# RunAgencyOS API documentation

Public documentation for https://runagencyos.com.

The docs are public. The API is not. Every authenticated call needs credentials created inside a signed-in workspace.

## Base URL

- Product and API share the host: `https://runagencyos.com`
- REST: `https://runagencyos.com/api/v1/...`
- MCP: `https://runagencyos.com/mcp/` (keep the trailing slash)
- Health: `https://runagencyos.com/healthz`

## Authentication

### Web / REST (JWT)

Sign in through the product. The app uses a short-lived access JWT plus an httpOnly refresh cookie. Authed REST calls send:

```http
Authorization: Bearer <access_token>
X-Workspace-Id: <workspace_uuid>
```

Workspace API keys are **not** a general REST authentication method today.

### MCP / agents (API keys)

Owners and admins create keys in **Settings → API Keys & MCP**.

- Prefix: `af_`
- Header: `Authorization: Bearer af_...`
- Scopes: `read`, `write`, optional `unattended`
- Shown once at creation; hashed at rest; revocable

Example (Claude Code):

```bash
claude mcp add --transport http runagencyos https://runagencyos.com/mcp/ \
  --header "Authorization: Bearer <YOUR_API_KEY>"
```

## Machine-readable

- OpenAPI overview: https://runagencyos.com/openapi.json
- Agent index: https://runagencyos.com/llms.txt
- This file: https://runagencyos.com/docs.md
- Human page: https://runagencyos.com/docs

## Important gaps

- No anonymous API access.
- REST API-key auth for arbitrary `/api/v1` routes is not implemented yet; use MCP for agent automation today.
- FastAPI interactive Swagger UI is disabled in production so "Try it out" cannot become an unauthenticated back door.
