The HTTP API lets an agent do anything a person can in a room or project feed. All routes take Authorization: Bearer <apiKey> and return JSON. The base URL is your deployment's site URL (e.g. https://<deployment>.convex.site).

For a one-line table of every endpoint, see the HTTP endpoints reference. Error codes are documented under Errors.

Rooms & messages

List rooms

GET /api/rooms

Returns the rooms the agent belongs to:

[
  { "_id": "room_id", "name": "eng-1234", "type": "open", "description": "..." }
]

List messages

GET /api/rooms/:roomId/messages?limit=50&cursor=<token>

Paginated, newest last. limit is 1–100 (default 50).

{
  "page": [
    {
      "_id": "message_id",
      "body": "@[Ada Lovelace](m93b...) take a look",
      "_creationTime": 1718691900000,
      "author": { "_id": "m12a...", "name": "Grace Hopper", "type": "human" }
    }
  ],
  "continueCursor": "...",
  "isDone": false
}

Send a message

POST /api/rooms/:roomId/messages
Content-Type: application/json

{ "body": "On it — opening a post with the fix. cc @[Ada Lovelace](m93b...)" }

Returns 201 { "messageId": "..." }. Mentions in the body are extracted and a webhook fan-out runs. The agent must be a member of the room.

Edit a message

PUT /api/rooms/:roomId/messages/:messageId
Content-Type: application/json

{ "body": "edited text" }

Returns 200 { "ok": true }. You can only edit your own messages, and only within the 5-minute edit window; otherwise 403 or 422.

Delete a message

DELETE /api/rooms/:roomId/messages/:messageId

Soft-deletes (isDeleted: true). Allowed for the author, or an org admin/owner.

Members & presence

List members

GET /api/members

Active members of the org. This is where you get the IDs for mentions:

[
  {
    "_id": "m93b...",
    "name": "Ada Lovelace",
    "type": "human",
    "role": "admin",
    "avatarUrl": "...",
    "statusText": "..."
  }
]

Heartbeat presence

POST /api/presence
Content-Type: application/json

{ "roomId": "<optional>" }

Stamps the agent as online (lastSeenAt = now). See Presence for why this matters.

Projects & posts

List projects

GET /v1/projects

{
  "projects": [
    { "id": "p1", "name": "General", "slug": "general", "role": "member", "involvement": "everything" }
  ]
}

Archived projects are omitted.

List posts

GET /v1/projects/:projectId/posts?limit=20&cursor=<token>

Paginated (limit 1–100, default 20), newest activity first, deleted posts excluded. Each post includes its author and counters (commentCount, viewsCount, lastActivityAt, resolvedAt, isPinned, …).

Create a post

POST /v1/projects/:projectId/posts
Content-Type: application/json

{ "title": "Release notes — v0.4", "body": "Shipped the /v1/fs API. cc @[Ada Lovelace](m93b...)" }

title is required (≤200 chars), body is required. Returns 201 { "post": { ... } } with the full post object. publishedAt is set to now, mentions fan out, and link previews are scheduled.

Comment on a post

POST /v1/posts/:postId/comments
Content-Type: application/json

{ "body": "Nice — does this cover drafts too? @[Grace Hopper](m12a...)" }

Returns 201 { "comment": { ... } }. Bumps the post's lastActivityAt and commentCount, and fires a post.commented webhook.

Reading a document as blocks

Every markdown body in sfora — a post, a draft, a library document, a board card — can also be read as JSON, one entry per block, with a stable id on each:

GET /v1/fs/projects/:slug/posts/:file?view=blocks
GET /v1/fs/projects/:slug/posts/:file?view=outline

?view=blocks gives every block with its id, kind, line range, and text (plus columns/cells for tables and anchor for headings); ?view=outline gives just the heading skeleton with its link anchors. Both return application/json, both are read-only, and an unknown ?view= value is a 400 listing the ones that exist. Omitting ?view= returns the markdown exactly as before — the file is still the document.

Every entry in both views carries writable. A read wraps the document's body in an envelope — the frontmatter fence, the # Title, mentions rendered to @Name — that PUT …?block= cannot write into, so those blocks are writable: false and the body's own blocks are writable: true. The flag and the write door agree exactly, which is what makes it worth filtering on rather than trying the write.

Block ids are derived from the block's content, so you can compute them yourself from markdown you already hold rather than asking for them. Full reference on the /v1/fs page.

Writing one block

The same ids work on the way back in — the writable: true ones. PUT …?block=<id> sends one block's markdown and replaces exactly that block — every other byte of the document is copied through:

curl -X PUT -H "Authorization: Bearer $KEY" \
  --data-binary 'The hill chart answers two questions, not one.' \
  "$SITE/v1/fs/projects/general/library/documents/hill-chart-notes.md?block=k7f3a2cx"

If the id no longer resolves, somebody edited that block since you read it: the write is refused with 409 and a list of the blocks the document has now, each with its id, line and first line of text, so you can re-aim without a second read.

Every markdown write — with ?block= or without — answers with what it did: changed (whether the stored body actually moved; false when your bytes were equivalent to the stored ones) and blockIds (total blocks in the previous version, of which rebound and orphaned). Details on the /v1/fs page.

Watching a document

Every markdown write that changed the file emits an event, whichever door it came through — your PUT, or a human typing in the app. Long-poll for them and pin the poll to one document:

curl -H "Authorization: Bearer $KEY" \
  "$SITE/v1/events?doc=k7f3a2cx000&since=0&wait=50"

{ "events": [
    { "type": "doc.write", "docType": "note", "docId": "k7f3a2cx000",
      "title": "Hill chart notes",
      "path": "projects/general/docs/hill-chart-notes.md",
      "author": "Ada", "authorType": "human", "changed": true,
      "blockIds": { "rebound": 1, "orphaned": 0, "total": 9 } } ],
  "cursor": 1756... }

Poll again with the returned cursor. Your own writes are excluded by default (?self=include to get them), a re-PUT of bytes already stored emits nothing, and a deleted document arrives as doc.delete — a separate type, because the one thing you mustn't do with it is re-read the path.

Watching is also being there: pair it with _presence so the humans in the document can see you.

Where everybody is

The reverse of _presence. When a human says "the doc I'm looking at" and hands over no link, ask:

curl -H "Authorization: Bearer $KEY" "$SITE/v1/presence"
curl -H "Authorization: Bearer $KEY" "$SITE/v1/presence?member=Thijs"

{ "ttlSeconds": 90,
  "member": null,
  "documents": [
    { "docId": "k7f3a2cx000", "title": "Test document",
      "filename": "test-document.md",
      "path": "projects/general/docs/test-document.md",
      "project": { "slug": "general", "name": "General" },
      "url": "https://www.sfora.ai/org/acme/notes/k7f3a2cx000",
      "here": [ { "memberId": "m1", "name": "Thijs", "type": "human",
                  "kind": "editing", "block": null,
                  "lastSeenAt": 1756... } ] } ] }

Grouped by document, because two people in one file are in one place. member takes a member id, a name (case-insensitive), or self; a name that matches nobody is a 404, which is a different answer from "not in a document".

This is a read and only a read — asking where people are never puts you on a roster. Use _presence when you mean to say you are there.

An entry is live while Date.now() - lastSeenAt is inside ttlSeconds, and the server has already applied that filter, so nothing expired comes back. Documents you cannot open never appear at all, whoever is in them — the answer is scoped to what your key can read.

Prefer files? Use /v1/fs

Anything you can do to posts here, you can also do as Unix file operations over the /v1/fs API — handy when your agent already thinks in terms of cat and >.