API Reference

The Ando API lets humans, services, and external agents work with the context in an Ando workspace. Use it to search messages and conversations, read calls, send messages, listen for live events, and manage outbound webhooks. Endpoints live under https://api.ando.so/v1. This page covers the typical flow; the complete contract is in the OpenAPI specification.

Client libraries

Ando does not provide a general API client. @andocorp/sdk exports webhook signature verification helpers and typed webhook events from @andocorp/sdk/webhooks. It does not export AndoClient, and it does not manage request retries, realtime connections, or idempotency keys. Call the HTTP endpoints directly. For live events, open a realtime connection and connect to its WebSocket URL with the ando.realtime.v1 subprotocol. See Realtime for the wire-level flow.

Authentication

Choose the identity that should own the request:

Caller	Create the key	Use it when
Human	Studio → API & Webhooks → API keys	A script or service should act as you.
Agent	Settings → Members → Agents → Invite agent	Messages and actions should be attributed to an agent.

Send the key with x-api-key:

x-api-key: ando_sk_...

Authorization: Bearer ando_sk_... remains available for compatibility, but new HTTP integrations should use x-api-key. Each key belongs to one workspace. Responses include only resources that key can access, and Ando derives message authorship from the key—you do not send an author_id. Workspace admins and owners can manage delegated credentials without a browser when the calling key has api_keys:read or api_keys:write. Issued and rotated secrets are revealed once. Delegated keys can receive agent, message, realtime, and webhook scopes, but never credential-management scopes, so they cannot create another generation of credentials. To create the first setup credential, open Studio → API & Webhooks and choose Provisioning key from the API keys menu. Only workspace admins and owners can select it. After a separate confirmation, the key receives only api_keys:read and api_keys:write; it cannot read or send messages. Use it to issue narrower keys for named agents, then store it as a privileged secret.

Quick start for agents

Create an external agent and give its key to the runtime you operate. Paste the following into that agent to establish the API boundary:

You can use Ando's public API to search and act on workspace context.

- Base URL: https://api.ando.so/v1
- Full contract: https://api.ando.so/openapi.json
- Authenticate every HTTP request with: x-api-key: <ANDO_API_KEY>
- If you do not have an agent API key, ask me to create one in Ando under
  Settings → Members → Agents → Invite agent.
- Treat the key as a secret. Never print it, save it in conversation history,
  or put it in client-side code.
- Search before reading large histories. Only use conversations and resources
  the key can access.
- Confirm the intended destination before writing. Message writes require an
  Idempotency-Key; reuse it only when retrying the same request.
- Report the source IDs you used and any writes you made.

Fetch the OpenAPI specification before choosing an endpoint or request shape.

If the runtime supports MCP, Ando MCP provides ready-made tools over the same permission boundary.

Quick start for humans

Create a personal API key under Studio → API & Webhooks → API keys, then make a server-side request:

export ANDO_API_KEY="ando_sk_..."

curl -sS -G "https://api.ando.so/v1/search/messages" \
  -H "x-api-key: $ANDO_API_KEY" \
  --data-urlencode "q=release"

To send a message, choose a conversation the key can access and include an idempotency key:

export CONVERSATION_ID="conv_..."

curl -sS -X POST \
  "https://api.ando.so/v1/conversations/$CONVERSATION_ID/messages" \
  -H "x-api-key: $ANDO_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data '{
    "markdown_content": "Hello from the Ando API.",
    "explicit_context_message_ids": [],
    "image_urls": [],
    "suppressed_link_preview_urls": [],
    "thread_root_id": null
  }'

Approval questions

A workspace member’s API key can create a question card through the same message endpoint. This includes keys issued for Ando-hosted agents: you do not need an external-agent identity or an MCP gateway session to post the card. Send the command as the entire markdown_content, with the authentication and Idempotency-Key headers above:

{
  "markdown_content": "$ando.question@2 {\"question\":\"Approve this PR?\",\"options\":[\"Approve\",\"Request changes\"],\"customAnswerLabel\":\"Something else\",\"replyMode\":\"thread\"}"
}

The key needs messages:write and access to the destination; an agent must be a member of that conversation. Ando derives authorship from the key and returns the created message with a miniapp link. Retry the same body with the same idempotency key to avoid a second card. Use a new key for a different question. replyMode is thread or conversation. The first human answer is final and posts a reply in the selected location. Agents cannot answer on a human’s behalf. The REST body uses markdown_content; miniapp_command is the MCP tool argument.

Thread replies

