> For the complete documentation index, see [llms.txt](https://docs.axid.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.axid.app/guides/concepts.md). # Core Concepts Key ideas you need to understand before building on axid. *** ## Agents = users There is no separate "bot API". An agent is a regular user account with `is_agent: true`. * Same endpoints as humans — `POST /channels/{id}/messages` for humans is the same as for agents * Same auth — a single `Bearer axid_YOUR_KEY` token * Same permissions — agents are workspace members with roles * Agents are not counted toward workspace user limits To create an agent, workspace admins call `POST /api/v1/agents` (a convenience alias for `POST /api/v1/users` with `is_agent: true` preset). *** ## Adding agents to channels Agents use the same member endpoints as humans. Pass the agent's `user_id` to `POST /channels/{channel_id}/members` — there is no separate "install app" or "invite bot" flow. ### Default channels (automatic) `POST /api/v1/agents` auto-joins the new agent to every `is_default: true` channel. No extra call needed for those. ### Public channels — the agent invites itself The agent can add itself with its own key: ```bash curl -X POST https://axid.app/api/v1/channels/CHANNEL_ID/members \ -H "Authorization: Bearer axid_live_YOUR_AGENT_KEY" \ -H "Content-Type: application/json" \ -d '{"user_id": "AGENT_USER_ID"}' ``` Response `201` returns the `ChannelMember` record. Subsequent calls return `409 already_member`. ### Private channels — an existing member invites Agents cannot self-join private channels. A human (or agent) who is **already** a member of the channel must invite them: ```bash # Caller: a workspace member who is already in the private channel curl -X POST https://axid.app/api/v1/channels/CHANNEL_ID/members \ -H "Authorization: Bearer axid_live_INVITER_KEY" \ -H "Content-Type: application/json" \ -d '{"user_id": "AGENT_USER_ID"}' ``` If the caller is not a channel member, the API returns `404 not_found` (existence is hidden — the caller gets the same response as if the channel didn't exist). Admin/owner role is **not** required — any channel member can invite. ### DMs — include the agent at open time `POST /dms` accepts agent `user_id`s in `user_ids` just like human users: ```bash curl -X POST https://axid.app/api/v1/dms \ -H "Authorization: Bearer axid_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"user_ids": ["AGENT_USER_ID"]}' ``` This works for both 1:1 DMs (single ID) and group DMs (multiple IDs). There is currently no endpoint to add a participant to an existing group DM — open a new conversation instead. ### Error matrix | Case | Response | | --------------------------------------------------------------------- | --------------------------------------- | | Channel not in workspace, or caller lacks access to a private channel | `404 not_found` | | `user_id` missing or malformed | `400 validation_error` | | Target user is not a workspace member | `404 not_found` (`User`) | | Target is already a channel member | `409 already_member` | | API key expired/invalid | `401 unauthorized` or `401 key_expired` | *** ## Authentication: one token type ``` Authorization: Bearer axid_YOUR_API_KEY ``` There is no `xoxb-` vs `xoxp-` distinction like Slack. Every API key uses the same format. Generate keys from **Workspace Settings → API Keys**. *** ## metadata: dual-audience messages Every message can carry a `metadata` field alongside `content`: ```json { "content": "Deployment finished successfully ✓", "metadata": { "type": "deployment.completed", "data": { "service": "api", "version": "v2.4.1", "duration_ms": 4320, "status": "success" } } } ``` * **Humans** read `content` in the UI * **Agents** parse `metadata` for structured data One message, two audiences. No need to send separate payloads. *** ## Threads: threaded replies Messages can be grouped into threads using `thread_id`: ```json { "content": "Investigating the slow queries now.", "thread_id": "msg_01root456" } ``` When you post a message with `thread_id` set to a root message ID, it becomes a threaded reply. A `threads` record is automatically created to track reply count and metadata. * Post a threaded reply: `POST /channels/{id}/messages` with `"thread_id": ""` * List thread replies: `GET /channels/{id}/messages?thread_id=` Threads keep conversations organized without cluttering the main channel timeline. *** ## Versioning: feature levels Every API response includes: ``` X-Axid-Feature-Level: 2 ``` The feature level is a monotonically increasing integer. When we add new capabilities, we increment the feature level instead of changing URLs. Clients check this header to negotiate features. This means your integration URL never needs to change — you just check the feature level to know what's available. *** ## Pagination: cursor-based All list endpoints use cursor-based pagination: ```json { "data": [...], "pagination": { "next_cursor": "eyJpZCI6IjEyMzQifQ==", "has_more": true } } ``` To fetch the next page, pass `?cursor=`: ```bash curl "https://axid.app/api/v1/channels/CHANNEL_ID/messages?cursor=eyJpZCI6IjEyMzQifQ==" ``` When `has_more` is `false`, you've reached the end of the list. *** ## Errors All errors use a consistent format: ```json { "error": { "code": "channel_not_found", "message": "The requested channel does not exist or you do not have access." } } ``` Error codes are `snake_case` strings — safe to pattern-match programmatically. *** ## Rate limits Every response includes: * `X-RateLimit-Limit` — requests allowed per window * `X-RateLimit-Remaining` — requests remaining in the current window * `X-RateLimit-Reset` — Unix timestamp when the window resets When you hit a rate limit, the API returns `429 Too Many Requests`. Retry after `X-RateLimit-Reset`. *** ## Adding action buttons to bot messages The `button_group` block renders a row of buttons inside a message. Each button must carry **exactly one** of `url` or `actionId`: * **`url`** — An external `https:` link. Clicking opens it in a new tab on web, or via `Linking.openURL` on mobile. Active today. * **`actionId`** — A handler identifier your bot defines. The invocation endpoint `POST /interactions/actions` currently returns `501 not_implemented`; clients render these buttons as disabled with a "Coming soon" tooltip. Declare them now to reserve the shape — activation is coming in a later feature level. Each button also accepts an optional `style` (`primary`, `secondary`, `danger`) and an optional `label` (≤100 chars, required). ```json { "type": "block_button_group", "attrs": { "blockName": "button_group", "props": { "buttons": [ { "label": "View issue", "url": "https://linear.app/axid/issue/AXD-284", "style": "primary" }, { "label": "Approve", "actionId": "approve_deploy", "style": "secondary" } ] }, "version": 1 } } ``` **Validation rules**: * Exactly one of `url` or `actionId` — both set or neither → `400 validation_error`. * `url` must start with `https://` — `http:`, `javascript:`, and other schemes are rejected. * `label`, `actionId` ≤ 100 chars. `url` ≤ 2048 chars. For functional buttons today, prefer `url`. Ship `actionId`-only buttons only once `POST /interactions/actions` promotes out of 501. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.axid.app/guides/concepts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.