Client API

Send

Needs chat:send. Each principal may send 30 messages per 10 seconds, a limit shared with the WebSocket send path. Resending a client_message_id (1–128 characters) returns the original message with duplicate: true and writes, publishes and meters nothing. A new message commits with a durable message.created event. The event goes to the room's sockets and to subscribed webhooks, and members who are offline and not muted get a push. A mention gets through a mute, and in an e2ee room the push carries no sender or preview. Plain rooms accept the kinds text, image, voice, video, story, file and system, with a body of at most 16 KiB and at most 50 active members in body.mentions. E2EE rooms accept only mls.* kinds, with a body of exactly {"ct": <base64>} up to 128 KiB; sending the other room type's kinds returns 409. attachment_ids takes at most 10 attachments from this room, and each must be ready (409 otherwise). reply_to must be a message in this room. With forward_of, the server ignores kind, body and attachment_ids and copies the kind, body and media of a non-deleted message from a room the sender is in, dropping its mentions. An e2ee room cannot receive a forward.

postMessage captured live

Request

curl -X POST https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/messages \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"client_message_id":"c-9f3b7e21","kind":"text","body":{"text":"Hey — are we still on for 3pm?"}}'

{
  "client_message_id": "c-9f3b7e21",
  "kind": "text",
  "body": {
    "text": "Hey — are we still on for 3pm?"
  }
}

Request fields

Response · 200

{
  "duplicate": false,
  "message": {
    "body": {
      "text": "Hey — are we still on for 3pm?"
    },
    "client_message_id": "c-9f3b7e21",
    "created_at": "2026-01-15T09:30:06Z",
    "event_seq": 5202,
    "id": "e8b186e4-845a-41dc-bb28-102dd8d0cb8d",
    "kind": "text",
    "room_id": "25964f12-9ae9-4356-80e8-69bc5f749bd1",
    "sender_id": "alice"
  }
}

History (after_seq / before_seq / limit)

Needs chat:history. limit defaults to 100 and is capped at 500. after_seq returns the messages after that event_seq (exclusive), oldest first. before_seq on its own returns the limit messages just before it, still oldest first, for scrolling back. With both set, the page starts after after_seq and stops before before_seq. Unlike the WebSocket catchup, this endpoint adds no overlap window. Deleted messages stay in the page as tombstones (kind deleted, body null). Each message includes its attachments and reaction aggregates, and latest_seq is the room's newest event_seq. In an e2ee room the bodies are the stored mls.* ciphertext.

listMessages captured live

Request

curl -X GET https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/messages?limit=20 \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…"

Response · 200

{
  "messages": [
    {
      "id": "e0b25ea0-1320-4862-af8d-bc28a2547b27",
      "event_seq": 5200,
      "room_id": "25964f12-9ae9-4356-80e8-69bc5f749bd1",
      "sender_id": "support-bot",
      "sender_kind": "agent",
      "client_message_id": "srv-8c1f2a",
      "kind": "text",
      "body": {
        "text": "Your order #7781 has shipped."
      },
      "created_at": "2026-01-15T09:30:04Z"
    },
    {
      "id": "e8b186e4-845a-41dc-bb28-102dd8d0cb8d",
      "event_seq": 5202,
      "room_id": "25964f12-9ae9-4356-80e8-69bc5f749bd1",
      "sender_id": "alice",
      "client_message_id": "c-9f3b7e21",
      "kind": "text",
      "body": {
        "text": "Hey — are we still on for 3pm?"
      },
      "created_at": "2026-01-15T09:30:06Z"
    }
  ],
  "latest_seq": 5202
}

Edit (author only)

Editing a message to the body it already has changes nothing: the same message is returned with 200, edited_at does not move and no second message.updated is published, so a client that resends after losing an ack does not turn one edit into two versions.

editMessage captured live

Request

curl -X PATCH https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/messages/e8b186e4-845a-41dc-bb28-102dd8d0cb8d \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"body":{"text":"Hey — are we still on for 3:30pm?"}}'

{
  "body": {
    "text": "Hey — are we still on for 3:30pm?"
  }
}

