API overview

Ando’s public API is for server-side integrations that need workspace context: search messages and workspace records, read conversation history, and create messages or replies with an API key.

API or SDK?

The API is the network contract. The SDK is a Node.js and TypeScript client that calls that same API.

Use	Choose
Any server language, raw HTTP or WebSocket, or exact protocol control	Call the API directly.
Node.js or TypeScript with typed methods, retries, automatic idempotency keys, and webhook helpers	Use `@andocorp/sdk`.

Both use the same API keys, permissions, rate limits, and workspace data. The SDK does not add endpoints or act as a separate backend. When the two differ, the generated endpoint reference describes what the server currently accepts. The stable, supported part of public API v1 is built around two jobs:

Find context: search messages, conversations, workspace members, and calls.
Work with messages: list, create, fetch, and reply to conversation messages.

Other endpoints exist for testing or older compatibility, but they are not the first surface new integrations should build on.

Get an API key

Start with Which key do I use? if you are choosing between a member key, third-party agent key, workspace or service key, MCP bearer setup, realtime ticket, or webhook signing secret. For a human-owned public API integration, create a member API key in Ando:

Open Settings.
Go to API keys.
Create or copy an API key.
Store it as a secret in your server-side environment.

Use Third party agents instead when you want messages to be attributed to an agent identity rather than a human workspace member. Use a workspace or service key when the integration should be owned by the workspace rather than one person.

Base URL and authentication

All public API v1 requests use this base URL:

https://api.ando.so/v1

Use x-api-key as the canonical auth header:

export ANDO_API_BASE="https://api.ando.so/v1"
export ANDO_API_KEY="ando_sk_..."

curl -sS "$ANDO_API_BASE/search/messages?q=release" \
  -H "x-api-key: $ANDO_API_KEY"

Bearer transport is still accepted for compatibility:

Authorization: Bearer ando_sk_...

Do not use https://api.ando.so/api/v1 for public API v1 clients.

Resource model

The API is scoped to the workspace attached to the API key. Results only include workspace resources the key can access.

Resource	What it means
Conversation	A channel or DM.
Message	A conversation message or thread reply.
Workspace member	A human user profile or agent profile visible in the workspace.
Call	A Jam or recorded call with metadata and transcript context.
Task	A visible task and recent work context.
Clipboard	A saved context bundle.

Identity terms are narrower than storage table names:

Term	What it means
Human user	A person who belongs to a workspace.
Agent	A connected or 3rd-party agent identity that can be visible in the workspace.
Workspace member profile	The visible human user or agent profile returned by member-shaped v1 routes.
Principal	The actor Ando authorizes for a request, derived from the API key or connected-agent identity.
Author	The profile Ando attaches to a message or reply after it derives authorship from the request principal.
API-key owner	The workspace user or agent identity that created or owns the key.

Some v1 names preserve compatibility spellings, such as /search/members, /members/{memberId}, MemberResult, and author_id. Treat these as workspace-member and message-author identifiers, not as a separate public resource model.

Stability levels

In this guide, stable means generally available: supported for production integrations and covered by the public API v1 compatibility promise.

Level	Use it for	Routes
Stable	Production integrations. These routes are monitored and supported as public API v1.	`/search/messages`, `/search/conversations`, `/search/members`, `/search/calls`, `/conversations/{conversationId}/messages`, `/conversation-messages/{messageId}`, `/conversation-messages/{messageId}/replies`
Preview	Exploratory integrations. Expect tighter compatibility review before building durable workflows.	`/members/{memberId}`, `/calls/{callId}`, `/calls/{callId}/transcript`, `/tasks/{taskId}`, `/tasks/{taskId}/updates`, `/realtime/connections`, `/webhook-endpoints`, `/webhook-endpoints/{endpointId}`, `/webhook-endpoints/{endpointId}/rotate-secret`, `/webhook-endpoints/{endpointId}/test`, `/webhook-deliveries`, `/webhook-deliveries/{deliveryId}/replay`
Legacy compatibility	Existing behavior kept documented while the public API converges. Avoid for new integrations unless no stable route exists.	`/search/clipboard`, `/clipboards/{clipboardId}`

The endpoint reference includes the exact status for every operation.

Response envelopes

Successful object responses return the resource under data:

{
  "data": {
    "id": "msg_...",
    "conversation_id": "conv_...",
    "content": "Hello from the public API."
  }
}

Search and list responses return items under data.items:

{
  "data": {
    "items": [
      {
        "id": "msg_...",
        "conversation_id": "conv_..."
      }
    ],
    "page_info": {
      "has_next_page": false,
      "next_cursor": null
    }
  }
}

Some current v1 responses also include deprecated top-level compatibility aliases such as items or pageInfo. New clients should read data, data.items, and data.page_info.

Pagination

List and search routes accept limit plus cursor or time filters where the endpoint supports them. Page using the cursor returned in data.page_info:

curl -sS "$ANDO_API_BASE/conversations/$CONVERSATION_ID/messages?limit=20" \
  -H "x-api-key: $ANDO_API_KEY"

Use before for older conversation messages. Use after and before filters on search routes when you need a time-bounded search.

Writes and idempotency

Message creation (POST /conversations/{conversationId}/messages) requires an Idempotency-Key header and replays idempotently. Reuse the same key only when retrying the same request body after a timeout or network failure. Use a new key for a distinct message.

curl -sS -X POST "$ANDO_API_BASE/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 public API.",
    "explicit_context_message_ids": [],
    "image_urls": [],
    "suppressed_link_preview_urls": []
  }'

Public API clients do not choose the author. Ando derives authorship from the API key or connected-agent identity. Task updates (POST /tasks/{taskId}/updates) accept an Idempotency-Key header but do not replay idempotently today. For concurrency protection, send the optional expected_state_version body field instead — a stale version returns 409. Other write routes do not use idempotency keys.

Errors

Most public v1 errors use a structured envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "Idempotency-Key is required.",
    "request_id": "req_..."
  }
}

Status	Meaning
`400`	The request shape failed validation, or a write is missing `Idempotency-Key`.
`401`	The API key is missing or invalid.
`403`	The key is valid but cannot access the requested workspace resource.
`404`	The requested resource was not found or is not visible to the key.
`409`	The request conflicts with an existing idempotency key or resource state.
`429`	The key hit a public API rate limit.
`5xx`	Server-side failure. Retry writes with the same idempotency key.

Compatibility endpoints may return the older error, error_code, and missing_scopes shape. The endpoint reference shows the exact response schema.

Recommended first workflow

Start with the stable message workflow:

Search messages with GET /search/messages.
List recent conversation history with GET /conversations/{conversationId}/messages.
Create a message with POST /conversations/{conversationId}/messages.
Fetch the created message with GET /conversation-messages/{messageId}.
Reply or inspect replies with the thread endpoints.

Follow the messaging quickstart for the copy-pasteable curl workflow, then use the endpoint reference for full schemas.

Start here

Agent integrations

API workflows

Tools

Reference

API overview

API or SDK?

Get an API key

Base URL and authentication

Resource model

Stability levels

Response envelopes

Writes and idempotency

Errors

Recommended first workflow

​API or SDK?

​Get an API key

​Base URL and authentication

​Resource model

​Stability levels

​Response envelopes

​Pagination

​Writes and idempotency

​Errors

​Recommended first workflow

API or SDK?

Get an API key

Base URL and authentication

Resource model

Stability levels

Response envelopes

Pagination

Writes and idempotency

Errors

Recommended first workflow