Skip to main content
POST
Create an invite link

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

room_id
string<uuid>
required

Body

application/json

Mint an invite link for a room, bounded in time and in uses.

Both fields are required: how long a shareable credential lives, and how many guests it lets in, are the only two things that bound a link once it leaves your hands, so they are yours to state rather than ours to default. A leaked link is bounded by exactly what you asked for here — and by DELETE /v1/rooms/{room_id}/invites, which retires the room's links at once and takes effect immediately.

Each field also has a server-side ceiling (30 days, 100 uses). They are not a policy about how you should run your calls — they are the outer edge of what a single unauthenticated bearer capability may be, and they are what keeps an out-of-range value a 422 naming the bound instead of a number the database cannot hold. If you need more than either allows, mint another link.

expires_in_seconds
integer
required

How long the link stays usable, in seconds from now, counted on the server's clock. Required — there is no default, because a link that outlives the conversation it was for is the one mistake this field exists to prevent. After it passes, the link returns 410 and cannot be renewed; mint a new one.

At most 30 days (2,592,000). A shareable credential nobody has to re-authorize should not outlive the quarter it was made in, and the cap is also what stops a value large enough to overflow the stored timestamp from reaching the database at all.

Required range: 60 <= x <= 2592000
Example:

3600

max_uses
integer
required

How many times this link may be redeemed. Required, and there is no unlimited option. Send 1 for a link meant for one guest — the common case, and the one where a forwarded link cannot let a stranger in behind them. A higher number admits that many separate guests.

This bounds the link, not the room: a room itself has no participant limit, so mint a link with the number of uses you actually intend to hand out, or several links, as suits you. The room's only limit is that everyone in it must be speaking at most two languages between them.

At most 100. One link admitting an unbounded crowd is a different kind of credential from the one this endpoint issues; mint several if you need to hand out more, so that a single leak costs you at most one of them.

Required range: 1 <= x <= 100
Example:

1

Response

Successful Response

A minted invite link.

invite_code is shown here and nowhere else. Only a hash of it is stored, so it cannot be read back from any endpoint — put it in the link you send your guest, and save it if you will need it again. Losing it costs you nothing you cannot undo: DELETE /v1/rooms/{room_id}/invites retires the room's links without it.

Build the guest's URL yourself, pointing at your own page: that page reads the room's state from GET /v1/invites/{invite_code} and joins through POST /v1/invites/{invite_code}/join. Keep the code in the URL's path, not its query string, so it does not travel to third parties in a Referer header.

invite_code
string
required
expires_at
string<date-time>
required
max_uses
integer
required