Request fields

Response · 200

{
  "message": {
    "body": {
      "text": "Hey — are we still on for 3:30pm?"
    },
    "client_message_id": "c-9f3b7e21",
    "created_at": "2026-01-15T09:30:06Z",
    "edited_at": "2026-01-15T09:30:06Z",
    "event_seq": 5202,
    "id": "e8b186e4-845a-41dc-bb28-102dd8d0cb8d",
    "kind": "text",
    "room_id": "25964f12-9ae9-4356-80e8-69bc5f749bd1",
    "sender_id": "alice"
  }
}

Soft delete

The sender may delete their own message, and an owner of the room anyone's — a group admin removing a message — read from the membership when the delete happens, so a demoted owner cannot. Anyone else gets 404, as for an id that does not exist. Idempotent: deleting a message that is already deleted returns the same tombstone with 200 and publishes no second event, so a client that resends after losing an ack is not told the deletion never happened.

deleteMessage captured live

Request

curl -X DELETE https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/messages/883e28db-e669-4fba-9a60-e071d1b79b8d \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…"

Response · 200

{
  "message": {
    "body": null,
    "client_message_id": "c-doomed",
    "created_at": "2026-01-15T09:30:08Z",
    "deleted_at": "2026-01-15T09:30:08Z",
    "event_seq": 5204,
    "id": "883e28db-e669-4fba-9a60-e071d1b79b8d",
    "kind": "deleted",
    "room_id": "25964f12-9ae9-4356-80e8-69bc5f749bd1",
    "sender_id": "alice"
  }
}

Full-text search within the room

Needs chat:history. q must be 1–256 bytes after trimming. The search runs against body.text of messages that are not deleted, using PostgreSQL's simple configuration: there is no stemming and every word must match. Results are ordered by relevance, then newest first. limit defaults to 50 and is capped at 100, and there is no cursor for further pages. Results include attachments but not reactions.

searchMessages captured live

Request

curl -X GET https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/messages/search?q=invoice&limit=20 \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…"

Response · 200

{
  "messages": [
    {
      "id": "5c6e7377-ca7d-4567-9beb-dafb87d2a4d9",
      "event_seq": 5203,
      "room_id": "25964f12-9ae9-4356-80e8-69bc5f749bd1",
      "sender_id": "bob",
      "client_message_id": "c-searchable",
      "kind": "text",
      "body": {
        "text": "The quarterly invoice is attached."
      },
      "created_at": "2026-01-15T09:30:07Z"
    }
  ],
  "latest_seq": 5203
}

Add a reaction

Needs chat:send. emoji is trimmed and must be 1–8 characters and at most 32 bytes. A message holds at most 20 distinct emoji; once it has 20, every add returns 400. When the set changes, a durable reaction.added event { message_id, event_seq, principal_id, emoji } goes to the room's sockets and to subscribed webhooks; a repeat publishes nothing. In an e2ee room, clients send reactions as encrypted mls.application messages instead. In a direct conversation frozen by a block, the call returns 403 blocked.

addReaction captured live

Request

curl -X POST https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/messages/e8b186e4-845a-41dc-bb28-102dd8d0cb8d/reactions \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"emoji":"👍"}'

{
  "emoji": "👍"
}

Request fields

Response · 200

{
  "changed": true
}

Remove a reaction

Needs chat:send. It removes only the caller's own reaction with that emoji, which follows the same 1–8 character rule as adding. When a reaction was removed, a durable reaction.removed event goes to the room's sockets and to subscribed webhooks. Removing a reaction that is not there returns changed: false and publishes nothing. Like adding, it returns 409 in an e2ee room and 403 blocked in a direct conversation frozen by a block.

removeReaction captured live

Request

curl -X DELETE https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/messages/e8b186e4-845a-41dc-bb28-102dd8d0cb8d/reactions \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"emoji":"👍"}'

{
  "emoji": "👍"
}

Request fields

Response · 200

{
  "changed": true
}

Delivery receipt

