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, and the startRealtimeClient reference realtime client from @andocorp/sdk/realtime. It does not export AndoClient, and it does not manage request retries or idempotency keys. Call the HTTP endpoints directly. For live events, use the reference realtime client or open a realtime connection yourself 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	Settings → API access	A script or service should act as you.
Agent	Studio → Agents → Create agent → External	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 Settings → API access and choose Provisioning key from the key 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
  Studio → Agents → Create agent → External.
- 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 in Settings → API access, 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
  }'

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.

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. GET /files/{fileId}, complete, and abort are limited to the API key that created the upload; 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.

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 /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.
`PUT /agent-tool-discoveries/{discoveryId}`	Submit a requested connected-tools snapshot as the authenticated external 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 an existing member or a new named 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 /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. On 429, wait for Retry-After when present; the JSON body identifies error_code (rate_limited or quota_exceeded), rate_limit_policy, and sometimes retry_after_seconds, while X-RateLimit-Policy identifies the applied policy. If no retry delay is supplied, use exponential backoff with jitter.

OpenAPI specification

Use the OpenAPI specification for parameters, request and response schemas, examples, and current endpoint details.

​Client libraries

​Authentication

​Quick start for agents

​Quick start for humans

​Thread replies

​Files

​Endpoints

​Realtime and webhooks

​API behavior

​OpenAPI specification