Send replies to the same POST https://api.ando.so/v1/conversations/{conversationId}/messages endpoint. Include the authentication and Idempotency-Key headers shown above. For the first reply to a thread, send only the root message ID:

{
  "markdown_content": "First reply in the thread.",
  "thread_root_id": "msg_root"
}

For a reply to another reply, send both the thread root and immediate parent:

{
  "markdown_content": "Reply to a reply.",
  "thread_root_id": "msg_root",
  "replied_to_message_id": "msg_parent"
}

If replied_to_message_id equals thread_root_id, Ando treats it as a first reply. Omit replied_to_message_id for the canonical first-reply shape.

Read message and conversation metadata

Message reads include forward_source when the message was forwarded. For show_message, every reader of the forwarded message receives the content snapshot captured at forward time. For link_only, the source content is not included. Source message, conversation, and thread IDs are present only when the caller can open the source conversation. When a show_message forward explicitly shares a Jam, the destination message’s forward_source includes call_id. A link_only forward does not provide this path. To read the shared Jam through the forward, pass the destination message ID on the call request:

GET /calls/{callId}?forwarded_message_id={destinationMessageId}
GET /calls/{callId}/transcript?forwarded_message_id={destinationMessageId}

The destination message must be readable to the caller and must explicitly share that Jam. This grants access only to that call. Include the same forwarded_message_id on every transcript page. Membership-backed conversation reads may include is_bridge and bridge_kind. bridge_kind is ando_connect, slack_connect, or null. Only ando_connect conversations follow Ando Connect membership semantics; a slack_connect value identifies a Slack Connect mirror.

Files

Upload a file once, then attach it to any number of messages through file_ids. Bytes go straight to storage through a short-lived URL; the API only carries metadata. Create the upload. Idempotency-Key is required:

export ANDO_API_KEY="ando_sk_..."

FILE=$(curl -sS -X POST "https://api.ando.so/v1/files" \
  -H "x-api-key: $ANDO_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data '{
    "filename": "diagram.png",
    "content_type": "image/png",
    "size_bytes": 48213,
    "purpose": "message_attachment"
  }')

The response’s data is the file object, initially in status: "waiting_for_upload", with an upload block describing the single PUT request to make:

{
  "data": {
    "object": "file",
    "id": "file_...",
    "status": "waiting_for_upload",
    "purpose": "message_attachment",
    "filename": "diagram.png",
    "content_type": "image/png",
    "size_bytes": 48213,
    "created_at": "2026-09-02T18:00:00.000Z",
    "updated_at": "2026-09-02T18:00:00.000Z",
    "upload": {
      "kind": "single_part_presigned_put",
      "method": "PUT",
      "url": "https://...",
      "headers": {
        "Content-Length": "48213",
        "Content-Type": "image/png",
        "x-amz-meta-ando-file-id": "file_..."
      },
      "expires_at": "2026-09-02T18:15:00.000Z"
    }
  },
  "file_id": "file_..."
}

Send the bytes with the returned method and URL and every returned header before upload.expires_at, then complete the file:

UPLOAD_URL=$(printf '%s' "$FILE" | jq -r '.data.upload.url')
FILE_ID=$(printf '%s' "$FILE" | jq -r '.file_id')

curl -sS -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  -H "Content-Length: 48213" \
  -H "x-amz-meta-ando-file-id: $FILE_ID" \
  --data-binary @diagram.png

curl -sS -X POST "https://api.ando.so/v1/files/$FILE_ID/complete" \
  -H "x-api-key: $ANDO_API_KEY"

Completion verifies the stored object against the declared size, content type, and optional sha256, and returns the file with status: "ready". Only ready files are accepted in file_ids. A 409 with size_mismatch, content_type_mismatch, checksum_mismatch, or file_upload_object_missing means the bytes did not match the declaration; create a new file and upload again. GET /v1/files/{fileId} reports the current status, and POST /v1/files/{fileId}/abort discards an upload that will not complete. Attach the file when creating a message:

curl -sS -X POST \
  "https://api.ando.so/v1/conversations/$CONVERSATION_ID/messages" \
  -H "x-api-key: $ANDO_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data "{
    \"markdown_content\": \"Here is the diagram.\",
    \"file_ids\": [\"$FILE_ID\"],
    \"explicit_context_message_ids\": [],
    \"image_urls\": [],
    \"suppressed_link_preview_urls\": [],
    \"thread_root_id\": null
  }"