Needs chat:send, so a viewer cannot post receipts. A principal's first delivery receipt for a message is recorded and publishes a durable receipt.delivered event { message_id, event_seq, principal_id } to the room's sockets and to subscribed webhooks. Posting it again returns advanced: false and publishes nothing. A delivery receipt does not change last_read_seq or the unread count.

receiptDelivered captured live

Request

curl -X POST https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/messages/e8b186e4-845a-41dc-bb28-102dd8d0cb8d/delivered \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…"

Response · 200

{
  "advanced": true
}

Read receipt (advances cursor)

Needs chat:send, so a viewer cannot post receipts. A principal's first read receipt for a message is recorded and publishes a durable receipt.read event { message_id, event_seq, principal_id } to the room's sockets and to subscribed webhooks. It also raises the member's last_read_seq to that message's event_seq (never lowering it); GET /v1/rooms/{room_id}/unread counts from that value. Posting it again returns advanced: false and publishes nothing. advanced is tracked per message, so a first receipt for an older message returns true without moving last_read_seq.

receiptRead captured live

Request

curl -X POST https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/messages/e8b186e4-845a-41dc-bb28-102dd8d0cb8d/read \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…"

Response · 200

{
  "advanced": true
}

Unread count and cursors

Needs only active membership. unread_count counts messages after last_read_seq that someone else sent and that are not deleted. last_read_seq moves only forward, and only through read receipts. latest_seq is the room's newest event_seq. E2EE rooms work the same way.

unread captured live

Request

curl -X GET https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/unread \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…"

Response · 200

{
  "unread_count": 0,
  "last_read_seq": 5202,
  "latest_seq": 5202
}

Room participants

Needs only active membership. Lists the room's current members (anyone who has left is excluded) with their role and an online flag. online is true while the member keeps a chat WebSocket open to this room; the presence heartbeat expires after 30 seconds. If presence cannot be read, every member is reported offline and the request still succeeds.

participants captured live

Request

curl -X GET https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/participants \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…"

Response · 200

{
  "participants": [
    {
      "principal_id": "alice",
      "role": "owner",
      "online": false
    },
    {
      "principal_id": "bob",
      "role": "member",
      "online": false
    },
    {
      "principal_id": "carol",
      "role": "member",
      "online": false
    },
    {
      "principal_id": "support-bot",
      "role": "member",
      "online": false
    }
  ]
}

Begin an upload

Needs attachment:upload. declared_mime must be a permitted type; an e2ee room accepts only application/octet-stream ciphertext and refuses poster_of. original_name must be 1–255 bytes with no /, \, NUL or ... byte_size must be between 1 and the deployment's MAX_UPLOAD_BYTES (100 MiB by default); a larger size returns 400. The monthly byte quota is checked against the declared size. poster_of marks an image as the poster of a video attachment in the same room. The response is a presigned PUT URL whose lifetime grows with the size, from 5 minutes to 2 hours, plus the headers to send with it. An upload that has not been completed and verified within 2 hours is deleted. Files larger than 5 MiB can use init-multipart instead.

initAttachment captured live

Request

curl -X POST https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/attachments/init \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"original_name":"invoice-q3.jpg","declared_mime":"image/jpeg","byte_size":160}'

{
  "original_name": "invoice-q3.jpg",
  "declared_mime": "image/jpeg",
  "byte_size": 160
}

Request fields

Response · 200

{
  "attachment_id": "ee86f695-3f58-48e2-9ca8-66ee9651ee3e",
  "upload_url": "https://files.example.com/objects/…?X-Amz-Signature=…",
  "upload_expires_at": "2026-01-15T09:35:10Z",
  "required_headers": [
    [
      "content-type",
      "application/octet-stream"
    ]
  ]
}

Finish and verify

Only the uploader may complete an upload (403 otherwise). The server checks that the object exists at exactly the declared byte_size (409 if it is missing or a different size). It then marks the attachment uploaded and queues a single verification job. That job re-checks the size, checks sha256 if one was declared and requires the leading bytes to match declared_mime; images also get a thumbnail. The result arrives as a durable attachment.ready or attachment.failed event; attachment.failed includes a reason, and the failed object is deleted. Only a ready attachment can be sent in a message or downloaded. Calling complete again after the attachment is ready returns 200 with status ready; calling it while verification is running, or after it failed, returns 409. In an e2ee room, ciphertext is checked only by size and the optional sha256.

