Integrations & API · v1

Build with the relaii API

Use the relaii API to post notifications, update channel widgets or connect an application to your Space. Start with the quickstart below, then use the endpoint reference for the requests you need.

Replace https://chat.example.no in examples with your Space address. Use /api/integrations/v1 with an API key, /api/client/v1 with a user session, or your secret /hooks/:secret URL to post a webhook message.

Using an AI agent? Point it to api.md, a Markdown edition of this reference written for agents.

Choose an integration

Choose the smallest API that fits the job. A webhook posts notifications to one channel. A URL widget embeds a cached HTML page. A scoped API key posts bot messages and updates block widgets. The client API works with a user’s session.

Send your first request

Use the address of your own Space in every example. There is no central relaii API account or API host.

1. Check the Space

curl --fail-with-body --silent --show-error \
  https://chat.example.no/.well-known/relaii

This public request needs no credential. The response advertises the API URLs, protocol versions and supported capabilities.

2. Create an integration key

Open Admin → API keys in your Space. Name a bot, grant it post_messages, and copy the key — the permission applies to every channel on the Space, so any channel’s ID works below. Set RELAII_API_KEY in your shell or secret manager and replace ROOM_ID with that channel’s ID.

3. Post a message

curl --fail-with-body --silent --show-error \
  https://chat.example.no/api/integrations/v1/rooms/ROOM_ID/messages \
  -H "Authorization: Bearer $RELAII_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"text":"Hello from my integration","client_message_id":"019c1234-5678-7000-8000-123456789abc"}'

Expect 201 with the message inside data. Generate a new UUID for each new message; reuse the same UUID when retrying that message. A successful retry returns 200.

A rak_… key works only on the integration API and only within the permissions it was granted — which apply to every local channel on the Space, not a selected subset. For a user’s rooms, messages and sync, follow client authentication.

If a request returns 401 or 403, check the API base path, credential type, key expiry and permissions.

Conventions

• Request and response bodies are JSON, UTF-8, unless noted.
• Timestamps are RFC 3339 with microseconds, always UTC: 2026-08-30T13:04:05.123456Z.
• Identifiers are UUIDv7 strings.
• Sequence numbers and cursors are JSON numbers (64-bit integers).
• Unknown fields in a response must be ignored. Fields are never removed or repurposed within v1.

Authentication

Two interchangeable mechanisms, both accepted on every authenticated client-API endpoint:

• Cookies (the web client). relaii_at and relaii_rt are HttpOnly, SameSite=Lax, and Secure on HTTPS. Unsafe methods must also send the CSRF token from relaii_csrf in the X-Relaii-CSRF header.
• Bearer (scripts and native clients). Authorization: Bearer <access_token>. No CSRF header is required.

Access tokens last 15 minutes. Refresh tokens last 30 days and rotate on every use: POST /auth/refresh returns a new refresh token and the presented one stops working.

Incoming webhooks do not use either mechanism. The secret in the path is the credential.

Errors

Every error uses the same envelope:

{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to post in this room.",
    "details": {}
  }
}

code is stable. message is English and may change. details is present only where noted.

Pagination

To fetch a list in pages, read { "data": [], "next_cursor": "…", "has_more": true }. When has_more is true, send the returned next_cursor as ?cursor=… in your next request. Treat cursors as opaque strings.

For message history, use before or after with a room_sequence value instead. See Messages for the response format and limits.

Discovery

Check your Space’s address, supported features and availability with these public endpoints. They do not require a session; use each full path shown below.

curl -s https://chat.example.no/.well-known/relaii

The document names client_api_url, federation_api_url, websocket_url, client_api_versions, federation_versions and a capabilities map (webhooks, search, federation, file_uploads, websocket, email, password_reset, push).

Incoming webhooks

Use a webhook to send notifications to one channel. Create it in that channel or through the management API, then copy its secret URL. Messages appear under the webhook’s bot name and support mentions, unread indicators and delivery to connected Spaces.

Webhooks can post messages in basic or blocks format. To create channels or manage members, use the client API with a user session. Neither webhook message format renders HTML.