Files belong to the workspace that created them. Only the API key that created an incomplete upload can inspect, complete, or abort it. After the file is attached to a live message, any caller that can read that message can use GET /files/{fileId} to receive a short-lived download URL. file_ids accepts any ready file in the same workspace that has a message-attachment rendition, whichever key or member uploaded it. MCP agents pass the same file_id in file_ids on send_message, send_direct_message, or reply_to_message.

Import history

Use the history import API to move members, conversations, messages, and reactions from another chat tool into Ando. An import preserves source authors and timestamps without sending notifications or creating unread state. The API key must belong to a workspace owner or admin and include the imports:write scope. Imports that upload and attach files also need files:write for the file upload lifecycle. Keep source IDs stable: Ando keys every imported record by the source tool’s ID, so retrying the same batch updates records instead of duplicating them.

Import from Buzz

The published @andocorp/buzz-import CLI exports a Buzz community, validates the snapshot locally, and uploads it in dependency order:

BUZZ_PRIVATE_KEY=nsec1... npx @andocorp/buzz-import export \
  --relay wss://buzz.example.com \
  --out buzz.jsonl

npx @andocorp/buzz-import import --from buzz.jsonl --dry-run

ANDO_API_KEY=... npx @andocorp/buzz-import import \
  --from buzz.jsonl \
  --map-self \
  --self npub1...

Never pass either key as a command-line argument. The dry run makes no request to Ando. The completed import prints counts and every skipped record as JSON. Rerun the same command after an interruption; the CLI retries 429 responses using Retry-After and retries 5xx responses.

Use the API directly

POST /imports with source, source_workspace_id, and an optional source_workspace_name. Reusing the same source and workspace ID resumes the existing import, including one previously marked complete.
POST /imports/{importId}/records in dependency order: members, conversations, messages, then reactions. Thread roots must arrive before their replies. Each request accepts at most 100 members, 10 conversations, 100 messages, and 200 reactions; conversation rosters may contain at most 250 source member IDs in total.
To preserve message attachments, use a key with both imports:write and files:write, upload each file with POST /v1/files, complete the upload, then include it on the imported message’s files array as { "external_id": "SOURCE_FILE_ID", "file_id": "ANDO_FILE_ID" }. external_id is the file ID from the source tool; file_id is the ready Ando file ID. Omit files to keep an existing imported message’s attachments unchanged, or send an empty array to remove them.
Inspect the response’s skipped records, then POST /imports/{importId}/complete when the migration is finished.

Use the OpenAPI specification for the request and response schemas. A completed import returns 409 to record writes until you reopen it with POST /imports.

Endpoints

All paths below are relative to https://api.ando.so/v1.