completeAttachment captured live

Request

curl -X POST https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/attachments/ee86f695-3f58-48e2-9ca8-66ee9651ee3e/complete \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{}'

{}

Response · 200

{
  "attachment_id": "ee86f695-3f58-48e2-9ca8-66ee9651ee3e",
  "status": "uploaded"
}

Begin a multipart upload

Needs attachment:upload, and applies the same declared_mime, original_name, e2ee and monthly byte quota rules as init. byte_size must be over 5 MiB and at most the deployment's MAX_UPLOAD_BYTES (400 otherwise); smaller files use init. part_size defaults to 16 MiB and is clamped to 5–64 MiB. An upload may have at most 512 parts; going over returns 400 asking for a larger part_size. The file is split into part_size chunks, one per URL in order, with a shorter last chunk. Keep the ETag that each part's PUT returns, because complete-multipart needs it. All part URLs share one expires_at, 5 minutes to 2 hours depending on size. An upload not completed within 6 hours is aborted and deleted.

initMultipart captured live

Request

curl -X POST https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/attachments/init-multipart \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"original_name":"standup.mp4","declared_mime":"video/mp4","byte_size":5243904,"part_size":5242880}'

{
  "original_name": "standup.mp4",
  "declared_mime": "video/mp4",
  "byte_size": 5243904,
  "part_size": 5242880
}

Request fields

Response · 200

{
  "attachment_id": "2b575b88-88bb-40d0-b616-57536b782806",
  "upload_id": "ZTY5ODdmMjMtMGI1OS00Y2QxLTk5MzYtNzllZjk2YjdiZDY5LmZkZGEzZGE4LTJmYjUtNDJjZS1iY2E2LTk4ZDhiZjM3NGJkOXgxNzkyMzI0Njc1MTk1NzY5NDk1",
  "part_size": 5242880,
  "part_urls": [
    "https://files.example.com/objects/…?X-Amz-Signature=…",
    "https://files.example.com/objects/…?X-Amz-Signature=…"
  ],
  "expires_at": "2026-01-15T09:35:12Z"
}

Finish multipart

Only the uploader may complete an upload, and only while the attachment is still pending. Unlike complete, a retry after a successful completion returns 409. parts lists 1–512 { part_number, etag } pairs. An empty or oversized list returns 400; a list the object store rejects, such as one with a missing part or a wrong ETag, returns 409. The reassembled object must match the declared byte_size exactly (409 otherwise). The attachment then becomes uploaded and goes through the same verification as a single-part upload, ending in a durable attachment.ready or attachment.failed event.

completeMultipart captured live

Request

curl -X POST https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/attachments/2b575b88-88bb-40d0-b616-57536b782806/complete-multipart \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"parts":[{"part_number":1,"etag":"b8fc857a25e7958868c2f003d5e0952d"},{"part_number":2,"etag":"e9f8000caffbce369d7fee9c07d43509"}]}'

{
  "parts": [
    {
      "part_number": 1,
      "etag": "b8fc857a25e7958868c2f003d5e0952d"
    },
    {
      "part_number": 2,
      "etag": "e9f8000caffbce369d7fee9c07d43509"
    }
  ]
}

Request fields

Response · 200

{
  "attachment_id": "2b575b88-88bb-40d0-b616-57536b782806",
  "status": "uploaded"
}

Presigned download

Needs attachment:download. Returns a presigned GET download_url valid for 5 minutes, along with the verified mime, original_name and a disposition (inline or attachment; e2ee ciphertext is always attachment). Images also get a thumbnail_url, and videos get a poster_url when a ready poster exists; both are presigned for the same 5 minutes. Request the attachment again for fresh URLs instead of caching them. An attachment that is not ready, whether still verifying or failed, returns 409.

downloadAttachment captured live

Request

