The app API

The app API is the HTTPS API your app calls, version 1. Every request carries the app’s token, and every call acts as the app, in the channels it was added to, with the scopes an admin gave it. For the token, the base URL and the general rules, see Build an app.

Paths below start at /v1, relative to https://api.buildit.social/functions/v1/app-api.

Endpoints#

Cards and their answers are on The card format; events and polling on Events and webhooks.

Where an app reaches#

• The org comes from the token, never from the request. Another org’s ids, DMs and group DMs, and ids that don’t exist all answer the same 404 not_found.
• Channels: only those the app was added to. Others in its org answer 403 not_in_channel. Writes in an archived channel answer 403 archived.
• Messages: an app changes, deletes and closes only its own (403 not_own_message).
• A read-only org (its subscription lapsed): nothing new can be written (403 org_read_only), but deleting the app’s own messages, removing its reactions and unpinning still work.
• A turned-off app: while the app is turned off, paused, or the org’s apps are off, every call answers 403 app_paused with details.reason (disabled, paused or apps_off). The token isn’t revoked: it works again when an admin turns the app back on.

Post a message#

curl -sS -X POST "$BUILDIT_API_BASE/channels/$CHANNEL_ID/messages" \
  -H "Authorization: Bearer $BUILDIT_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Deployed **web 1.0.0** to production.", "idempotency_key": "00000000-0000-4000-8000-000000000001"}'

The answer is 201 with the new message:

{
  "created": true,
  "message": {
    "id": "00000000-0000-4000-8000-000000000001",
    "channel_id": "7e9a1c3b-5d7f-4e9a-8c1d-3f5b7d9e1a3c",
    "thread_id": null,
    "reply_to_id": null,
    "kind": "text",
    "text": "Deployed **web 1.0.0** to production.",
    "author": {"type": "app", "id": "0d4b6f8a-2c4e-4a6b-8c0d-2e4f6a8b0c2d", "name": "Deploybot"},
    "mentions": [],
    "card": null,
    "card_state": null,
    "has_attachment": false,
    "reply_count": 0,
    "last_reply_at": null,
    "created_at": "2026-10-20T15:02:11.482Z",
    "edited_at": null,
    "deleted": false,
    "version": 1,
    "reactions": []
  }
}

Messages#

• Text: the Markdown people use (bold, italic, code, links, lists, quotes), 1 to 4,000 characters, counted as Unicode code points. No images: ![ outside code is refused; write \![ for the text.
• Mentions: [@Name](mention:<user id>) of people who are members of the channel (ids from GET /v1/channels/{id}/members), at most 20 a message. They notify under each person’s own settings. A mention of an app is kept as text and notifies nobody; any other id answers 422 validation on text. Mentions added by an edit don’t notify.
• Threads and quotes: thread_id posts a reply in the thread of that top-level message of the channel; reply_to_id quotes a message of the channel.
• Links get the same previews as anyone’s. Work item keys such as WEB-42 link to the item for people who can see it.
• Versions: the app’s own messages have a version (1 when posted, one more for each change). Send it as if_version with a PATCH to refuse a change on top of another one (409 conflict, with details.current.version).
• Authors in what you read: {"type": "user", "id", "name", "is_guest"} or {"type": "app", "id", "name"}. Files and GIFs show only as has_attachment: true. A deleted message keeps its place, with no text.
• Reactions: the emoji itself in the path, URL-encoded, or :name: for one of the org’s custom emoji from GET /v1/emoji (case-sensitive). An app puts at most 20 different reactions on one message, and none on system lines.
• Custom emoji in text: write [:name:](emoji:<id>) with an id from GET /v1/emoji.
• Pins: the app pins as a member does: text messages and replies only, refused where only managers may pin (403 message_pin_not_allowed), at most 100 per channel (409 message_pin_limit). The channel gets a line saying the app pinned it.
• Cards go in card; with a card, text is its plain-text fallback. See The card format.

Idempotency#

• Posting: idempotency_key is a UUID that becomes the new message’s id. A retry with the same key answers 200 with the same message and "created": false, so a retry never posts twice. The key used for anything else answers 409 idempotency_conflict. Make one random UUID per message you mean to post, and reuse it for retries.
• Everything else is idempotent by design: a PATCH with the same content, a DELETE of a deleted message (deleted: false), a reaction that is already there or already gone (changed: false), the same accept or reject again. Closing a closed card answers 409 card_closed.

Paging#

Lists answer {"items": […], "next_cursor": "…"}. Pass next_cursor back as cursor for the next page; it’s null on the last page. Cursors are opaque and valid only with the same query. limit is 1 to 100 (default 50), or 1 to 200 for a channel’s members. A malformed cursor answers 422 validation on cursor.

Polling has its own cursor: see Polling.

Rate limits#

GET /v1/me gives the limits in force for your app. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds). A refusal is 429 rate_limited with Retry-After, details.retry_after (seconds) and details.bucket; a refused request counts nothing. The per-address limit answers 429 with only {"message": "…"}: treat it as rate_limited and retry after a minute.

Errors#

Every error is one envelope:

{
  "error": {
    "code": "not_in_channel",
    "message": "The app isn't in this channel. Someone in the channel can add it from the channel's details.",
    "hint": "Ask someone in the channel to add the app, or use a channel from GET /v1/channels.",
    "details": {"channel_id": "7e9a1c3b-5d7f-4e9a-8c1d-3f5b7d9e1a3c"}
  }
}

Read code, hint and details; message is for people.

Retry 429 after Retry-After, 500 once, and 503. Don’t retry the other 4xx codes unchanged: hint says what to change.