folkwaysDocs
JavaScript SDKAPI reference

REST endpoints

Reference for the node's backend endpoints — POST /v1/dm/open, POST /v1/members/*, POST /v1/kick and POST /v1/revoke — with requests, answers and errors.

Your backend calls these endpoints on the node's HTTP address (the same url as Folkways.Rest). They take and return JSON, and authenticate with a service token (kind: 'service') in Authorization: Bearer. The segment always comes from the token, never from the request.

None of them allow browser origins (no CORS): only backends hold service tokens.

Errors are JSON { "code", "error", "message" } with the code's HTTP status, e.g. {"code":203,"error":"Forbidden","message":"not allowed"}. A 429 also has retry_after_ms in the body and a Retry-After header in seconds. Unknown fields in a request body are refused with InvalidArgument. Codes are listed in Error codes.

POST /v1/dm/open

Opens (or finds) the room for a set of members and invites each of them on their personal topic $user/{identity}. Guide: Direct messages and group rooms.

Token: kind: 'service', with publish on the room (e.g. dm/*) and on every member's $user/{identity} (e.g. $user/>).

POST /v1/dm/open
Authorization: Bearer <service token>
Content-Type: application/json

{ "members": ["user:1", "user:2"], "prefix": "dm", "data": { "startedBy": "user:1" } }
FieldTypeDefaultMeaning
membersstring[]required2 to 50 different identities, each one topic level (A-Z a-z 0-9 . _ ~ : @ = + -, no /)
prefixstring"dm"The room is {prefix}/{id}, and must match one of the segment's topic rules
dataany JSONnullPassed on in every invite

200 OK

{
  "topic": "dm/5f0c8e1d2a9b44c7e1f03a6d",
  "members": ["user:1", "user:2"],
  "invites": [
    { "identity": "user:1", "topic": "$user/user:1", "duplicate": false },
    { "identity": "user:2", "topic": "$user/user:2", "duplicate": false }
  ]
}

topic is the same every time for the same members in the same segment. duplicate: true means the same invite was already sent within the last 10 minutes and was not sent again. Each invite is an invite Stream event with data { "type": "dm", "topic", "members", "data" }.

StatusErrorWhen
401AuthRequired, AuthInvalid, AuthExpired, AuthRevokedNo token, or a bad, expired or revoked one
403ForbiddenNot a service token; no rule for the room; no publish on the room or on a member's $user/{identity}. Nobody is invited
403SuspendedThe segment's subscription is suspended
400InvalidArgumentThe body isn't as above; fewer than 2 or more than 50 members; an identity that can't have a personal topic
400InvalidTopicprefix isn't a topic name, or the room name would be too long
429QuotaExceededTopic limit, personal topic limit, monthly cap or plan allowance reached. Nobody is invited
429RateLimitedThe segment's service budget (one unit per member, refilling at the segment's per-connection publish rate, holding 64) or a publish rate can't take the request yet. Nothing was sent
503Draining, UnavailableThe node is shutting down, or can't load the segment's settings. For a members-only room: its member list couldn't be read or stored, and nobody was invited

Members-only rooms. When the room's rule is Members only, the node first puts the members who aren't on the room's member list yet on it, with every operation the rule allows, and stores them before the first invite goes out. Members already on the list keep their entry, so opening the room again never undoes a block set with /v1/members/set. Each member's token must still allow what they do in the room.

If an invite fails part-way, the members before it already have theirs. Send the same request again: those come back duplicate: true and only the rest are sent.

POST /v1/members/*

Says who may use a private topic (one whose rule is Members only), and with which operations. In such a topic a user may do what their token, the rule's operations and their member entry all allow, so tokens don't list rooms and a new token can't undo a removal. Service tokens need no entry.

Token: kind: 'service', with publish on the topic (e.g. private/* or dm/*).

POST /v1/members/add
Authorization: Bearer <service token>
Content-Type: application/json

{ "topic": "dm/7f3a9c", "identities": ["user:1", "user:2"], "ops": ["subscribe", "publish", "set", "signal"] }
EndpointBodyDoes
/v1/members/add{ topic, identities, ops }Each identity gets exactly ops, whether or not it was a member
/v1/members/set{ topic, identity, ops }The same for one identity. Narrow it to block someone: ["subscribe"] can read but not send
/v1/members/remove{ topic, identities }The identities lose every right in the topic. Not being a member is not an error
/v1/members/clear{ topic }Everyone does: the room is closed
/v1/members/list{ topic }Answers 200 { "topic", "members": [{ "identity", "ops" }] }, by identity
FieldMeaning
topicA topic name (not a pattern, not a $ topic) matched by a Members only rule
identities, identityToken subs, each one topic level (A-Z a-z 0-9 . _ ~ : @ = + -, no /). 1 to 1,000 per request
opsAt least one of subscribe, publish, set, signal, history, presence. To take every right away, remove the member

204 No Content (200 with the list for /list), once the change is stored. A change takes effect in this order:

  1. Whatever it takes away applies at once. A removed member's subscriptions to the topic end with Forbidden, a long-poll it has waiting there returns with Forbidden, and its next publish, subscribe or poll there is refused, whatever token it holds or fetches next. A member narrowed to ["subscribe"] keeps its subscription and can no longer write.
  2. The change is stored, so it survives a restart of the node.
  3. Then whatever it grants applies, and the request is answered.
StatusErrorWhen
401AuthRequired, AuthInvalid, AuthExpired, AuthRevokedNo token, or a bad, expired or revoked one
403ForbiddenNot a service token; no rule for the topic; no publish on it in the token or the rule
403SuspendedThe segment's subscription is suspended
400InvalidArgumentThe body isn't as above, or the topic's rule isn't Members only (its token decides, and it has no member list)
429QuotaExceededThe topic would hold more than 10,000 members; nothing changed
429RateLimitedThe segment's service budget (one unit per request, shared with /v1/dm/open, /v1/kick and /v1/revoke) is empty
503UnavailableThe change couldn't be stored. What it took away still holds on this node and is stored on a retry; what it granted doesn't apply. Sending the request again is safe

A change applies on the node that receives it. The first time a topic is used after a restart, the node reads its list back; while it can't, the topic's clients get Unavailable, never access.

POST /v1/kick and POST /v1/revoke

Cut off one user, or one token, before the token expires. Guide: Kick and revoke.

  • POST /v1/kick closes every connection of one identity in the segment with AuthRevoked, within a second. The identity's tokens still work.
  • POST /v1/revoke closes every connection holding the token with that jti, anonymous ones included, with AuthRevoked, and refuses the token from then on (connecting, updateToken, publishing, polling and /v1/dm/open) until it would have expired. Tokens without a jti can't be revoked.

Both apply to the node that receives the request only, and are kept in its memory: send them to every node your segment's clients connect to.

POST /v1/kick
Authorization: Bearer <service token with publish on $user/user:42>
Content-Type: application/json

{ "identity": "user:42" }
POST /v1/revoke
Authorization: Bearer <service token with publish on $user/>>
Content-Type: application/json

{ "jti": "9b1d3c0e-tok" }
EndpointFieldTypeMeaning
/v1/kickidentitystringThe token sub to cut off; one topic level, no /
/v1/revokejtistringThe token id to revoke, 1 to 256 bytes

Token: kind: 'service'. Kicking needs publish on the identity's $user/{identity}; revoking needs publish on all of $user/>.

204 No Content, with no body, whether or not anyone was connected and whether or not the identity or token was ever seen.

StatusErrorWhen
401AuthRequired, AuthInvalid, AuthExpired, AuthRevokedNo token, or a bad, expired or revoked one
403ForbiddenNot a service token, or without the right above. The same answer for every identity
403SuspendedThe segment's subscription is suspended
400InvalidArgumentThe body isn't as above
429QuotaExceeded/v1/revoke only: the segment already holds 10,000 revocations on this node. Room comes back as they expire (at most 16 minutes)
429RateLimitedThe segment's service budget (one unit per request, shared with /v1/dm/open and /v1/members/*) is empty
503UnavailableThe node can't load the segment's settings

Both keep working while the node shuts down, so its remaining connections can still be cut off.

On this page