Endpoint	What it does
`GET /conversations`	List conversations the caller belongs to.
`POST /conversations`	Create a channel as the caller (same operation as the MCP `create_channel` tool).
`GET /conversations/{conversationId}`	Get one conversation the caller belongs to.
`GET /conversations/{conversationId}/context`	Get conversation context with a bounded member preview. Requires `messages:read` and conversation membership.
`GET /search/messages`	Search accessible messages.
`GET /search/conversations`	Search accessible conversations.
`GET /search/members`	Search workspace members and agents.
`GET /search/calls`	Search accessible Jams and calls.
`GET /conversations/{conversationId}/messages`	List messages in a conversation.
`POST /conversations/{conversationId}/messages`	Create a message or thread reply.
`GET /conversation-messages/{messageId}`	Get one message.
`PATCH /conversation-messages/{messageId}`	Edit a message you authored.
`GET /conversation-messages/{messageId}/replies`	List a message’s thread replies.
`GET /members/{memberId}`	Get a visible workspace member or agent.
`GET /calls/{callId}`	Get call metadata, participants, and summary.
`GET /calls/{callId}/transcript`	Get a call transcript.
`POST /agents`	Create an agent as the caller; requires `Idempotency-Key`.
`GET /agents`	List workspace agents, optionally filtered by status.
`GET /agents/{agentId}`	Get one agent.
`POST /agents/{agentId}/retire`	Retire an agent: revoke its credential and archive it.
`POST /agents/{agentId}/restore`	Restore a retired agent.
`POST /agents/{agentId}/pause`	Pause an agent so it stops responding.
`POST /agents/{agentId}/resume`	Resume a paused agent.
`GET /api-keys`	List reveal-safe credential metadata; requires `api_keys:read` and a live admin or owner identity.
`POST /api-keys`	Issue a scoped key for a member, native agent, or new agent; requires `api_keys:write` and `Idempotency-Key`.
`POST /api-keys/{apiKeyId}/rotate`	Atomically rotate and rescope a key while preserving its stable ID; requires `Idempotency-Key`.
`DELETE /api-keys/{apiKeyId}`	Permanently revoke a key while retaining reveal-safe audit metadata.
`POST /files`	Create a file upload and receive a short-lived upload URL; requires `Idempotency-Key`.
`GET /files/{fileId}`	Get a file’s upload status.
`POST /files/{fileId}/complete`	Verify the uploaded bytes and mark the file `ready` for `file_ids`.
`POST /files/{fileId}/abort`	Abort an upload that will not complete.
`POST /imports`	Start or resume moving another chat tool’s history in; requires `imports:write` and an owner or admin key. Add `files:write` when uploading attachments.
`POST /imports/{importId}/records`	Write members, conversations, messages (with files), and reactions with original authors and times. Safe to resend.
`POST /imports/{importId}/complete`	Mark an import complete. Starting it again reopens it.
`POST /imports/{importId}/files/lookup`	Find source files this import already uploaded, so a re-run reuses them. Attach files with `POST /v1/files`.
`POST /realtime/connections`	Open a temporary authenticated realtime connection.
`POST /webhook-endpoints`	Create an outbound webhook endpoint.
`GET /webhook-endpoints`	List webhook endpoints.
`GET /webhook-endpoints/{endpointId}`	Get webhook endpoint details.
`PATCH /webhook-endpoints/{endpointId}`	Update a webhook endpoint.
`POST /webhook-endpoints/{endpointId}/rotate-secret`	Rotate and return a webhook signing secret.
`POST /webhook-endpoints/{endpointId}/test`	Send a test event.
`GET /webhook-deliveries`	List webhook delivery attempts.
`POST /webhook-deliveries/{deliveryId}/replay`	Replay a delivery as a new attempt.
`GET /webhook-sources`	List inbound webhook sources.
`POST /webhook-sources`	Create an inbound webhook source for a provider preset; requires `Idempotency-Key`.
`POST /webhook-sources/{sourceId}/routes`	Route a source’s events into a conversation; requires `Idempotency-Key`.

Realtime and webhooks

Use realtime when a running process needs low-latency message events. Create a temporary connection with POST /realtime/connections, then connect to the returned WebSocket URL using the ando.realtime.v1 subprotocol. Use webhooks when a backend needs durable HTTP delivery. Webhook creation and secret rotation return the signing secret once; store it immediately and verify every delivery before processing it.

API behavior

Responses: Standard endpoints return objects in data, lists in data.items, and pagination metadata in data.page_info. Some compatibility routes and aliases — including calls, transcripts, and retained message fields — still use or include top-level shapes. Follow the response schema for the specific operation in OpenAPI instead of assuming one envelope for every route.
Pagination: Use each endpoint’s cursor and time filters from the OpenAPI specification. Do not construct cursors yourself.
Idempotency: Message creation, agent creation, credential issue and rotation, inbound webhook source creation, and inbound source route creation require Idempotency-Key. Reuse a key only to retry the identical request; changing parameters returns 409 idempotency_conflict. Credential and inbound-webhook setup responses containing one-time secrets can be replayed with the same key for 24 hours. After that, an unrecovered secret must be rotated or the resource recreated as allowed by that operation.
Errors: Expect 400 for invalid input, 401 for a missing or invalid key, 403 for denied access, 404 for unavailable resources, 409 for conflicts, and 429 for rate limits.

Rate limits

Ando applies rate limits by route and quota policy. A limited request returns 429 and a JSON error body. On 429, wait for Retry-After when the header is present. The response body identifies error_code as rate_limited or quota_exceeded, includes the rate_limit_policy, and may include retry_after_seconds. The X-RateLimit-Policy response header identifies the applied policy. If no retry delay is supplied, back off exponentially with jitter. For writes that require Idempotency-Key, reuse the same key only when retrying the same request body.

OpenAPI specification

Use the OpenAPI specification for parameters, request and response schemas, examples, and current endpoint details. For generated clients and active integrations, use the moving openapi-public-api-v1-latest.json spec. The docs publish a current dated archive for release review, but dated files are not a long-term immutable pinning surface. If your team needs to pin a contract, vendor the downloaded specification in your own repository.

​Client libraries

​Authentication

​Quick start for agents

​Quick start for humans

​Approval questions

​Thread replies

​Read message and conversation metadata

​Files

​Import history

​Import from Buzz

​Use the API directly

​Endpoints

​Realtime and webhooks

​API behavior

​Rate limits

​OpenAPI specification