@webhook_builder {
    path /hooks/*
    method POST OPTIONS
    header Origin https://relaii.app
}
header @webhook_builder {
    Access-Control-Allow-Origin https://relaii.app
    Access-Control-Allow-Methods POST
    Access-Control-Allow-Headers Content-Type
    Access-Control-Max-Age 600
    +Vary Origin
}
@webhook_builder_preflight {
    path /hooks/*
    method OPTIONS
    header Origin https://relaii.app
    header Access-Control-Request-Method POST
}
handle @webhook_builder_preflight {
    respond 204
}

Post a message

POST /hooks/:secret

Basic messages can be JSON or application/x-www-form-urlencoded. Block messages must be JSON because blocks is an array. The complete request body is capped at 64 KiB.

Basic messages

format defaults to basic, so the smallest valid body is { "text": "…" }.

curl -X POST https://chat.example.no/hooks/relaii_hook_… \
  -H 'content-type: application/json' \
  -d '{
    "format": "basic",
    "text": "Deploy **finished**",
    "name": "CI",
    "avatar_url": "https://ci.example.no/avatar.png",
    "external_id": "build-112"
  }'

Block messages

Set format to blocks and send 1–20 blocks in the order you want them displayed. Use the JSON fields in the table below. The validated block array must fit within 60 KiB.

{
  "format": "blocks",
  "name": "Release bot",
  "avatar_url": "https://ci.example.no/avatar.png",
  "blocks": [
    {
      "type": "title",
      "text": "Deployment complete"
    },
    {
      "type": "text",
      "text": "Build **412** passed all checks."
    },
    {
      "type": "image",
      "url": "https://ci.example.no/build-412.png",
      "alt": "Deployment summary"
    },
    {
      "type": "table",
      "columns": ["Service", "Status", "Version"],
      "rows": [
        ["API", "Healthy", "1.0.8"],
        ["Web", "Healthy", "1.0.8"]
      ]
    },
    {
      "type": "actions",
      "buttons": [
        {
          "text": "Open build",
          "url": "https://ci.example.no/builds/412"
        },
        {
          "text": "View logs",
          "url": "https://ci.example.no/builds/412/logs"
        }
      ]
    }
  ],
  "external_id": "build-412"
}

Use absolute http:// or https:// URLs for images, avatars and actions. Each URL can contain at most 2,048 characters and must have no whitespace or embedded credentials. A successful webhook request confirms the message was accepted; it does not confirm that linked images or pages are reachable.

{ "ok": true, "message_id": "019c…" }

Use the authenticated management endpoints to create, list, rotate or revoke webhooks. Save the secret URL when you create or rotate a webhook; you cannot retrieve it later. To receive message events in an application, use sync or WebSocket.

Embed a URL widget in a channel

URL widgets require relaii 1.0.14 or later. Open Admin → Widgets, select a local channel and add a widget. Enter its HTTPS URL, set any bearer token it requires, then choose its cache duration, lazy loading, height and enabled state. Channel managers can also use the channel’s Widgets view.

Layout controls depend on your installed version. If your Space offers an aspect ratio or maximum dimensions, use them to fit the embedded page to the channel. You need channel management permission and any separate widget permission required by your Space.

Host the widget as an HTML page at a public HTTPS address. relaii fetches and caches that page for channel members. If the page requires authentication, supply its bearer token; relaii sends it only to the configured URL. The token and cached page are encrypted on your Space.

Download the single-file PHP widget demo. Upload widget.php to your HTTPS web host and use its address as the widget URL. Try ?scenario=normal, ?scenario=busy or ?scenario=incident. The generation time and fetch ID make cache behavior visible.

Make the widget a self-contained HTML document: include its CSS and JavaScript inline, and embed images and fonts with data: URLs. The widget can run inline scripts but cannot access relaii, browser storage or external resources, submit forms or open popups. A page that depends on cookie login or additional network requests will not work. Use an Apple or Android app version that supports URL widgets to view it on those platforms.

Normal authenticated client sessions manage widgets at /api/client/v1:

POST /api/client/v1/rooms/:id/widgets
Content-Type: application/json

{
  "title": "Operations",
  "source_url": "https://dashboard.example.com/widget.php",
  "bearer_token": "optional-upstream-secret",
  "cache_seconds": 300,
  "lazy_load": true,
  "height": 420,
  "enabled": true
}

Cookie-authenticated writes require the usual CSRF header. On update, omit bearer_token to keep it or send an empty string to remove it. Responses include source_type: "url" and has_bearer_token. Both snapshot endpoints recheck channel access, even when content is cached. Expired snapshots are not served after a failed refresh.

API keys and block widgets

To create a key, open Admin → API keys in the web app. Choose a name, a bot name, an expiry and one or more permissions, then copy the secret into your integration’s secret store. It is shown only once. Use the key list to check last use, edit its permissions, or revoke a key you no longer need. Revoking deactivates the bot; its earlier messages keep it as their sender.

Machine requests use Authorization: Bearer rak_… and the separate base path /api/integrations/v1. Each permission — create_channels, edit_channels, close_channels, manage_members, create_webhooks, manage_widgets and post_messages — applies to every local channel on the Space, not a selected subset; the key’s bot is seated in a channel automatically the first time it acts there. A channel shared with other Spaces is reachable only by keys on the Space that owns it — never a guest Space’s key. Keys cannot sign in as a user or access administration. A key has its own bot identity.

A key with manage_widgets can create the block widget itself, or you can create one from a user session at POST /api/client/v1/rooms/:id/widgets with channel management permission. Either way, save the returned widget ID; your integration can then update it in place:

PUT /api/integrations/v1/rooms/:id/widgets/:widget_id
Authorization: Bearer <integration-key>
Content-Type: application/json

{
  "revision": 1,
  "stale_after_seconds": 300,
  "blocks": [
    {"type": "metric", "label": "Availability", "value": "99.98%", "status": "good"},
    {"type": "chart", "label": "Requests", "unit": "req/min", "points": [
      {"label": "12:00", "value": 125},
      {"label": "12:01", "value": 148}
    ]}
  ]
}

Increase the integer revision for each update. Repeating the same revision and content is safe; stale or conflicting revisions return 409. Read the latest revision before retrying a conflict. Widgets also support the existing text, title, image, table and action blocks. There are at most 20 blocks, 120 chart points and 60 KiB of normalized block data. Block payloads do not accept HTML or scripts; use URL widgets to embed a self-contained HTML document.

Each update replaces the widget’s displayed data and refreshes it for people viewing the channel. Set stale_after_seconds to show when that data is overdue for an update. Widget updates do not create chat messages, unread counts or push notifications. Access follows the channel’s permissions; send updates to the Space that owns the channel.

To manage keys programmatically, use an administrator’s session with GET, POST, PATCH or DELETE on /api/client/v1/admin/api-keys[/:id]. PATCH renames a key, renames its bot, or changes its permissions. After revoking a key, requests using it will no longer be accepted.

Every key in those responses includes bot_avatar_url: the address of the key’s bot avatar, or null for the default. To give the bot an avatar, use the same administrator session with the endpoints below, relative to /api/client/v1. Avatar changes take effect immediately; they are not part of PATCH.

Client API

Send client requests to https://YOUR_SPACE/api/client/v1 using a user session. Paths in the following client tables are relative to that base. Replace placeholders such as :id with the relevant ID from an earlier response. Before initial setup is complete, protected endpoints return 403 setup_required; use /setup/status to check and /setup/admin to create the owner account.

Authentication and session

Successful login, setup and accepting an invitation return the same session shape. If login returns data.mfa_required: true, first exchange data.mfa_token and a TOTP or recovery code at POST /auth/mfa to receive the session. A browser uses the cookies; a script uses the tokens in the body. The server always sends both.

curl -s https://chat.example.no/api/client/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"login": "chris", "password": "…"}'

If the Space requires MFA enrollment, protected endpoints return 403 mfa_enrollment_required until the user completes setup. Profile, logout and MFA enrollment endpoints remain available.

Rooms and channels

Use room endpoints to create and manage conversations. Set kind to channel for a channel, direct for a one-to-one conversation, or group_direct for a group conversation. These requests require a user session.

Create a channel

POST /api/client/v1/rooms
{
  "kind": "channel",
  "name": "prosjekt-x",
  "topic": "Kundeprosjekt",
  "visibility": "private",
  "member_ids": ["019c…"]
}

name is required, 1–80 characters. The slug is derived from it (prosjekt-x) unless you send slug yourself — lowercase letters, digits and dashes. visibility is private (default) or public. A public channel is listed for everyone on the server. The creator becomes the room owner. Named members are added afterwards; a failed invite does not fail the creation.

Your account must have permission to create channels (create_channels). If the requested slug is already in use, the response is 422 with a validation error for slug; choose another slug and retry.

To open a direct conversation, send { "kind": "direct", "user_id": "…" }. If the conversation already exists, you receive that room. For a group, send kind: "group_direct" and at least two other people in member_ids or qualified_ids.

Rename, archive, restore

PATCH /api/client/v1/rooms/:id
{ "name": "prosjekt-y", "topic": "…", "visibility": "public", "archived": true }

To archive a room, send archived: true or an explicit archived_at timestamp. Its history remains readable, but new messages and webhook posts are rejected. Send archived: false to restore the room.

Delete

DELETE /api/client/v1/rooms/:id

Deleting a room sets deleted_at, removes it from room listings and prevents new writes. This action does not erase its stored message history.

Members

POST /api/client/v1/rooms/:id/members
{ "member_ids": ["019c…"], "qualified_ids": ["alex@chat.partner.no"], "role": "member" }

Identify the people to add with user_id, member_ids or qualified_ids (name@server). For a single person in an array field, send a one-item array. Choose owner, moderator, member or guest. Unless you are an administrator, you cannot grant a role above your own. Repeating an add request does not duplicate membership. Send membership changes to the Space that owns the room.

notification_preference on a membership is the room override: default, all, mentions or muted.

Messages

POST /api/client/v1/rooms/:id/messages
{
  "text": "Hei",
  "client_message_id": "b3f1…",
  "attachment_ids": []
}

Generate a UUID for client_message_id for each new message. Reuse that UUID when retrying so the response returns the original message without posting a duplicate. Treat text as plain text when displaying it, even if it contains HTML. For shared rooms, relaii forwards the request to the owning Space. If it returns 503 because that Space is unavailable, retry later with the same UUID.

An archived room takes no new messages (client API or webhook).

Files

Three steps, identical whether storage is local disk or S3. Quota is charged at step 1.

1. POST /rooms/:id/uploads with { "filename", "mime_type", "byte_size" } → attachment plus { "method": "PUT", "url", "headers", "expires_at" }.
2. PUT the bytes to upload.url with upload.headers. That request does not carry relaii credentials — the URL is the credential. Local storage uses /files/v1/:id/content; S3 uses the bucket directly.
3. POST /uploads/:id/finalize with an optional { "checksum" }. Then put attachment.id in attachment_ids when posting the message.

Attachment status is pending, uploaded, scanning, ready, blocked or deleted. Only ready is downloadable. In a channel homed elsewhere the three steps are forwarded; the quota charged is the homeserver’s.

Search

GET /search?q=…&limit=…&cursor=…

Combine search text with from:username, in:#channel, before:YYYY-MM-DD, after:YYYY-MM-DD and has:file. URL-encode the complete query. Results include only rooms the signed-in user can read.

Sync and WebSocket

GET /sync?since=<cursor>&limit=<n>

{
  "events": [],
  "cursor": 18460,
  "has_more": false,
  "rooms": [],
  "reset": false
}

since=0 (or a missing since) is a full bootstrap: the current room list and cursor, no events. Load history per room afterwards. reset: true means the cursor is older than retained history — discard the cache and bootstrap again.

Store the last cursor you have processed and send it as since when requesting further events. Process returned events in order before advancing your saved cursor.

WebSocket: wss://<server>/socket/v1/websocket?token=<socket_token>. Phoenix channels:

• user:<user_id> — every durable event for rooms the user belongs to, plus presence.changed.
• room:<room_id> — the same durable events for that room, plus typing.*.

Both topics deliver the Event shape under the message name event. Join the user topic with { "since": <cursor> }; the reply includes cursor and missed. If missed is non-zero, call /sync to catch up. Use WebSocket for live updates and /sync to recover missed events after reconnecting.

Client-to-server on a room topic: typing ({ "typing": true|false }) and read ({ "sequence": n }). Both are best-effort.

Durable event types:

Ephemeral, WebSocket only, never persisted: typing.started, typing.stopped, presence.changed. They have no cursor.

Managing webhooks

Use a user session with manage permission in the room. Creating a webhook also requires the Space’s create_webhooks permission. Create and manage webhooks on the Space that owns the channel.

Bot avatar changes take effect immediately. For a revoked or unknown webhook, the avatar endpoints return 404.

Create and rotate return the secret once, with Cache-Control: no-store:

{
  "webhook": {
    "id": "019c…",
    "room_id": "019c…",
    "name": "Deploy",
    "secret_prefix": "relaii_h",
    "bot_user_id": "019c…",
    "bot_avatar_url": null,
    "enabled": true,
    "rate_limit_per_minute": 60,
    "last_used_at": null,
    "created_at": "2026-08-30T13:04:05.123456Z"
  },
  "secret": "relaii_hook_…",
  "url": "https://chat.example.no/hooks/relaii_hook_…"
}

Each webhook posts under its own bot account in the channel. If you lose the secret URL, rotate it and update your integration with the new URL. Rotation invalidates the old URL immediately.

Every webhook object — in lists, in these responses and from the integration API — includes bot_avatar_url, the bot account’s avatar or null. A per-message avatar_url in a webhook request still overrides it for that message.

Channel sharing

Send sharing requests to the Space that owns the channel. You need share permission, federation must be enabled, and the destination Space must already be paired. See the federation guide to set up a connection.

Users, invitations, devices

Native clients register an opaque push_device_id from notifications.relaii.app. The platform device token never appears on these endpoints. Push is optional: chat and federation work without it.

Admin API

Use an administrator’s session. The paths below include /admin; append them to /api/client/v1. For example, request GET /api/client/v1/admin/settings. Key rotation and ownership transfer require the Space owner’s account.

Federation API

Use /api/federation/v1 for communication between paired Spaces. To post bot messages, use the integration API. Pairing requires approval from both Space administrators. After pairing, sign requests with the peer’s Ed25519 key; the public ping, key discovery and initial pairing endpoints are used to establish that connection.

For a shared room, send changes to its owning Space, also called its homeserver. It returns the room_sequence for each accepted message and manages membership and files. Other Spaces forward their users’ requests to it and receive the resulting events.

If you are connecting two existing relaii Spaces, use Admin → Federation and follow the pairing guide; relaii handles request signing. The optional push gateway uses a separate endpoint, POST /api/push/v1/challenge, with the challenge prefix RELAII-PUSH-CHALLENGE. Use that prefix only for push gateway challenges.

Entities

Use these response shapes when reading lists, sync events and WebSocket messages. IDs and nested objects are abbreviated in the examples; use complete values returned by your Space in requests.

User

{
  "id": "019c…",
  "username": "chris",
  "display_name": "Chris",
  "qualified_id": "chris@chat.example.no",
  "server_id": "chat.example.no",
  "is_local": true,
  "is_bot": false,
  "is_admin": true,
  "is_owner": true,
  "status": "active",
  "avatar_url": null,
  "last_seen_at": "2026-08-30T13:00:00.000000Z"
}

A remote user has is_local: false and is_admin / is_owner always false. GET /auth/me additionally returns email, timezone, notification_preference and onboarding_completed_at. No endpoint returns another user’s email to a non-admin.

A bot account (is_bot: true) can have an avatar_url on another host, set by whoever manages its API key or webhook. Treat it as an external image: loading it shares the reader’s IP address with that host.

Room

{
  "id": "019c…",
  "kind": "channel",
  "name": "prosjekt-x",
  "slug": "prosjekt-x",
  "topic": "Kundeprosjekt",
  "visibility": "private",
  "owner_server_id": "chat.example.no",
  "is_local": true,
  "is_shared": true,
  "shared_with": ["chat.partner.no"],
  "last_sequence": 733,
  "member_count": 12,
  "archived_at": null,
  "created_at": "2026-08-01T09:00:00.000000Z",
  "my_membership": {
    "role": "owner",
    "joined_at": "2026-08-01T09:00:00.000000Z",
    "muted": false,
    "notification": "default"
  },
  "unread": { "count": 3, "mentions": 1, "last_read_sequence": 730 }
}

For direct and group_direct, name is null — clients render the participants. shared_with is present only for rooms this server owns.

Member

{
  "id": "019c…",
  "role": "member",
  "joined_at": "2026-08-02T10:00:00.000000Z",
  "muted": false,
  "user": { }
}

Message

{
  "id": "019c…",
  "room_id": "019c…",
  "room_sequence": 733,
  "text": "Hei",
  "sender": { },
  "sender_override": null,
  "client_message_id": "b3f1…",
  "mentions": ["019c…"],
  "mentions_everyone": false,
  "attachments": [],
  "edited_at": null,
  "deleted_at": null,
  "created_at": "2026-08-30T13:04:05.123456Z"
}

When deleted_at is set, display the message as deleted and retain its sequence for synchronization. sender_override contains the sender supplied for an individual webhook message.

Attachment

{
  "id": "019c…",
  "room_id": "019c…",
  "message_id": "019c…",
  "filename": "rapport.pdf",
  "mime_type": "application/pdf",
  "byte_size": 184320,
  "checksum": "sha256:9f86d0…",
  "status": "ready",
  "created_at": "2026-08-30T13:04:00.000000Z"
}

Download URLs are never embedded. Fetch them from GET /attachments/:id/download.

Event

{
  "type": "message.created",
  "event_id": "019c…",
  "cursor": 18421,
  "room_id": "019c…",
  "room_sequence": 733,
  "created_at": "2026-08-30T13:04:05.123456Z",
  "payload": {}
}

Running a server

Start in the Docs page for installation, configuration, backups and troubleshooting. See updates and backups before changing a running Space, or the federation guide to connect two Spaces.

For authentication failures, start with the quickstart checks. For missed messages or reconnects, follow Sync and WebSocket. For server health and access problems, use the troubleshooting guide.

Security

Keep webhook URLs, API keys and session tokens secret. Use HTTPS and grant integration keys only the permissions they need — a permission applies to every channel on the Space. See authentication conventions for cookies and bearer tokens, and the security guide for the server’s encryption model.