curl -X GET https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/attachments/ee86f695-3f58-48e2-9ca8-66ee9651ee3e/download \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…"

Response · 200

{
  "download_url": "https://files.example.com/objects/…?X-Amz-Signature=…",
  "expires_at": "2026-01-15T09:35:12Z",
  "mime": "image/jpeg",
  "original_name": "invoice-q3.jpg",
  "thumbnail_url": "https://files.example.com/objects/…?X-Amz-Signature=…",
  "disposition": "inline"
}

Register a Web Push subscription

The token's principal must still be an active member of the token's room. endpoint must be an https URL of at most 1024 characters whose host is not a private, loopback or link-local IP literal (400 otherwise). Host names are resolved and checked again each time a push is sent. The subscription belongs to the principal, not to one room or device. Subscribing the same endpoint again replaces its keys and clears any earlier delivery failure. The subscription receives pushes for new messages in the principal's rooms when they have no chat socket open to that room (at most one per room every 30 seconds), and for call rings. Web Push only works when the deployment has a VAPID key configured (see GET /v1/push/vapid-public-key).

pushSubscribe captured live

Request

curl -X POST https://api.ollacore.com/v1/push/subscriptions \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"endpoint":"https://fcm.googleapis.com/fcm/send/EXAMPLE","keys":{"p256dh":"<redacted>","auth":"c2VjcmV0MTIzNDU2Nzg"},"user_agent":"Mozilla/5.0 (Android 14; Pixel 8)"}'

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/EXAMPLE",
  "keys": {
    "p256dh": "<redacted>",
    "auth": "c2VjcmV0MTIzNDU2Nzg"
  },
  "user_agent": "Mozilla/5.0 (Android 14; Pixel 8)"
}

Request fields

Response · 200

{
  "subscribed": true
}

Unregister one

Deletes only the caller's own subscription for that endpoint and returns removed. Deleting a subscription that does not exist returns removed: false, so the call is safe to retry. It checks the token but not membership, so a principal removed from the room can still delete its subscription.

pushUnsubscribe captured live

Request

curl -X DELETE https://api.ollacore.com/v1/push/subscriptions \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"endpoint":"https://fcm.googleapis.com/fcm/send/EXAMPLE"}'

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/EXAMPLE"
}

Request fields

Response · 200

{
  "removed": true
}

VAPID public key

Needs no authentication. Pass vapid_public_key as applicationServerKey to PushManager.subscribe(), then register the resulting subscription with POST /v1/push/subscriptions. A 404 means Web Push is not enabled on this deployment.

vapidPublicKey captured live

Request

curl -X GET https://api.ollacore.com/v1/push/vapid-public-key \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…"

Response · 200

{
  "vapid_public_key": "BOCW_h9I_7rKsBL9E6EXl2eENH5vPkbuYPcIR9AVhUDwFJipZ4vC5RMAUqiKWSlVEhK3T2Zyv0DnJGXC1i0cNoE"
}

Publish device + one-time keys

Limited to 30 calls per principal per 10 seconds, and the principal must still be an active member of the token's room. device_keys replaces the calling device's identity keys. The first upload for a new device bumps the principal's device-list version, so co-members see the principal in device_list_changes. Each call takes up to 100 one_time_keys and 8 fallback_keys, and each key blob may be at most 64 KiB serialized (400 otherwise). A one-time key whose id is already stored is ignored, and a fallback key replaces the device's previous fallback key for that algorithm.

keysUpload captured live

Request

curl -X POST https://api.ollacore.com/v1/e2ee/keys/upload \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"device_keys":{"user_id":"alice","device_id":"dev-alice","algorithms":["m.olm.v1.curve25519-aes-sha2","m.megolm.v1.aes-sha2"],"keys":{"curve25519:dev-alice":"JGDn8Xz3…","ed25519:dev-alice":"lEuiSJHm…"}},"one_time_keys":{"signed_curve25519:AAAAAQ":{"key":"zKbLg+NrIjpn…"},"signed_curve25519:AAAAAg":{"key":"mYWt2yTv8p…"},"signed_curve25519:AAAAAw":{"key":"qR7dLm3nXk…"}}}'

