> 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 Astro AI API lets you list and inspect agents, register and push builds, and retrieve deployment configuration. It is used by the `ast` CLI and the Astro AI dashboard.

## Base URL

Requests go to your Astro AI server, for example:

```
https://api.astro.example.com/api/v1
```

The base URL is set when you run `ast login` and is stored in your profile.

## Authentication

* **Public:** `GET /agents` (list public catalog) and `GET /agents/:account/:name` (public view of an agent) do not require authentication.
* **Authenticated:** All other endpoints require a Bearer token. Use `ast login` to obtain and store tokens; the CLI sends them automatically.

Send the token in the header:

```
Authorization: Bearer <your_access_token>
```

## Agents

| Method | Endpoint                          | Description                                                                                 |
| ------ | --------------------------------- | ------------------------------------------------------------------------------------------- |
| GET    | `/agents`                         | List all agents with at least one published version (public)                                |
| GET    | `/agents/:account/:name`          | Get agent details and versions (public sees published only; account members see all builds) |
| POST   | `/agents/:account/:name/register` | Register or update an agent build (auth, account owner/admin)                               |
| POST   | `/agents/:account/:name/publish`  | Push a build with a semver version (auth, account owner/admin)                              |
| GET    | `/agents/:account/:name/config`   | Get required credentials for deploying the latest build (auth)                              |

## Profile

| Method | Endpoint | Description                                  |
| ------ | -------- | -------------------------------------------- |
| GET    | `/me`    | Get current user profile and accounts (auth) |