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

# asobeast API

> The asobeast API is a REST API over HTTP. Every endpoint requires authentication with a session cookie or a personal API token, and every response is JSON.

The asobeast API is the same API the dashboard uses. Every endpoint on it requires authentication, and the endpoint pages in this tab are generated from the API's own OpenAPI document.

## Base URL

There are two, and which one you use depends on where your code runs.

| Base URL                        | Use when                                                                                       |
| ------------------------------- | ---------------------------------------------------------------------------------------------- |
| `https://your-host/api/backend` | Almost always. This is the web origin proxy, which is reachable from anywhere the dashboard is |
| `http://localhost:4000`         | Only when your code runs on the same host as the API container                                 |

The proxy path is not a convenience wrapper. In the Compose stack the API stays on a private network and is never published, so the web origin is the only way in from outside the host. The proxy forwards your `Authorization` header unchanged.

## Authentication

Send a personal API token as a bearer header on every request. See [Authenticate API requests](/api-reference/authentication).

## Content type

JSON in, JSON out. Send `Content-Type: application/json` on any request with a body. Errors are JSON too, in a consistent envelope. See [Error responses](/api-reference/errors).

## The OpenAPI document

Your own instance serves it at `/docs-json`, with human readable documentation at `/docs`.

Both are gated by `API_DOCS`, which defaults to `owner`. An unauthenticated request answers `404` rather than `401`, because the surface does not confirm it exists. See [The queue dashboard and the OpenAPI surface](/security/admin-surfaces).

The copy powering the endpoint pages in this tab is committed in the repository, so this documentation site never needs a running instance to build.

## Generate a client

Any OpenAPI generator works against the document.

```bash theme={null}
curl -H "Authorization: Bearer asob_…" \
  https://your-host/api/backend/docs-json > openapi.json

npx @openapitools/openapi-generator-cli generate \
  -i openapi.json -g typescript-fetch -o ./asobeast-client
```

If you write TypeScript, consider using `@asobeast/shared` directly instead. It holds the same contract types the API and the dashboard are built from, which is what the MCP server does.

## Related

<CardGroup cols={2}>
  <Card title="API conventions" icon="ruler" href="/api-reference/conventions">
    UTC dates, 1 based positions, 202 for queued work.
  </Card>

  <Card title="Personal API tokens" icon="key-round" href="/security/api-tokens">
    Mint and revoke the credential.
  </Card>
</CardGroup>