{
  "device_keys": {
    "user_id": "alice",
    "device_id": "dev-alice",
    "algorithms": [
      "m.olm.v1.curve25519-aes-sha2",
      "m.megolm.v1.aes-sha2"
    ],
    "keys": {
      "curve25519:dev-alice": "JGDn8Xz3…",
      "ed25519:dev-alice": "lEuiSJHm…"
    }
  },
  "one_time_keys": {
    "signed_curve25519:AAAAAQ": {
      "key": "zKbLg+NrIjpn…"
    },
    "signed_curve25519:AAAAAg": {
      "key": "mYWt2yTv8p…"
    },
    "signed_curve25519:AAAAAw": {
      "key": "qR7dLm3nXk…"
    }
  }
}

Request fields

Response · 200

{
  "one_time_key_counts": {
    "signed_curve25519": 3
  }
}

Query devices for principals

Limited to 60 calls per principal per 10 seconds. The token must carry an explicit device_id (400 otherwise). Every principal in the query must be the caller or share an active room with the caller; if any one does not, the whole request returns 403. The response contains all devices of each principal, whatever device list the request names. A principal with no uploaded keys is left out of the result.

keysQuery captured live

Request

curl -X POST https://api.ollacore.com/v1/e2ee/keys/query \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"device_keys":{"alice":{},"bob":{}}}'

{
  "device_keys": {
    "alice": {},
    "bob": {}
  }
}

Request fields

Response · 200

{
  "device_keys": {
    "alice": {
      "dev-alice": {
        "algorithms": [
          "m.olm.v1.curve25519-aes-sha2",
          "m.megolm.v1.aes-sha2"
        ],
        "device_id": "dev-alice",
        "keys": {
          "curve25519:dev-alice": "JGDn8Xz3…",
          "ed25519:dev-alice": "lEuiSJHm…"
        },
        "user_id": "alice"
      }
    },
    "bob": {
      "dev-bob": {
        "algorithms": [
          "m.olm.v1.curve25519-aes-sha2"
        ],
        "device_id": "dev-bob",
        "keys": {
          "curve25519:dev-bob": "aBcD…"
        },
        "user_id": "bob"
      }
    }
  }
}

Claim a one-time key (atomic)

Limited to 120 calls per principal per 10 seconds. The token must carry an explicit device_id (400 otherwise). For each requested device, the oldest unclaimed one-time key is deleted and returned. When none is left, the device's newest fallback key is returned instead and kept on file. It is marked as used, so it no longer appears in its owner's unused_fallback_key_algorithms, which tells the owner to replace it. Devices with no key at all are left out of the result, and the algorithm named in the request is ignored.

keysClaim captured live

Request

curl -X POST https://api.ollacore.com/v1/e2ee/keys/claim \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"one_time_keys":{"bob":{"dev-bob":"signed_curve25519"}}}'

{
  "one_time_keys": {
    "bob": {
      "dev-bob": "signed_curve25519"
    }
  }
}

Request fields

Response · 200

{
  "one_time_keys": {
    "bob": {
      "dev-bob": {
        "signed_curve25519:BBBBAQ": {
          "key": "nnn…"
        }
      }
    }
  }
}

Send a to-device message

Limited to 60 calls per principal per 10 seconds. The token must carry an explicit device_id (400 otherwise). event_type must be 1–128 characters and each device's content at most 64 KiB. After * is expanded to every device the recipient has uploaded keys for, one request may queue at most 500 rows (400 otherwise). If any recipient is neither the caller nor shares an active room with the caller, the whole request returns 403. Queued events wait in each device's inbox until that device fetches and acknowledges them through GET /v1/e2ee/todevice; no socket event announces them. Events never fetched are purged after 30 days.

todeviceSend captured live

Request

curl -X POST https://api.ollacore.com/v1/e2ee/todevice \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"m.room_key_request","messages":{"bob":{"dev-bob":{"action":"request","requesting_device_id":"dev-alice"}}}}'

