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 and tasks, 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.

Authentication

Choose the identity that should own the request:

Caller	Create the key	Use it when
Human	Settings → API keys	A script or service should act as you.
Agent	Studio → Agents → Create agent → Third-party 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.

Quick start for agents

Create a third-party 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 → Third-party 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 member API key in Settings → 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
  }'

Endpoints

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

Endpoint	What it does
`GET /conversations`	List conversations 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 /search/tasks`	Search visible tasks.
`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.
`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.
`GET /tasks/{taskId}`	Get task context, entries, and resources.
`POST /tasks/{taskId}/updates`	Record a task update and optional resource changes.
`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 /search/clipboard`	Search saved clipboards; legacy compatibility only.
`GET /clipboards/{clipboardId}`	Get a saved clipboard; legacy compatibility only.

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: Read objects from data and lists from data.items. Pagination metadata lives in data.page_info.
Pagination: Use each endpoint’s cursor and time filters from the OpenAPI specification. Do not construct cursors yourself.
Retries: Message creation requires Idempotency-Key and safely replays the same request. Use a new key for a different message.
Task updates: Use expected_state_version to prevent stale concurrent writes; do not assume task-update retries replay idempotently.
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.

OpenAPI specification

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

​Authentication

​Quick start for agents

​Quick start for humans

​Endpoints

​Realtime and webhooks

​API behavior

​OpenAPI specification