# API

Everything the dashboard does, it does through a REST API, and you can use the same one.

- **Reference and explorer**: [api.runalf.com/docs](https://api.runalf.com/docs). Every endpoint, its parameters and its request body, with a console to try them.
- **OpenAPI document**: [api.runalf.com/openapi.json](https://api.runalf.com/openapi.json) (OpenAPI 3.1), for generating a client or importing into Postman, Insomnia and the like.

The reference is generated from the API's own routes and validation rules, so it describes what's running, not what someone remembered to write down.

## A first call

Log in for an access token, then send it as a bearer token:

```bash
curl -s https://api.runalf.com/api/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","password":"…"}'
```

```bash
curl -s https://api.runalf.com/api/v1/auth/me \
  -H "authorization: Bearer $ACCESS_TOKEN"
```

The access token is valid for 15 minutes. `POST /api/v1/auth/refresh` trades the refresh token for a new pair (the old refresh token stops working).

## Good to know

- Ids look like `svc_…`, `prj_…`, `srv_…`: the prefix says what it is.
- Errors are JSON, `{ "error": { "code", "message", "details" } }`. A 422 says which fields are wrong.
- Lists come as `{ "data": [...] }`.
- Secrets are write-only: their values never come back.
- What you may do follows your role in the organization, as in the dashboard.

## For coding agents

Agents don't use this API. They use the MCP endpoint at `https://api.runalf.com/mcp`, with an [agent token](/docs/agents) or by signing in: the same abilities, as tools, with limits and approvals. See [Coding agents](/docs/agents).