{
  "event_type": "m.room_key_request",
  "messages": {
    "bob": {
      "dev-bob": {
        "action": "request",
        "requesting_device_id": "dev-alice"
      }
    }
  }
}

Request fields

Response · 200

{
  "queued": 1
}

Fetch queued to-device messages

The token must carry an explicit device_id (400 otherwise), and only that device's inbox is returned. Pass the previous response's next_token as ack: events up to it are deleted and the next batch of at most 100 events is returned, oldest first. An unacknowledged batch is therefore served again after a crash. Each event carries the server-stamped sender principal, its type and its content. Pass the previous device_list_watermark as device_watermark; device_list_changes then lists the caller and any co-members whose devices changed since. Undelivered events are purged after 30 days.

todeviceFetch captured live

Request

curl -X GET https://api.ollacore.com/v1/e2ee/todevice \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…"

Response · 200

{
  "device_list_changes": [
    "alice",
    "bob"
  ],
  "device_list_watermark": 157,
  "events": [
    {
      "content": {
        "action": "request",
        "requesting_device_id": "dev-alice"
      },
      "sender": "alice",
      "type": "m.room_key_request"
    }
  ],
  "next_token": 130,
  "one_time_key_counts": {
    "signed_curve25519": 1
  },
  "unused_fallback_key_algorithms": []
}

Upload MLS key packages

The token's principal must still be an active member of the token's room. packages holds 1–50 base64 blobs, each decoding to between 1 byte and 64 KiB (400 otherwise). They are stored under device_id, which defaults to default when omitted and is not taken from the token. A package already on file (same SHA-256) is skipped, so stored counts only new packages. With last_resort: true the request must carry exactly one package, which replaces the device's previous last-resort package. expires_in_seconds (1 to 31,536,000, one year) sets how long the server keeps the package: after that it is never served and is swept. If omitted, the package is kept until it is consumed.

uploadKeyPackages captured live

Request

curl -X POST https://api.ollacore.com/v1/keypackages \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"device_id":"dev-alice","packages":["AAECAwQFBgcICQoLDA0ODw==","EBESExQVFhcYGRobHB0eHw==","ICEiIyQlJicoKSorLC0uLw=="]}'

{
  "device_id": "dev-alice",
  "packages": [
    "AAECAwQFBgcICQoLDA0ODw==",
    "EBESExQVFhcYGRobHB0eHw==",
    "ICEiIyQlJicoKSorLC0uLw=="
  ]
}

Request fields

Response · 200

{
  "stored": 3
}

Remaining key-package count

The token's principal must still be an active member of the token's room. For each of the caller's devices that has packages on file, remaining counts the unexpired, unconsumed regular packages, and last_resort says whether an unexpired last-resort package is held. A device with nothing left does not appear in devices. When remaining reaches zero, consumers receive the reusable last-resort package, so replenish before that.

keyPackageCount captured live

Request

curl -X GET https://api.ollacore.com/v1/keypackages/count \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…"

Response · 200

{
  "devices": [
    {
      "device_id": "dev-alice",
      "last_resort": false,
      "remaining": 3
    }
  ]
}

Consume one key package

Both the caller and the target principal must be active members of this room (403 otherwise). For each of the target's devices, the oldest unexpired regular package is consumed and returned. A device with none left returns its last-resort package with last_resort: true; that package stays on file and can be served again. Expired packages are never served. The call returns 404 when none of the target's devices has any package.

consumeKeyPackages captured live

Request

curl -X GET https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/keypackages/alice \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…"

Response · 200

{
  "principal_id": "alice",
  "packages": [
    {
      "device_id": "dev-alice",
      "package": "AAECAwQFBgcICQoLDA0ODw==",
      "last_resort": false
    }
  ]
}

Publish the MLS GroupInfo + ratchet tree

Any active member may publish; a room that is not e2ee returns 409. epoch must be 0 or more. group_info (base64, up to 64 KiB) and the optional ratchet_tree (base64, up to 256 KiB) are stored as a single row per room that each publish replaces. Omitting ratchet_tree clears any previously stored tree. Oversized or non-base64 blobs return 400. Publishing the same epoch again is accepted, so a committer can retry safely. Nothing is published to the room's sockets.

