# REST endpoints

URL: https://docs.folkways.io/docs/js-sdk/reference/rest

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](/docs/js-sdk/reference/error-codes).

## `POST /v1/dm/open` [#post-v1dmopen]

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](/docs/js-sdk/direct-messages).

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

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

{ "members": ["user:1", "user:2"], "prefix": "dm", "data": { "startedBy": "user:1" } }
```

| Field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `members` | `string[]` | required | 2 to 50 different identities, each one topic level (`A-Z a-z 0-9 . _ ~ : @ = + -`, no `/`) |
| `prefix` | `string` | `"dm"` | The room is `{prefix}/{id}`, and must match one of the segment's topic rules |
| `data` | any JSON | `null` | Passed on in every invite |

**`200 OK`**

```json
{
  "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" }`.

| Status | Error | When |
| --- | --- | --- |
| `401` | `AuthRequired`, `AuthInvalid`, `AuthExpired`, `AuthRevoked` | No token, or a bad, expired or revoked one |
| `403` | `Forbidden` | Not a service token; no rule for the room; no `publish` on the room or on a member's `$user/{identity}`. Nobody is invited |
| `403` | `Suspended` | The segment's subscription is suspended |
| `400` | `InvalidArgument` | The body isn't as above; fewer than 2 or more than 50 members; an identity that can't have a personal topic |
| `400` | `InvalidTopic` | `prefix` isn't a topic name, or the room name would be too long |
| `429` | `QuotaExceeded` | Topic limit, personal topic limit, monthly cap or plan allowance reached. Nobody is invited |
| `429` | `RateLimited` | The 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 |
| `503` | `Draining`, `Unavailable` | The 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`](#post-v1members). 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/*` [#post-v1members]

Says who may use a [private topic](/docs/js-sdk/private-topics) (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/*`).

```http
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"] }
```

| Endpoint | Body | Does |
| --- | --- | --- |
| `/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 |

| Field | Meaning |
| --- | --- |
| `topic` | A topic name (not a pattern, not a `$` topic) matched by a **Members only** rule |
| `identities`, `identity` | Token `sub`s, each one topic level (`A-Z a-z 0-9 . _ ~ : @ = + -`, no `/`). 1 to 1,000 per request |
| `ops` | At 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.

| Status | Error | When |
| --- | --- | --- |
| `401` | `AuthRequired`, `AuthInvalid`, `AuthExpired`, `AuthRevoked` | No token, or a bad, expired or revoked one |
| `403` | `Forbidden` | Not a service token; no rule for the topic; no `publish` on it in the token or the rule |
| `403` | `Suspended` | The segment's subscription is suspended |
| `400` | `InvalidArgument` | The body isn't as above, or the topic's rule isn't **Members only** (its token decides, and it has no member list) |
| `429` | `QuotaExceeded` | The topic would hold more than 10,000 members; nothing changed |
| `429` | `RateLimited` | The segment's service budget (one unit per request, shared with `/v1/dm/open`, `/v1/kick` and `/v1/revoke`) is empty |
| `503` | `Unavailable` | The 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` [#post-v1kick-and-post-v1revoke]

Cut off one user, or one token, before the token expires. Guide: [Kick and revoke](/docs/js-sdk/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.

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

{ "identity": "user:42" }
```

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

{ "jti": "9b1d3c0e-tok" }
```

| Endpoint | Field | Type | Meaning |
| --- | --- | --- | --- |
| `/v1/kick` | `identity` | `string` | The token `sub` to cut off; one topic level, no `/` |
| `/v1/revoke` | `jti` | `string` | The 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.

| Status | Error | When |
| --- | --- | --- |
| `401` | `AuthRequired`, `AuthInvalid`, `AuthExpired`, `AuthRevoked` | No token, or a bad, expired or revoked one |
| `403` | `Forbidden` | Not a service token, or without the right above. The same answer for every identity |
| `403` | `Suspended` | The segment's subscription is suspended |
| `400` | `InvalidArgument` | The body isn't as above |
| `429` | `QuotaExceeded` | `/v1/revoke` only: the segment already holds 10,000 revocations on this node. Room comes back as they expire (at most 16 minutes) |
| `429` | `RateLimited` | The segment's service budget (one unit per request, shared with `/v1/dm/open` and `/v1/members/*`) is empty |
| `503` | `Unavailable` | The 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.
