> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# API reference

The Astropods API is the API the `ast` CLI and the Astropods dashboard use. Every endpoint they call is in this reference.

## Base URL

```
https://astropods.com/api/v1
```

Endpoint paths in this reference include the `/api/v1` prefix.

WebSocket endpoints, such as a sandbox terminal, use the same host over `wss://`.

## Authentication

Send a bearer token in the `Authorization` header:

```
Authorization: Bearer <token>
```

| Caller                              | Token                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------ |
| You, from the CLI or a script       | Your access token. Run `ast login` to get one; the CLI sends it for you. |
| An agent, calling back to Astropods | The deployment's token, available to the agent as `ASTRO_AUTHZ_TOKEN`.   |

Each endpoint lists the token it accepts. A few endpoints, such as listing public agents, need no token.

## Errors

A failed request returns a JSON body:

```json
{
  "error": "agent not found"
}
```

`error` describes the failure. Some endpoints add `details` with more context, and a `code` you can match on.