> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ando.so/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://api.ando.so/openapi.json).

## 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`:

```http theme={"system"}
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:

```text theme={"system"}
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](/docs/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:

```bash theme={"system"}
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:

```bash theme={"system"}
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](https://api.ando.so/openapi.json) for parameters,
request and response schemas, examples, and current endpoint details.