putGroupInfo captured live

Request

curl -X PUT https://api.ollacore.com/v1/rooms/f10b8ba1-6206-4994-9e66-597cef0a6792/mls/group-info \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"epoch":3,"group_info":"AAECAwQFBgcICQoLDA0ODw==","ratchet_tree":"EBESExQVFhcYGRobHB0eHw=="}'

{
  "epoch": 3,
  "group_info": "AAECAwQFBgcICQoLDA0ODw==",
  "ratchet_tree": "EBESExQVFhcYGRobHB0eHw=="
}

Request fields

Response · 200

{
  "epoch": 3
}

Latest GroupInfo + ratchet tree

Any active member may read it. Returns the stored epoch, the base64 group_info and ratchet_tree, and updated_by and updated_at for the latest publish. ratchet_tree is null when the publisher omitted it. The call returns 404 until a member has published GroupInfo for this room, which means a room that is not e2ee always returns 404.

getGroupInfo captured live

Request

curl -X GET https://api.ollacore.com/v1/rooms/f10b8ba1-6206-4994-9e66-597cef0a6792/mls/group-info \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…"

Response · 200

{
  "epoch": 3,
  "group_info": "AAECAwQFBgcICQoLDA0ODw==",
  "ratchet_tree": "EBESExQVFhcYGRobHB0eHw==",
  "updated_by": "alice",
  "updated_at": "2026-01-15T09:30:53Z"
}

Observe your own accepted RTC session by its handle — not GA, and absent unless the deployment enables it

Not stable or GA. RTC_SESSION_CONTROL_ENABLED defaults to false; only literal true registers this route, otherwise POST returns 404. The socket must separately opt in with exactly one literal control=1 on /v1/rtc/ws (duplicate or encoded control keys/values do not enable it). Its private session.handle event follows initial peers and is never broadcast. This HTTP request requires Authorization: Bearer, rtc:subscribe and exact equality to the socket's stored claims: tid, rid, sub, did (absence differs from empty), jti, exp, iss, aud, role, permissions (including order), iat and nbf. WebSocket subprotocol credentials alone do not authenticate HTTP. A renewed JWT requires a new opted-in WebSocket and handle. Expiry is strict at exp, without verifier leeway. After exact ownership and nonblocking read permits, a fresh active-membership query must succeed before the media-thread exact-session/port/epoch/writer check; HTTP rechecks expiry and ownership before responding. Membership observation is NOT atomic with concurrent membership removal. accepted is admission only, not connected transport or media health. No mutations or room/source inventory. All responses for this exact path are Cache-Control: no-store. A shared two-second deadline covers the read; pressure/unavailability is 503, deadline expiry is 504.

read · scope rtc:subscribe from schema placeholder credentials

Request

curl -X POST https://api.ollacore.com/experimental/rtc/session \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…" \
  -H "Content-Type: application/json" \
  -d '{"handle":"00000000-0000-0000-0000-000000000000"}'

{
  "handle": "00000000-0000-0000-0000-000000000000"
}

Request fields

Response · 200

{
  "client_id": "7",
  "state": "accepted"
}

Sunset 2027-01-05 — camera feeds were withdrawn; always an empty list, with Deprecation and Sunset headers

DEPRECATED: the camera-feeds media sidecar that produced recordings has been decommissioned, so this returns an empty list. Responses carry Deprecation and Sunset headers; it may be removed on or after 2027-01-05. See docs/API-STABILITY.md. Segments of a recorded camera, newest first, each a fragmented MP4 playable on its own or in order. A camera is recorded by publishing to rec/{room_id} instead of {room_id}; nothing here turns recording on. Whoever may watch the camera may watch what it recorded: the same rtc:subscribe permission and the same live membership. Footage is deleted on the deployment’s retention schedule and by every erasure path, so treat these as a secondary copy of what the camera’s own recorder holds.

listRecordings captured live

Request

curl -X GET https://api.ollacore.com/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/recordings?limit=20 \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSJ9…"

Response · 200

{
  "segments": []
}