# The AQ API

> The AQ API is AQ's REST, MCP, and webhook surface: create workspaces, read events, PRs, and previews, run AQ's built-in agent, and react via signed webhooks.

Updated October 27, 2026 (first published August 1, 2026) · by the AQ team · Canonical: https://aq.dev/docs/api/

The AQ API is the programmatic interface to AQ workspaces: a versioned REST API at `https://aq.dev/v1`, a hosted MCP server at `https://aq.dev/mcp`, and signed outbound webhooks, all operating on the same workspaces with the same permission model as the AQ dashboard. The REST API lists, creates, and closes workspaces, reads each workspace's event log, tracked pull requests, and preview URLs, and starts, steers, stops, and archives conversations with AQ's built-in agent. The MCP server exposes those same operations as tools, plus tools to find, read, and message any work item or bot, so any MCP-compatible agent can discover and call them directly, and webhooks push workspace activity to your service so it reacts without polling. The complete machine-readable contract is the OpenAPI 3.1 document at [undefined](https://aq.dev/v1/openapi.json).

Every surface authenticates with scoped API keys that act as the person who created them, and every REST write is retry-safe through idempotency keys. API keys, the REST API, webhooks, and the MCP server are available on every [plan](https://aq.dev/pricing/), Free included. This guide takes you from a new API key to a working integration, including copy-paste tests that do not change data.

## Start here

| Surface | URL | Use it when |
| --- | --- | --- |
| REST API | `https://aq.dev/v1` | Your application needs predictable requests, responses, pagination, and retry-safe writes. |
| MCP server | `https://aq.dev/mcp` | An MCP-compatible agent should discover and use AQ tools directly. |
| Webhooks | Configured through `/v1/webhooks` | Your service should react to workspace, pull request, agent, Linear, comment, or runner events. |
| OpenAPI | [undefined](https://aq.dev/v1/openapi.json) | You need the complete machine-readable OpenAPI 3.1 contract or want to generate a client. |

The fastest safe test is: create a read-only key, call `GET /v1/me`, list workspaces, then ask the MCP server for its tool list. Those calls are all read-only.

## In this guide

- [Create a key and make the first read-only request](#quickstart)
- [Choose scopes and understand the permission model](#authentication)
- [Find the complete REST endpoint map](#rest-reference)
- [Implement workspace, event, and agent-event pagination](#pagination)
- [Retry REST writes safely with idempotency keys](#idempotency)
- [Create, inspect, and close a test workspace](#workspace-example)
- [Start, poll, steer, stop, and archive an AQ agent run](#agent-runs)
- [Follow a run live over server-sent events](#run-stream)
- [Merge a pull request, and name your client](#merge)
- [Run a crew with role picks and limits, and answer its questions](#crews-limits)
- [Know when a workspace is prepared, and coordinate dependency installs](#preparation)
- [Connect and test an MCP client](#mcp)
- [Register, verify, deduplicate, and troubleshoot webhooks](#webhooks)
- [Handle errors and rate limits](#errors)
- [Run the safe production smoke-test checklist](#smoke-test)

## Quickstart: authenticate and make your first request

### 1. Create an API key

Open [AQ Settings](https://aq.dev/settings), choose Connections, find API keys, and select Create key. Give the key a name that identifies its consumer, such as `release-bot` or `local-mcp-test`, then select only the scopes it needs.

Keys start with `aq_` and are shown exactly once. AQ stores only a SHA-256 hash of the key. Copy it into your password manager or secret store before leaving the creation screen.

### 2. Put the key in your shell without saving it in history

```
read -rsp "AQ API key: " AQ_API_KEY
export AQ_API_KEY
echo
```

Do not commit the key, put it in a query string, paste it into an issue, or expose it to browser-side JavaScript. Revoke a key immediately from Settings if it may have leaked.

### 3. Verify the key and its scopes

```
curl -fsS https://aq.dev/v1/me \
  -H "Authorization: Bearer $AQ_API_KEY" | jq
```

A successful response identifies the user and team the key acts as, along with the scopes attached to it:

```
{
  "user": {
    "id": "user-id",
    "email": "you@example.com",
    "name": "Your Name"
  },
  "tenant_id": "tenant-id",
  "account_id": "account-id",
  "scopes": ["workspaces:read", "events:read"],
  "key_id": "ak_..."
}
```

### 4. Make a read-only request

```
curl -fsS "https://aq.dev/v1/workspaces?limit=5" \
  -H "Authorization: Bearer $AQ_API_KEY" | jq
```

Workspace responses use stable, public field names such as `id`, `title`, `status`, `repo_id`, `branch_name`, `pr_url`, and timestamps. Runner identifiers, filesystem paths, credentials, and raw infrastructure errors are never included.

## Authentication, permissions, and scopes

Send the key as an HTTP Bearer token on every REST or MCP request:

```
Authorization: Bearer aq_your_key
```

An API key is personal, not a team-wide service account. It acts as the user who created it, sees only workspaces that user can access, and is re-checked against live team and account membership. Revoking the key, removing the user, or suspending the account stops access. API keys never inherit AQ host-operator privileges.

| Scope | Allows | Typical use |
| --- | --- | --- |
| `workspaces:read` | List and fetch workspaces and connected repos | Dashboards, inventory, MCP discovery |
| `workspaces:write` | Create and close workspaces | Issue intake, automation, workspace lifecycle |
| `events:read` | Read workspace event logs | Activity feeds and polling integrations |
| `prs:read` | Read pull requests tracked for a workspace | Release and review workflows |
| `prs:merge` | Merge a work item's pull request on the key's person's behalf. Never on a key unless someone ticks it | A software factory that merges green work |
| `previews:read` | Read preview status and URLs | QA links and review dashboards |
| `webhooks:manage` | List, create, and delete webhook endpoints | Event-driven integrations |
| `agent:run` | Start, inspect, steer, stop, and archive AQ agent conversations | Agent orchestration from applications or other agents |
| `secrets:read` | List the names of the secrets the key's user can use (never values) | Checking which environment variables a work item will have |
| `bots:read` | See the key's user's bots: routines, runs, usage, the work items they started, open questions, sharing, accounts and library | Dashboards and oversight from another agent |
| `bots:operate` | Everything in `bots:read`, plus run routines, message bots, answer their questions and approvals, pause and resume bots and routines | Day-to-day operation from another agent |
| `bots:manage` | Everything in `bots:operate`, plus create, change, share, archive and restore bots, and add, change and delete routines | Letting another agent set bots up |
| `pages:read` | List and read the AQ Pages the key's user can open: text, HTML and screenshots | Reading a spec or report another agent published |
| `pages:write` | Everything in `pages:read`, plus publish, update, share, guest-link and delete pages | Publishing reports and dashboards from another system |

The bot scopes form a ladder: `bots:manage` includes `bots:operate`, which includes `bots:read`. Keys created before the bot scopes keep the routes they had: `workspaces:read` still lists bots and reads their routines, runs and threads, `workspaces:write` still adds, changes, pauses, resumes and deletes routines, and `agent:run` still runs a routine. Those reads now answer with more than before: `GET /v1/bots`, `GET /v1/bots/{id}` and `list_bots` include a bot's `instructions` and `model` when the key's person owns or manages it, and `GET /v1/bot-runs/{id}` includes the report and outputs of a run that ran as the key's person. Every new action needs a bot scope. MCP connections approved through the browser get `bots:operate` by default; `bots:manage` and `prs:merge` are added only when the person ticks them on the consent screen. A key never gets more than its person: it sees and changes only the bots that person can, with the same owner, manager and member rules as the app.

Use separate keys for separate consumers. A read-only reporting job should not share a key with a system that creates workspaces or runs agents.

## REST API reference by task

Every endpoint except the public OpenAPI document requires a Bearer key. Methods and paths below are the current `v1` surface.

| Method | Path | Scope | Purpose |
| --- | --- | --- | --- |
| GET | `/v1/me` | Any valid key | Inspect the acting user, team, key id, and scopes. |
| GET | `/v1/account` | Any valid key | Everything onboarding needs in one read: the account and plan, the machines you can use (with status), your connected agent subscriptions, the organization's repositories and your connected tools. |
| GET | `/v1/connected-apps` | `agent:run` | Your connected app accounts (Gmail, Slack, Vanta, Stripe and more), each with the name it is called everywhere in AQ and that agents read to pick an account. |
| PATCH | `/v1/connected-apps/{id}` | `agent:run` | Name one of your connected app accounts, for example two Vanta accounts "Betterleap" and "AQ". An empty name puts it back on its default. Audited. |
| GET | `/v1/crews` | `workspaces:read` | The organization's crews (Ship, Review, Fix and its own) with their roles and plan gate, and every role. |
| PUT | `/v1/workspaces/{id}/role-picks` | `workspaces:write` | Set what each crew role runs on for one work item (owner only). See [Crews, run limits and questions](#crews-limits). |
| POST | `/v1/agent-sessions/{id}/crew` | `agent:run` | Make an existing conversation a crew's Lead (it keeps its model), optionally with role picks. |
| GET | `/v1/agent-sessions/{id}/stream` | `agent:run` | Server-sent events for the whole run, with resume from a cursor. See [Follow a run live](#run-stream). |
| GET | `/v1/agent-sessions/{id}/updates` | `agent:run` | The same events as a poll: the run's snapshot and the events after `after_seq`. |
| GET | `/v1/agent-sessions/{id}/limits` | `agent:run` | A run's limits and what it has used so far. |
| PUT | `/v1/agent-sessions/{id}/limits` | `agent:run` | Set, replace or clear a run's spend and wall-time limits. |
| GET | `/v1/agent-sessions/{id}/questions` | `agent:run` | Open questions the run and its crew members wait on (questions, plans to approve, approvals), each with its `request_id`. |
| POST | `/v1/agent-sessions/{id}/questions/answer` | `agent:run` | Answer one as the key's user. One-time decisions only. |
| POST | `/v1/agent-sessions/{id}/plan` | `agent:run` | Decide a crew Lead's plan: `approve`, `edit` (with a `note`) or `one_thread`. |
| GET | `/v1/secrets` | `secrets:read` | List secret names and scopes (organization and the user's personal secrets). Values are never returned. |
| GET | `/v1/repos` | `workspaces:read` | List repositories connected to the team. |
| POST | `/v1/imports/workspaces` | `workspaces:write` | Import one workspace from another agent tool (used by the AQ importer) as your own private work item on its branch. |
| POST | `/v1/imports/{id}/sessions` | `workspaces:write` | Add one Claude Code or Codex conversation to an imported workspace (scrubbed; resumable on AQ). |
| POST | `/v1/imports/{id}/parts` | `workspaces:write` | Send one part of a conversation or file bigger than one request; imports have no size limit. |
| POST | `/v1/imports/{id}/files` | `workspaces:write` | Add the plans and notes a source tool kept as files to an imported workspace (scrubbed; written into its worktree). |
| GET | `/v1/imports` | `workspaces:read` | Your imports and how far each work item has been set up. |
| GET | `/v1/bots` | `bots:read` | List the bots the key's user can use. Owners and managers also get each bot's `instructions` and `model`. |
| POST | `/v1/bots` | `bots:manage` | Create a bot: `name`, `role`, `instructions`, `character`, `color`, `model` (`"auto"`, an AQ model id, or `{ harness, model, effort }`), `visibility` (`private` or `team`). |
| GET | `/v1/bots/{id}` | `bots:read` | Read one bot. |
| PATCH | `/v1/bots/{id}` | `bots:manage` | Change a bot's name, role, instructions, character, color or model (owner and managers). The answer lists what changed and a `change_id`; the person can undo it in AQ. |
| POST | `/v1/bots/{id}/pause` | `bots:operate` | Pause the whole bot: none of its routines run until it is resumed. |
| POST | `/v1/bots/{id}/resume` | `bots:operate` | Resume a paused bot. |
| POST | `/v1/bots/{id}/archive` | `bots:manage` | Archive a bot (owner): routines stop, chats become read-only. Restorable for 30 days. |
| POST | `/v1/bots/{id}/restore` | `bots:manage` | Restore an archived bot (owner). It comes back paused. |
| POST | `/v1/bots/{id}/messages` | `bots:operate` | Message a bot in the key's user's own chat with it (`{ "text": "..." }`). |
| GET | `/v1/bots/{id}/chat` | `bots:read` | The newest messages of your own chat with a bot (its replies), and whether it is still working. |
| GET | `/v1/bots/{id}/routines` | `bots:read` | List a bot's routines with status and next run. |
| POST | `/v1/bots/{id}/routines` | `bots:manage` | Add a routine; it runs as the key's user. Any trigger the app offers; a schedule without `tz` uses the user's time zone; a webhook trigger answers its URL and secret once. |
| PATCH | `/v1/bots/{id}/routines/{routineId}` | `bots:manage` | Change a routine. Applies at once, except a change that lets someone else's routine do or spend more, which waits for the person it runs as. |
| DELETE | `/v1/bots/{id}/routines/{routineId}` | `bots:manage` | Delete a routine (the bot's owner, its managers or the person it runs as). |
| POST | `/v1/bots/{id}/routines/{routineId}/run` | `bots:operate` | Run a routine now (only the person it runs as). Keys with `agent:run` keep this. |
| POST | `/v1/bots/{id}/routines/{routineId}/pause` | `bots:operate` | Pause a routine; nothing runs until it is resumed (the same people). |
| POST | `/v1/bots/{id}/routines/{routineId}/resume` | `bots:operate` | Resume a paused routine; the answer carries its next run. |
| GET | `/v1/bots/{id}/runs` | `bots:read` | Recent runs, newest first: status, trigger, start and end, cost and a one-line result (`routine_id`, `status`, `limit`, `cursor`). |
| GET | `/v1/bot-runs/{id}` | `bots:read` | One run in full. The person it ran as also gets its report and outputs (what it did). |
| GET | `/v1/bots/{id}/usage` | `bots:read` | Spend in a period (`from`, `to`; default this month) per routine, plus your chats with the bot. |
| GET | `/v1/bots/{id}/work-items` | `bots:read` | Work items the bot started that the user can open, with status and pull request. |
| GET | `/v1/bot-questions` | `bots:read` | What your bots are waiting on you for: open questions and approval cards, each with its `request_id` (`bot_id` to filter). |
| POST | `/v1/bot-questions/answer` | `bots:operate` | Answer one: `{ "request_id": "...", "answer": "Allow once" }` or `answers` per question. One-time decisions only: standing permissions ("Always allow") and secret values are given in AQ. |
| GET | `/v1/bots/{id}/permissions` | `bots:read` | Which connected accounts the bot may use, and your own connections. Runs use the secrets of the person they run as. |
| PUT | `/v1/bots/{id}/permissions` | `bots:manage` | Bind one of your accounts to a need (`need`, `connection_id` or `null`, `shared_with_members`). Owner only. |
| GET | `/v1/bots/{id}/sharing` | `bots:read` | Who the bot is shared with and each person's role. |
| POST | `/v1/bots/{id}/share` | `bots:manage` | Share with teammates (`emails`, `role`, `can_share`) and/or the whole team (`whole_team`). |
| POST | `/v1/bots/{id}/unshare` | `bots:manage` | Stop sharing with people and/or the whole team. |
| GET | `/v1/bots/{id}/library` | `bots:read` | The pages, files, links and notes the bot saved that you may see. |
| GET | `/v1/bots/{id}/library/{itemId}` | `bots:read` | One library item: text, a small file as base64, or a page or link address. |
| GET | `/v1/bots/{id}/threads` | `bots:read` | List your own threads with a bot. |
| GET | `/v1/workers` | `workspaces:read` | List the [background workers](https://aq.dev/docs/background-workers/) of the work items the key can see (`workspace_id` filters). |
| POST | `/v1/workers` | `workspaces:write` | Create or update a worker (`workspace_id`, `name`, `command`, `restart`, `health_check`) and start it, as the key's user. |
| GET | `/v1/workers/{id}` | `workspaces:read` | A worker's live state, restarts, health and who started it. |
| GET | `/v1/workers/{id}/logs` | `workspaces:read` | Its recent output, secret values masked. |
| POST | `/v1/workers/{id}/start` | `workspaces:write` | Start a stopped worker. |
| POST | `/v1/workers/{id}/stop` | `workspaces:write` | Stop it; it stays stopped, also after a machine restart. |
| POST | `/v1/workers/{id}/restart` | `workspaces:write` | Restart it. |
| DELETE | `/v1/workers/{id}` | `workspaces:write` | Stop and remove it. |
| GET | `/v1/workspaces` | `workspaces:read` | List visible workspaces, newest first, with filters (`status`, `repo_id`, `repo_name`, `query`). |
| GET | `/v1/workspaces/count` | `workspaces:read` | Count visible workspaces grouped by status, with the same filters. |
| POST | `/v1/workspaces` | `workspaces:write` | Create a workspace. |
| GET | `/v1/workspaces/{id}` | `workspaces:read` | Fetch one visible workspace. |
| POST | `/v1/workspaces/{id}/close` | `workspaces:write` | Close a workspace and stop its terminals and previews. The answer's `stopped` says what ended and whether the machine confirmed it (`confirmed`); an unconfirmed stop finishes when the machine reconnects. |
| POST | `/v1/workspaces/{id}/owner` | `workspaces:write` | Transfer ownership to another active member (`to_user_id` or `to_email`). The current owner, or an organization owner/admin for any workspace. The previous owner keeps access unless `keep_previous_owner_access` is false; the checkout stays where it is. |
| POST | `/v1/workspaces/{id}/repos` | `workspaces:write` | Add repositories (`repo_ids`) so one agent works across them: each is checked out on the workspace's branch name beside its own repository, up to 6 in all. `POST /v1/workspaces` takes `additional_repo_ids` for the same at creation. Each repository gets its own pull request. |
| POST | `/v1/workspaces/{id}/prepare` | `workspaces:write` | Prepare without an agent: a fresh workspace is checked out and prepared; a prepared one re-runs in place (install dependencies, run the repository's current setup command again). Answers 202; read the result as `prep` on the workspace. |
| GET | `/v1/workspaces/{id}/events` | `events:read` | Read the append-only workspace event log. |
| GET | `/v1/workspaces/{id}/prs` | `prs:read` | List pull requests associated with a workspace. |
| POST | `/v1/workspaces/{id}/prs/{number}/merge` | `prs:merge` | Merge a work item's pull request with the app's rules. See [Merge a pull request](#merge). |
| GET | `/v1/workspaces/{id}/previews` | `previews:read` | Read preview status, visibility, and URLs. |
| POST | `/v1/workspaces/{id}/preview/visibility` | `workspaces:write` | Make the running preview public (`{"public": true}`, Pro plan) or private again (`{"public": false}`). |
| POST | `/v1/workspaces/{id}/agent` | `agent:run` | Start an AQ agent conversation with an initial task. |
| GET | `/v1/agent-sessions/{id}` | `agent:run` | Read agent status, budget state, spend, and timestamps. |
| GET | `/v1/agent-sessions/{id}/events` | `agent:run` | Poll ordered progress events using `after_seq`. |
| GET | `/v1/agent-sessions/{id}/messages` | `agent:run` | Read the conversation transcript, paging with `before_seq` or `after_seq`. |
| POST | `/v1/agent-sessions/{id}/messages` | `agent:run` | Queue a follow-up or start the next turn now. `deliver=now` stops the current turn first. |
| DELETE | `/v1/agent-sessions/{id}/messages/{messageId}` | `agent:run` | Retract a queued message before a turn claims it. |
| PATCH | `/v1/agent-sessions/{id}/messages/order` | `agent:run` | Reorder the queued messages. |
| POST | `/v1/agent-sessions/{id}/messages/{messageId}/deliver` | `agent:run` | Run a queued message next, stopping the current turn if one is in flight. |
| POST | `/v1/agent-sessions/{id}/interrupt` | `agent:run` | Stop the current turn while keeping the conversation open. |
| POST | `/v1/agent-sessions/{id}/resume` | `agent:run` | Resume a resting conversation with the same model and prompt; a session held by a Block setup failure (`setup_blocked`) starts anyway. |
| POST | `/v1/agent-sessions/{id}/archive` | `agent:run` | Close the conversation tab while retaining its transcript. |
| POST | `/v1/agent-sessions/{id}/delegate` | `agent:run` | Hand a task from a conversation to a crew role thread (plan, build, review, test, research); the child's typed report reaches the parent. |
| GET | `/v1/connections` | `agent:run` | List your connected CLI accounts: the id to pass as `native_connection_id`, and when each last hit its plan limit (`limit_hit_at`, `limit_until`). |
| GET | `/v1/delegations/{id}` | `agent:run` | Read a crew delegation: the child's state, what it runs on, its report, any open question. |
| GET | `/v1/webhooks` | `webhooks:manage` | List endpoints and discover all supported event types. |
| POST | `/v1/webhooks` | `webhooks:manage` | Create an endpoint and receive its signing secret once. |
| DELETE | `/v1/webhooks/{id}` | `webhooks:manage` | Delete an endpoint. |
| GET | `/v1/pages` | `pages:read` | List the pages the key's user can open, newest first: `query` searches titles, `limit`, `cursor`. |
| GET | `/v1/pages/{id}` | `pages:read` | Read a page: title, version, publisher, a Markdown `text`, the `html` in parts (`html_offset`), and with `screenshot=true` PNG screenshots at 1280px. `version` reads an older one. |
| POST | `/v1/pages` | `pages:write` | Publish a page into a work item, chat or bot you can open: `workspace_id`, `title`, `html`, optional `visibility` (`workspace` or `team`). |
| PUT | `/v1/pages/{id}` | `pages:write` | Update a page in place (new version, same URL): `title`, `html`. |
| PATCH | `/v1/pages/{id}` | `pages:write` | Change `visibility` (the item's owner). |
| DELETE | `/v1/pages/{id}` | `pages:write` | Delete a page and every version (the item's owner). |
| POST | `/v1/pages/{id}/guest-link` | `pages:write` | Guest link: `action` `enable` (or read the current one), `rotate` or `disable`. Needs the Pro plan. |

Two routes need no API key: `GET /v1/identity/verify` checks the signed identity token every agent turn gets, and `/v1/identity/jwks.json` publishes the keys to check it offline. See [execution identity](https://aq.dev/docs/execution-identity/).

Request and response schemas, field types, enums, limits, and error responses are defined in the [OpenAPI 3.1 document](https://aq.dev/v1/openapi.json).

## When a subscription reaches its limit

A native session runs on a person's own connected CLI account. When that account reaches its plan limit, AQ first moves the session to another connected account of the same harness with room. When there is none (and the person's "When a plan runs out" choice does not continue on Auto), the session rests:

- `status` is `waiting_for_user` and `error_code` is `subscription_limit`.
- `limit` on the session says which account (`harness`, `connection_id`), when it has room again (`resets_at`, with `resets_at_source` `provider` when the harness reported it, `estimate` when AQ holds the account for a default period), and which messages the refused turn used (`consumed_message_id`, `consumed_message_ids`).
- The same `error_code` and `limit` ride the `status_changed` progress event and the `workspace.agent_idle` webhook.
- The refused messages are consumed, not replayed. Send them again after `resets_at`, or now with another `native_connection_id` or `source`.

`GET /v1/connections` (and the `list_connections` MCP tool) shows each account's `limit_hit_at` and `limit_until`; a past `limit_until` means the account is no longer held.

## Pagination

Workspace lists use an opaque cursor. Pass the returned `next_cursor` unchanged to the next request:

```
curl -fsS \
  "https://aq.dev/v1/workspaces?limit=50&cursor=opaque-cursor" \
  -H "Authorization: Bearer $AQ_API_KEY"
```

Workspace events are returned newest first and use a timestamp cursor. Pass `next_before` back as the `before` query parameter. Agent progress events are different: they are ordered and carry a monotonic string `seq`. Pass the newest sequence you have seen as `after_seq` to fetch only later events.

## Retry-safe REST writes with idempotency keys

Every REST `POST` and `DELETE` requires an `Idempotency-Key` header of at most 255 characters. Generate one key for each logical action and keep it stable across retries. A UUID is a good default.

```
curl -fsS -X POST https://aq.dev/v1/workspaces \
  -H "Authorization: Bearer $AQ_API_KEY" \
  -H "Idempotency-Key: 9683499e-966d-4d4b-bc6c-05c9216da279" \
  -H "Content-Type: application/json" \
  -d '{"title":"Fix the auth bug","repo_id":"your-repo-id"}'
```

- A retry with the same method, path, body, key, and API key replays the stored response and adds `Idempotency-Replayed: true`.
- Reusing the key with a different body returns `422 idempotency_key_reused`.
- Retrying while the first request is still running returns `409 retry_in_progress`. Wait briefly and retry with the same key.
- Do not generate a fresh idempotency key merely because the client timed out. That would describe a new logical action and could create a duplicate.

## End-to-end REST example: create, inspect, and close a workspace

First choose a repository id:

```
curl -fsS https://aq.dev/v1/repos \
  -H "Authorization: Bearer $AQ_API_KEY" | jq '.repos[] | {id, name, default_branch}'
```

Create the workspace and save its id:

```
CREATE_RESPONSE=$(curl -fsS -X POST https://aq.dev/v1/workspaces \
  -H "Authorization: Bearer $AQ_API_KEY" \
  -H "Idempotency-Key: docs-smoke-create-1" \
  -H "Content-Type: application/json" \
  -d '{"title":"API smoke test","repo_id":"your-repo-id"}')

WORKSPACE_ID=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.workspace.id')
printf '%s' "$CREATE_RESPONSE" | jq
```

Inspect its activity, pull requests, and previews:

```
curl -fsS "https://aq.dev/v1/workspaces/$WORKSPACE_ID/events" \
  -H "Authorization: Bearer $AQ_API_KEY" | jq

curl -fsS "https://aq.dev/v1/workspaces/$WORKSPACE_ID/prs" \
  -H "Authorization: Bearer $AQ_API_KEY" | jq

curl -fsS "https://aq.dev/v1/workspaces/$WORKSPACE_ID/previews" \
  -H "Authorization: Bearer $AQ_API_KEY" | jq
```

Close the test workspace when you are done:

```
curl -fsS -X POST \
  "https://aq.dev/v1/workspaces/$WORKSPACE_ID/close" \
  -H "Authorization: Bearer $AQ_API_KEY" \
  -H "Idempotency-Key: docs-smoke-close-1" | jq
```

## Run and steer AQ's agent over REST

AQ's built-in agent is a durable conversation attached to an active workspace. Starting a run queues work, and a worker normally begins it within seconds. The agent edits the workspace's worktree and reports progress through ordered events and transcript messages. It does not automatically push or open a pull request.

The key needs `agent:run`, the workspace must be active, and AQ's agent must be enabled for the team. It is included (beta) for every organization by default; a team can have it turned off. A disabled team receives `403 agent_disabled`.

The workspace also needs a prepared worktree. Starting a conversation prepares it if nobody has opened it yet: AQ checks out the branch, and when the repository has a setup command, installs its dependencies and runs that command before the agent's first turn (see [Preparation](#preparation)). If the checkout itself fails, the session rests in `waiting_for_user` with `error_code` set to `workspace_not_ready` and a system message explaining why. A temporarily unreachable runner rests with `error_code` set to `runner_unavailable`: nothing is lost, and the conversation resumes on the next message.

### Start a conversation

```
RUN_RESPONSE=$(curl -fsS -X POST \
  "https://aq.dev/v1/workspaces/$WORKSPACE_ID/agent" \
  -H "Authorization: Bearer $AQ_API_KEY" \
  -H "Idempotency-Key: agent-run-1" \
  -H "Content-Type: application/json" \
  -d '{"message":"Inspect the failing tests, explain the cause, and fix it."}')

AGENT_SESSION_ID=$(printf '%s' "$RUN_RESPONSE" | jq -r '.agent_session.id')
printf '%s' "$RUN_RESPONSE" | jq
```

Start, get, and interrupt respond with the session object. The fields your poller needs are `status`, `error_code`, and `credits_spent_micros`; `title` is the tab label the conversation gets in the workspace:

```
{
  "agent_session": {
    "id": "as_...",
    "workspace_id": "workspace-id",
    "title": "AQ",
    "status": "queued",
    "budget_state": "active",
    "credits_spent_micros": "0",
    "error_code": null,
    "created_at": "2026-08-02T18:20:00.000Z"
  }
}
```

### Poll progress incrementally

```
curl -fsS \
  "https://aq.dev/v1/agent-sessions/$AGENT_SESSION_ID/events?after_seq=0&limit=200" \
  -H "Authorization: Bearer $AQ_API_KEY" | jq
```

Persist the largest returned `seq` and use it as the next `after_seq`. The stream mirrors what the workspace tab shows: `message` entries, one `tool` event per tool call the agent makes while working, `checkpoint` markers for the worktree snapshot taken before each turn, and `status_changed` transitions. Read the conversation itself from the messages endpoint:

```
curl -fsS \
  "https://aq.dev/v1/agent-sessions/$AGENT_SESSION_ID/messages" \
  -H "Authorization: Bearer $AQ_API_KEY" | jq
```

Without a cursor you get the newest page (up to `limit`, 500 at most) in chronological order. Every message carries a string `seq`: pass the oldest one you hold as `before_seq` to read further back, or the newest as `after_seq` to read forward, until `has_more` is false. Each message's `content` is complete. A single message is stored up to 1,000,000 characters; a longer one ends with a `[Message truncated: ...]` note, so a cut is never silent. Tool results in the events stream keep the first 8,000 characters of a command's output: such a `tool_result` has `truncated: true` and `total_bytes` with the full size, and the rest of that output is not kept.

| Status | Meaning | What the client should do |
| --- | --- | --- |
| `queued` | Waiting for a worker | Continue polling. |
| `running` | The current turn is active | Read events and messages; send a message only when you intend to steer. |
| `waiting_for_user` | The agent is resting or needs input | Read the transcript and send a reply to resume. If `error_code` is set, fix that first: `workspace_not_ready` means open the workspace once. |
| `paused` | The run is paused by a control or budget gate | Inspect `budget_state` and `error_code`. |
| `completed`, `failed`, `cancelled` | Terminal states | Stop polling. Start a new conversation for more work. |

### Reply, stop a turn, or archive the conversation

```
# Reply or steer. A reply to waiting_for_user resumes the run.
curl -fsS -X POST \
  "https://aq.dev/v1/agent-sessions/$AGENT_SESSION_ID/messages" \
  -H "Authorization: Bearer $AQ_API_KEY" \
  -H "Idempotency-Key: agent-reply-1" \
  -H "Content-Type: application/json" \
  -d '{"content":"Use the smaller fix and rerun the focused tests."}'

# Stop only the current turn. The conversation remains open.
curl -fsS -X POST \
  "https://aq.dev/v1/agent-sessions/$AGENT_SESSION_ID/interrupt" \
  -H "Authorization: Bearer $AQ_API_KEY" \
  -H "Idempotency-Key: agent-stop-1"

# Close the conversation tab. Its transcript remains readable by id.
curl -fsS -X POST \
  "https://aq.dev/v1/agent-sessions/$AGENT_SESSION_ID/archive" \
  -H "Authorization: Bearer $AQ_API_KEY" \
  -H "Idempotency-Key: agent-archive-1"
```

Interrupt answers once the machine says whether every process the turn started has ended. Read `agent_session.last_stop`: `state` is `confirmed` or `unconfirmed`, `scope` says how the turn's processes were found, `remaining` counts what was still running, and `cleanup_pending` is true while AQ is still trying to end the run. If `last_stop.state` is `unconfirmed` (for example the machine could not be reached), call interrupt again with a new Idempotency-Key: AQ sends the stop to that same run and returns what the machine says now. AQ also retries on its own when the machine reconnects.

## Crews, run limits and questions

A run can be a crew: pass `crew_id` (from `GET /v1/crews`) when you start the agent and the conversation becomes the crew's Lead. It plans, delegates to the crew's roles and integrates their work. `role_picks` says what each role runs on for this work item, for example the builder on your Claude subscription, the reviewer on Codex so a different vendor checks the work, and `test` (or your organization's own role) as the browser checker. A role you leave out uses the crew's or the organization's pick, else Auto, and Auto review already prefers a different vendor than the builder.

```
curl -sS -X POST https://aq.dev/v1/workspaces/$WS/agent \
  -H "Authorization: Bearer $AQ_API_KEY" \
  -H "Idempotency-Key: crew-run-1" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Add CSV export to the reports page",
    "source": "aq",
    "crew_id": "builtin:ship",
    "role_picks": {
      "build":  { "source": "native", "native_harness": "claude" },
      "review": { "source": "native", "native_harness": "codex" },
      "test":   "auto"
    },
    "limits": { "max_spend_usd": 20, "max_wall_time_minutes": 90 }
  }'
```

`limits` bound one run: the conversation and every crew member it delegates to. `max_spend_usd` counts AQ credits only, so work on a connected subscription counts as $0. `max_wall_time_minutes` counts from the start. AQ checks at every turn boundary and every 15 seconds; a run that reaches a limit is stopped, rests with `error_code` `run_limit_spend` or `run_limit_wall_time`, and records a `run_limit_reached` event with the reason. A run can pass its spend limit by the model requests already in flight when it is checked. Raise or clear the limits with `PUT /v1/agent-sessions/{id}/limits` (the clock and the spend count restart), then send a message or resume. These limit one run; they are not spending limits on a person, a team or a bot.

When a run waits on someone, `GET /v1/agent-sessions/{id}/questions` lists what it waits on, including its crew members' questions and a plan to approve (`kind` `plan`). Answer with `POST /v1/agent-sessions/{id}/questions/answer` and an option label, or decide a plan with `POST /v1/agent-sessions/{id}/plan`. Standing permissions ("Always allow") and secret values are only given in AQ. An existing conversation becomes a crew's Lead with `POST /v1/agent-sessions/{id}/crew`.

**A finished turn rests, it does not complete.** When the agent has done what a message asked, the conversation's status becomes `waiting_for_user`, with no `error_code`: it is ready for the next message. `completed` means the conversation itself ended (it was archived or its work item closed), so never wait for `completed` to know a turn is done. Watch for `waiting_for_user` (the `agent.status_changed` stream event or webhook, or `workspace.agent_idle`), then read `error_code`: none means the turn finished, anything else (`run_limit_spend`, `subscription_limit`, `setup_blocked`, ...) says why it stopped.

**What counts toward a limit.** Run limits and every AQ budget count AQ credits only. Work on a connected subscription (your Claude, Codex or other plan) costs $0 in AQ credits, so it never moves a spend limit. `"source": "aq"` is AQ Auto, which picks a model per turn and may run a turn on one of the key's person's connected subscriptions when it has room, so a run on `source: "aq"` can spend nothing. The session's `auto_credits_only` (or the organization's Auto setting) keeps Auto on AQ credits; `run_credits_spent_micros` on the session is what the whole run actually spent.

**Who continues after a crew member reports.** By default a crew member's report wakes the conversation that delegated to it, which starts a new turn (on AQ credits or a subscription). A caller that owns the loop can turn that off: `resume_parent: false` on `POST /v1/agent-sessions/{id}/delegate` (one delegation), or on `POST /v1/workspaces/{id}/agent` and `POST /v1/agent-sessions/{id}/crew` (every delegation of that conversation). The report is still the `delegation_result` event, the `agent.delegation_finished` stream event and webhook, and a line in the transcript; nothing runs until you send the next message. `GET /v1/delegations/{id}` returns the report text (`result.report`), a reviewer's issues as a list (`result.findings`: `file`, `line`, `severity`, `message`; `result.findings_count`), and what the member ran on (`child_model`, `child_vendor`, `pick`), so you can show "reviewed by OpenAI".

For an onboarding screen, `GET /v1/account` answers in one read with the plan, machines and their status, connected agents, repositories and connected tools.

## Follow a run live

`GET /v1/agent-sessions/{id}/stream` answers with `text/event-stream` for the whole run: the conversation and every crew member it delegates to. The first frame is a `snapshot`, and a new one comes whenever the run's state changes: `status`, `error_code`, `run_credits_spent_micros` (AQ credits for the whole run; subscriptions count as $0), `members`, `questions_waiting`, `preview` (its URL), `prs` and `limits`. Between snapshots come the run's events: `agent.status_changed`, `agent.message` (the agent's text in chunks; join the chunks that share a `block_id`), `agent.tool_started` and `agent.tool_finished` (the tool name and a one-line summary), `agent.question_asked` and `agent.question_answered`, `agent.delegation_started` and `agent.delegation_finished`, `agent.run_limit_reached` and `agent.pr_opened`.

```
curl -N https://aq.dev/v1/agent-sessions/$AGENT_SESSION_ID/stream \
  -H "Authorization: Bearer $AQ_API_KEY"

event: snapshot
data: {"agent_session_id":"as_...","status":"running","run_credits_spent_micros":"412000",...}

id: 1838201
event: agent.tool_started
data: {"event_id":"are_...","seq":"1838201","session_id":"as_...","type":"agent.tool_started","data":{"name":"Bash","summary":"npm test"},...}
```

Every event frame has an `id`, its cursor. After a disconnect, reconnect with the `Last-Event-ID` header (browsers' EventSource does this for you) or `?after_seq=`. A stream sends `: ping` every 15 seconds and ends after 15 minutes with a `reconnect` event that carries the cursor. Delivery is at least once, so dedupe by `event_id`. A key can hold 10 streams open at once. Where a long-lived connection is not an option, poll `GET /v1/agent-sessions/{id}/updates?after_seq=` (MCP: `get_run_updates`) for the same snapshot and events. The run's status changes, questions, delegations and limit stops are also [webhooks](#webhooks).

## Merge a pull request

`POST /v1/workspaces/{id}/prs/{number}/merge` (MCP `merge_pr`) merges a work item's pull request on the key's person's behalf, with the same rules as the Merge button in AQ: the pull request is open and mergeable, its review is not stale, and its checks are green. It runs as that person on the work item's machine, with their own GitHub login and never a teammate's: a person who has not connected GitHub in AQ gets `403 github_not_connected`. Only the work item's owner or a team admin can merge.

- **Scope:** it needs `prs:merge`. No key gets it by default: tick it when you create the key, or on the consent screen when an MCP client connects. A key without it gets `403 missing_scope`.
- **Method:** `squash` (the default), `merge` or `rebase`.
- **Exact commit:** `match_head_sha` merges only that commit. If the branch moved, nothing merges and the answer is `409 head_mismatch`.
- **Checks:** pending or failing checks answer `409 ci_not_green`. `override_checks: true` merges anyway; every other rule still applies.
- **Other refusals:** `409 merge_blocked` (closed, conflicts, a review older than the head) and `409 merge_refused` (GitHub said no, with its reason).
- **Answer:** `{merged, sha, head_sha, pr_url, pr_number, method, checks_overridden, message}`. `merged: false` with no error means GitHub queued the merge for when checks pass.
- **Record:** every attempt and every refusal is in the audit log with the person, the key's name, the client and the state before and after. A merge also writes a line in the work item's history, for example "Merged pull request #12 via OpenFactory by Khaled (squash)."

```
curl -X POST "https://aq.dev/v1/workspaces/$WORKSPACE_ID/prs/12/merge" \
  -H "Authorization: Bearer $AQ_API_KEY" \
  -H "Idempotency-Key: merge-12-$HEAD_SHA" \
  -H "client: openfactory" \
  -H "Content-Type: application/json" \
  -d '{"method": "squash", "match_head_sha": "'"$HEAD_SHA"'"}'
```

### Name your client

Send a `client` header (for example `client: openfactory`) or a User-Agent that starts with your product (`OpenFactory/0.1`). AQ records it on each request's usage and on the key, and it names your client in the work item's history. A key can also be created for a client: `POST /api/api-keys` takes an optional `client`, and an MCP client's OAuth name is used for the keys it receives. Sign-up links can carry `?ref=yourproduct` (for example `https://aq.dev/signin?ref=openfactory`), which AQ keeps on the people who sign up through them.

## Preparation: know when a workspace is ready

A new workspace is prepared in three steps: the checkout (`worktree`), AQ's dependency install (`dependencies`) and the repository's setup command (`setup`). The install and the setup command run only when the repository has a setup command; without one, AQ installs dependencies when a preview starts, and the agent installs what it needs itself.

`GET /v1/workspaces/{id}` and the MCP tool `get_workspace` return a `prep` object:

```
"prep": {
  "phase": "ready",              // pending | installing | setup | ready | failed
  "started_at": "2026-11-10T18:02:11.204Z",
  "finished_at": "2026-11-10T18:03:40.918Z",
  "outcome": "ok",               // ok | ok_with_warnings | failed | null while running
  "dependencies": "installed",   // installed | failed | not_run
  "setup_command": "ran",        // ran | not_configured
  "steps": [{ "id": "worktree", "status": "ok", "duration_ms": 2140 }, ...],
  "failure": null                // { "step": "setup", "exit_code": 1, "summary": "Setup command failed (exit 1)" }
}
```

Poll it until `phase` is `ready` or `failed`, or subscribe to the `workspace.prepared` and `workspace.setup_hook_failed` webhooks. Failure payloads carry `step` (`dependencies` or `setup`), `exitCode`, `timedOut` and `durationMs`; never the command's output. The full log is in the workspace's Log tab.

When a conversation started over the API or MCP prepares the workspace itself (nobody opened it in AQ first), the agent's first turn waits for that preparation (up to 20 minutes) and is told whether it finished or failed, so it does not reinstall dependencies beside AQ. To have dependencies installed before the first turn, give the repository a setup command (`npm ci` is enough).

A failed dependency install is never reported as a clean preparation: with a setup command that passed after it, `outcome` is `failed` (or `ok_with_warnings` when the repository's setup failure mode is "Continue"), `dependencies` is `failed` and `failure` names the `dependencies` step and its exit code. The agent is told to install them itself under the lock below. A step that times out ends every process it started.

### Setup failure mode "Block"

When the repository's setup failure mode is saved as "Block" and the dependency install or the setup command fails or times out, no agent conversation starts on that workspace: a new conversation rests at `waiting_for_user` with `error_code` `setup_blocked` (also on the `workspace.agent_idle` webhook), its messages kept. It starts on its own once a re-run succeeds; `POST /v1/agent-sessions/{id}/resume` (MCP `resume_agent`) starts it anyway.

### Prepare before the first task

To hold the real task until dependencies and setup succeed, prepare the workspace right after creating it, with no agent: `POST /v1/workspaces/{id}/prepare` on a workspace with no worktree yet checks it out, installs dependencies and runs the setup command. Poll `prep` until `phase` is `ready`, then start the agent. A conversation started while preparation runs waits for it; with "Block", a failure holds it as above.

### Re-run preparation in place

After you change the setup command or fix the repository, re-run preparation on the same workspace. AQ forgets that setup ran (under its lock), installs dependencies and runs the current setup command, in a new log:

```
curl -X POST "https://aq.dev/v1/workspaces/$WORKSPACE_ID/prepare" \
  -H "Authorization: Bearer $AQ_API_KEY" \
  -H "Idempotency-Key: prepare-1"
```

It answers `202` at once; follow `prep` and the webhooks as above. The MCP tool is `prepare_workspace`; in the app, the Log tab's **Retry setup** does the same (shown after a failure or a warning). A follow-up message alone never re-runs preparation.

### Coordinate dependency installs

AQ's dependency install and the setup command hold one lock per worktree. On AQ cloud machines, anything else that installs dependencies in the worktree (an agent, a script you run through it) can wait on the same lock:

```
flock "$(git rev-parse --absolute-git-dir)/aq-preview-install.lock" npm ci
```

AQ's agent is told this in its context. Inside the setup command itself, use `flock "$AQ_INSTALL_LOCK" ...`: the setup command already holds the worktree lock, and `$AQ_INSTALL_LOCK` points at a separate file so it cannot deadlock.

## Connect an MCP client

For the agent-facing quickstart (one-step connect for Claude Code, Claude and ChatGPT connectors, Cursor, and a paste-to-your-agent setup block), see [Connect your AI agent to AQ over MCP](https://aq.dev/docs/mcp/). The reference below covers the same surface in API terms.

AQ's MCP endpoint uses stateless Streamable HTTP with OAuth. In a client that supports remote MCP servers (as of October 2026 that includes Cursor, Claude, ChatGPT connectors, and others), add the URL and nothing else:

```
{
  "mcpServers": {
    "aq": {
      "url": "https://aq.dev/mcp"
    }
  }
}
```

The first time the client connects, your browser opens an AQ sign-in and consent screen. Approve, and the client receives its own access token, no key copying. Each connected app shows up in **Settings → Connections → API keys** (named `MCP: <client>`), and revoking it there disconnects the app immediately.

### Headless or key-based clients

If your client cannot run a browser OAuth flow, mint a key in Settings → Connections → API keys and send it as a Bearer header: the same key used by REST:

```
{
  "mcpServers": {
    "aq": {
      "url": "https://aq.dev/mcp",
      "headers": {
        "Authorization": "Bearer aq_your_key"
      }
    }
  }
}
```

Prefer a client feature that reads the token from an environment variable or secret store when one is available.

| MCP tool | Required scope | Effect |
| --- | --- | --- |
| `whoami` | *any key* | Identify the key: user, team, and scopes. |
| `list_workspaces` | `workspaces:read` | List visible workspaces with bounded cursor pagination and server-side filters (`status`, `repo_id`, `repo_name`, `query`). |
| `count_workspaces` | `workspaces:read` | Count workspaces grouped by status, with the same filters. The instant answer to "how many", with no paging. |
| `get_workspace` | `workspaces:read` | Fetch one workspace. |
| `list_repos` | `workspaces:read` | List connected repositories. |
| `create_workspace` | `workspaces:write` | Create a workspace (optionally from a specific `base_branch`). |
| `update_workspace` | `workspaces:write` | Edit a workspace's title and/or description. |
| `share_workspace` | `workspaces:write` | Set visibility and the share roster (owner-only). Omit `shared_with_emails` to keep the current roster; pass `[]` to revoke everyone. Newly-added teammates are notified. |
| `add_workspace_repos` | `workspaces:write` | Add repositories to a workspace (each checked out on its branch name); `create_workspace` also takes `additional_repo_ids`. |
| `close_workspace` | `workspaces:write` | Close a workspace; requires `confirm=true`. |
| `reopen_workspace` | `workspaces:write` | Reopen a closed or archived workspace. |
| `prepare_workspace` | `workspaces:write` | Re-run a workspace's preparation in place (dependencies, then the current setup command). |
| `get_workspace_events` | `events:read` | Read workspace activity. |
| `list_workspace_prs` | `prs:read` | List tracked pull requests. |
| `merge_pr` | `prs:merge` | Merge a work item's pull request with the app's rules. |
| `list_connections` | `agent:run` | List the connected CLI accounts of the person the key acts as, with the id to pass as `native_connection_id` when a harness has more than one, and when each last hit its plan limit (`limit_hit_at`, `limit_until`). |
| `get_preview_url` | `previews:read` | Read preview status and URLs. |
| `list_agent_sessions` | `agent:run` | List a workspace's AQ agent conversations. |
| `start_agent` | `agent:run` | Start an AQ agent conversation. |
| `get_agent_run` | `agent:run` | Read status, the transcript tail, and recent events. |
| `send_agent_message` | `agent:run` | Steer or resume the agent. |
| `stop_agent` | `agent:run` | Stop the current turn while keeping the conversation open. |
| `resume_agent` | `agent:run` | Resume a resting conversation; one held by a Block setup failure starts anyway. |
| `archive_agent_session` | `agent:run` | Close a conversation tab; the transcript stays readable. |
| `delegate` | `agent:run` | Hand a task from a conversation to a crew role thread (plan, build, review, test, research) on the organization's role policy; the child's typed report reaches the parent. |
| `delegation_status` | `agent:run` | Read a crew delegation: the child's state, what it runs on, its report, any open question. |
| `find_items` | `workspaces:read` | Find work items, bots, Genie and earlier chats by title or name across the organization, with exact ids, kinds and status. |
| `read_item` | `agent:run` | Read an item's threads and recent conversation without waking it. Pass the result's `next_before` as `before` to page back. A message longer than one read (24,000 characters) has `truncated`, `total_chars` and `next_offset`; call again with `message_id` and `offset` for the rest. |
| `message_item` | `agent:run` | Send a follow-up to an existing item's thread, queued or (`deliver: "now"`) interrupting the current turn. |
| `stop_item` | `agent:run` | Stop an item's current turn, given the `run_id` from a fresh `read_item`. |
| `get_account` | *any key* | The account, plan, machines (with status), connected agents, repositories and connected tools in one read. |
| `list_connected_apps` | `agent:run` | Your connected app accounts with their names, providers, status and which is your default. |
| `rename_connected_app` | `agent:run` | Name one of your connected app accounts; agents read the name to pick the right account. |
| `list_crews` | `workspaces:read` | The organization's crews and roles. |
| `set_role_picks` | `workspaces:write` | Set what each crew role runs on for one work item (owner only). |
| `engage_crew` | `agent:run` | Make an existing conversation a crew's Lead, optionally with role picks. |
| `get_run_updates` | `agent:run` | A run's snapshot and its events after a cursor (the stream as a poll). |
| `get_run_limits` | `agent:run` | A run's limits and what it has used. |
| `set_run_limits` | `agent:run` | Set, replace or clear a run's spend and wall-time limits. |
| `list_run_questions` | `agent:run` | Open questions a run and its crew members wait on. |
| `answer_run_question` | `agent:run` | Answer one as the key's user (one-time decisions only). |
| `decide_plan` | `agent:run` | Approve, edit or decline (one thread) a crew Lead's plan. |
| `list_bots` | `bots:read` | List the bots the key's user can use, with status. |
| `bot_status` | `bots:read` | One bot's status, its routines and the recent runs you may see. |
| `create_bot` | `bots:manage` | Create a bot: name, role, instructions, character, color, model, visibility. |
| `update_bot` | `bots:manage` | Change a bot's name, role, instructions, character, color or model; undoable in AQ. |
| `pause_bot` | `bots:operate` | Pause a whole bot and all its routines. |
| `resume_bot` | `bots:operate` | Resume a paused bot. |
| `archive_bot` | `bots:manage` | Archive a bot (owner); pass `confirm: true`. Restorable for 30 days. |
| `restore_bot` | `bots:manage` | Restore an archived bot; it comes back paused. |
| `message_bot` | `bots:operate` | Message a bot in your own chat with it. |
| `read_bot_chat` | `bots:read` | Read your own chat with a bot: its replies and whether it is still working. |
| `list_routines` | `bots:read` | List a bot's routines with status and next run. |
| `create_routine` | `bots:manage` | Add a routine that runs as you, with any trigger the app offers. |
| `update_routine` | `bots:manage` | Change a routine's name, instruction, trigger or posting. |
| `run_routine` | `bots:operate` | Run a routine now (only the person it runs as). |
| `pause_routine` | `bots:operate` | Pause a routine by its id (the bot's owner, its managers or the person it runs as). |
| `resume_routine` | `bots:operate` | Resume a paused routine; returns its next run. |
| `delete_routine` | `bots:manage` | Delete a routine for good; pass `confirm: true`. |
| `list_bot_runs` | `bots:read` | Recent runs with status, trigger, timing, cost and a one-line result. |
| `get_bot_run` | `bots:read` | One run in full, including what it did for the person it ran as. |
| `bot_usage` | `bots:read` | Spend over a period, per routine. |
| `list_bot_work_items` | `bots:read` | Work items the bot started, with status and pull request. |
| `pending_bot_questions` | `bots:read` | What your bots are waiting on you for. |
| `answer_bot_question` | `bots:operate` | Answer a question or approve or decline an approval card by its `request_id`. |
| `get_bot_permissions` | `bots:read` | Which accounts a bot may use and your own connections. |
| `set_bot_permissions` | `bots:manage` | Bind, remove or share one of your accounts for a bot (owner). |
| `get_bot_sharing` | `bots:read` | Who a bot is shared with. |
| `share_bot` | `bots:manage` | Share with teammates or the whole team. |
| `unshare_bot` | `bots:manage` | Stop sharing with people or the whole team. |
| `list_bot_library` | `bots:read` | The pages, files, links and notes a bot saved. |
| `read_bot_library_item` | `bots:read` | Read one library item. |
| `list_webhooks` | `webhooks:manage` | List webhook endpoints and subscribable event types. |
| `create_webhook` | `webhooks:manage` | Create a webhook endpoint; the signing secret is returned exactly once. |
| `delete_webhook` | `webhooks:manage` | Delete a webhook endpoint; requires `confirm=true`. |
| `list_pages` | `pages:read` | The AQ Pages you can open, newest first, with a title search. |
| `read_page` | `pages:read` | Read a page by id or URL: text, HTML in parts, and screenshots as images. |
| `publish_page` | `pages:write` | Publish a page into a work item, chat or bot, or update one in place with `page_id`. |
| `set_page_visibility` | `pages:write` | The item's audience or the whole team. |
| `page_guest_link` | `pages:write` | Turn a page's guest link on, rotate it, or turn it off. |
| `delete_page` | `pages:write` | Delete a page; requires `confirm=true`. |

The MCP server only advertises tools allowed by the presented key's scopes, and annotates read-only versus destructive tools so clients can gate confirmations. Mutating tools accept an optional `idempotency_key` argument: a retry with the same key and identical arguments replays the first result instead of re-executing, so an agent that automatically retries can safely repeat `create_workspace` or `start_agent` without checking state first.

### AQ Pages

A page is a report, spec or dashboard published in AQ, at `https://aq.dev/pages/<id>`. A key sees exactly the pages its person can open in the app: pages from the work items, chats and bots they can see, plus pages shared with the whole team. A page they can't open answers 404. A page published through the API belongs to the item you name in `workspace_id`; that item's audience can open it, and `visibility: "team"` (the item's owner) opens it to the whole organization. Remote images load as written; nothing is read from a machine. Screenshots are rendered on the organization's machine; when it is asleep the read says so and returns the text and HTML anyway.

### Managing bots from another agent

An agent connected to `https://aq.dev/mcp` (Grok, ChatGPT, Claude or your own) can run a person's bots end to end with the bot tools above: create a bot, give it routines, run them, read what each run did, answer what the bot asks, share it and archive it. Changes apply at once (a routine change that lets someone else's routine do more waits for that person) and show in the bot's chat in AQ as "Changed by Grok" with the time, named after the connection (or the API key's name). Changes to a bot's name, role, instructions, character, color, model and sharing have a one-click Undo there for the bot's owner and managers, and account changes for its owner; Undo puts the earlier values back while nothing has changed since. Pausing, archiving and routine changes have their own opposite actions instead. Every change is also in the organization's audit log with the person, the app and the values before and after.

The usual loop: `list_bots` → `create_bot` → `create_routine` → `run_routine` or `message_bot` → `read_bot_chat` / `list_bot_runs` / `get_bot_run` → `pending_bot_questions` → `answer_bot_question`. Ids always come from an earlier answer; nothing is guessed from names.

### Test MCP without installing a client

List the tools visible to your key:

```
curl -fsS https://aq.dev/mcp \
  -H "Authorization: Bearer $AQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tools/list",
    "params":{}
  }' | jq
```

Call a read-only tool:

```
curl -fsS https://aq.dev/mcp \
  -H "Authorization: Bearer $AQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"list_workspaces",
      "arguments":{"limit":5}
    }
  }' | jq
```

The server is stateless and POST-only. A browser visit or other `GET /mcp` request intentionally returns `405`. Raw MCP POSTs must accept both `application/json` and `text/event-stream`, even though AQ currently returns JSON responses.

## Receive signed webhooks

Webhook endpoints let a service react without polling. Production endpoints must be public HTTPS URLs. AQ rejects credentials in webhook URLs, private and link-local address ranges, internal hostnames, redirects, and hostnames that resolve to private addresses at delivery time.

### Create an endpoint

```
curl -fsS -X POST https://aq.dev/v1/webhooks \
  -H "Authorization: Bearer $AQ_API_KEY" \
  -H "Idempotency-Key: webhook-create-1" \
  -H "Content-Type: application/json" \
  -d '{
    "url":"https://example.com/webhooks/aq",
    "description":"Production activity feed",
    "event_types":["workspace.pr_opened","workspace.agent_error"]
  }' | jq
```

The response returns the endpoint and an `aqwh_` signing secret. The secret is shown once and is never retrievable again. Store it before discarding the response:

```
{
  "webhook": {
    "id": "whe_...",
    "url": "https://example.com/webhooks/aq",
    "event_types": ["workspace.pr_opened", "workspace.agent_error"],
    "created_at": "2026-08-02T18:20:00.000Z"
  },
  "secret": "aqwh_..."
}
```

Pass an empty `event_types` array, or omit it, to subscribe to every supported event. `GET /v1/webhooks` returns your endpoints as `webhooks` plus the complete supported list as `event_types`, so your integration can discover new event types without a docs check.

### Delivery format

```
POST /webhooks/aq
content-type: application/json
user-agent: AQ-Webhooks/1.0
aq-webhook-id: whd_...
aq-event-type: workspace.pr_opened
aq-signature: t=1785690000,v1=hex-hmac-sha256

{
  "id": "whd_...",
  "type": "workspace.pr_opened",
  "created_at": "2026-08-02T18:20:00.000Z",
  "data": {
    "id": "event-id",
    "workspace_id": "workspace-id",
    "type": "pr_opened",
    "payload": {
      "prNumber": 42,
      "prUrl": "https://github.com/org/repo/pull/42"
    },
    "created_at": "2026-08-02T18:20:00.000Z",
    "read_at": null
  }
}
```

Webhook `data` uses the same scrubbed public DTOs as REST. Treat event delivery as at least once: deduplicate using the stable `id` or `aq-webhook-id`.

### Verify the signature before parsing or processing

```
import crypto from "node:crypto";

export function verifyAqWebhook(rawBody, signature, secret) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(signature ?? "");
  if (!match) return false;

  const timestamp = Number(match[1]);
  const received = Buffer.from(match[2], "hex");
  const expected = Buffer.from(
    crypto.createHmac("sha256", secret)
      .update(String(timestamp) + "." + rawBody)
      .digest("hex"),
    "hex",
  );

  const fresh = Math.abs(Date.now() / 1000 - timestamp) <= 300;
  return fresh && received.length === expected.length
    && crypto.timingSafeEqual(received, expected);
}
```

Use the exact raw request bytes in the HMAC input, not parsed and re-serialized JSON. Reject stale timestamps to prevent replay, compare digests in constant time, and return a `2xx` only after your system has durably accepted the event.

### Event types

- **Lifecycle:** `workspace.created`, `workspace.closed`, `workspace.reopened`.
- **Agent:** `workspace.agent_error`, `workspace.agent_stopped`, `workspace.agent_stale`, `workspace.agent_idle`.
- **Pull requests:** `workspace.pr_opened`, `workspace.pr_merged`, `workspace.pr_closed`.
- **Linear and comments:** `workspace.linear_state_changed`, `workspace.comment_added`.
- **Runtime health:** `workspace.terminal_exited_unexpectedly`, `workspace.setup_hook_failed`, `workspace.prepare_failed`, `workspace.prepared`, `workspace.runner_lost`, `workspace.stranded`.
- **Live runs:** `agent.status_changed`, `agent.question_asked`, `agent.question_answered`, `agent.delegation_started`, `agent.delegation_finished`, `agent.run_limit_reached`. The same fields as the [live stream](#run-stream), plus `agent_session_id`, `workspace_id`, and for a crew member `parent_session_id` and `role`. Pull requests arrive as `workspace.pr_opened`.
- **Bots:** `bot.run.completed`, `bot.run.needs_person`, `bot.routine.paused`, `bot.deleted`. Ids and states only; never a report or a chat.

### Retries and endpoint health

AQ considers any `2xx` response successful and times out a delivery after 10 seconds. Failed deliveries receive up to six total attempts, with delays of 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours. A delivery is dead-lettered after its final failed attempt. An endpoint is automatically disabled after 20 consecutive failed deliveries; create a new endpoint after fixing the receiver.

## Errors, limits, and troubleshooting

REST errors use a stable JSON envelope with a machine-readable snake_case code:

```
{"error":"insufficient_scope","scope":"events:read"}
```

| Status or error | Meaning | What to do |
| --- | --- | --- |
| `401 unauthorized` | The Bearer header is missing, malformed, revoked, or no longer backed by active membership. | Call `/v1/me`, check the header, then create a new key if needed. |
| `403 insufficient_scope` | The key is valid but cannot perform this operation. | Create a least-privilege replacement key with the returned scope. |
| `403 agent_disabled` | The team has AQ's agent turned off. | Ask AQ to enable the built-in agent for the team. |
| `400 idempotency_key_required` | A `POST` or `DELETE` arrived without an `Idempotency-Key` header. | Send the header on every REST write. See the idempotency section above. |
| `404 not_found` | The resource does not exist or is not visible to the acting user. | Check the id and the user's workspace access. AQ intentionally does not distinguish the two cases. |
| `409 retry_in_progress` | The first request using this idempotency key has not finished. | Wait briefly and retry the identical request with the same key. |
| `409 session_archived` | The conversation tab was closed with the archive endpoint. | The transcript stays readable by id. Start a new conversation for more work. |
| `409 run_finished` | The conversation is already in a terminal state. | Read its final transcript and start a new conversation for more work. |
| `422 idempotency_key_reused` | The same key was used with a different request body. | Use the original body, or use a new key for a genuinely new action. |
| `429 rate_limited` | The key exceeded the default 240 requests per minute, or an agent concurrency gate was reached. | Honor `Retry-After` and add backoff with jitter. |
| MCP `405` | The client sent GET or DELETE to the stateless endpoint. | Use a Streamable HTTP MCP client or POST JSON-RPC messages. |
| MCP `406` | The raw client did not accept both required media types. | Send `Accept: application/json, text/event-stream`. |

The default API and MCP limit is 240 requests per minute per key. Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. A `429` also includes `Retry-After`.

## A safe production smoke-test checklist

1. Create a temporary key with only `workspaces:read`.
2. Call `GET /v1/me` and verify the user, team, and scopes.
3. Call `GET /v1/workspaces?limit=1`.
4. POST an MCP `tools/list` request and confirm only read tools are advertised.
5. Call the MCP `list_workspaces` tool.
6. Revoke the temporary key and confirm `GET /v1/me` returns `401`.

Only after those read-only checks pass should you create a write-scoped key and run the create-and-close workspace example. Agent tests change files and may consume credits, so run them in a disposable workspace and only after confirming the team has AQ's agent enabled.

## Complete reference

Import [https://aq.dev/v1/openapi.json](https://aq.dev/v1/openapi.json) into an OpenAPI client generator, API client, or contract test suite for the complete field-level reference. For MCP, `tools/list` is the live source of truth because it returns exactly the tools allowed by the presented key.

## Frequently asked questions

### What is the AQ API?

The AQ API is the programmatic interface to AQ workspaces: a versioned REST API at `https://aq.dev/v1`, a hosted MCP server at `https://aq.dev/mcp`, and signed outbound webhooks. All three operate on the same workspaces with the same permission model as the AQ dashboard, authenticate with scoped `aq_` API keys, and are fully described by the OpenAPI 3.1 document at `/v1/openapi.json`.

### What can you do with the AQ API?

List, create, and close workspaces; read workspace event logs, tracked pull requests, and preview status and URLs; start, poll, steer, stop, and archive AQ agent conversations; and register webhook endpoints so your service reacts to workspace, agent, pull request, Linear, comment, and runner events without polling. Typical integrations are dashboards, issue intake automation, activity feeds, agent orchestration, and event-driven workflows.

### Does AQ have an API?

Yes. AQ exposes a versioned REST API at `https://aq.dev/v1`, signed webhooks for workspace events, and an MCP server at `https://aq.dev/mcp`. The machine-readable OpenAPI 3.1 reference lives at [/v1/openapi.json](https://aq.dev/v1/openapi.json).

### How do I get an AQ API key?

Create one in Settings under API keys. Keys start with `aq_`, are shown once at creation, and act as you inside your team: a key sees exactly the workspaces you can see, with the scopes you chose at creation.

### Does AQ have an MCP server?

Yes, at `https://aq.dev/mcp` (Streamable HTTP). Any compatible MCP client can list workspaces, create new ones, read event logs, fetch preview URLs, find, read, and message existing work items and bots, and use the AQ agent tools allowed by its scopes. Clients that support OAuth connect with just the URL (your browser opens an AQ consent screen once), and headless clients can authenticate with the same `aq_` API key as REST.

### What are the AQ API rate limits?

240 requests per minute per key by default. When a key exceeds the limit, the API returns 429 with a `Retry-After` header. Responses also report the limit, remaining requests, and reset time in rate-limit headers.

### Does the AQ REST API use the same permissions as the dashboard?

Yes. An API key acts as the user who created it and can only see workspaces that user can access. AQ also checks the key's explicit scopes. Removing the user from the team, suspending the account, or revoking the key stops access.

### Can an MCP client start and steer an AQ coding agent?

Yes. A key with the agent:run scope can list_agent_sessions, start_agent, get_agent_run, send_agent_message, stop_agent, and archive_agent_session. AQ's agent must also be enabled for the team, and the target workspace must be active.

### Are AQ webhooks delivered exactly once?

No. Treat delivery as at least once. AQ retries failures, so receivers should verify the signature and deduplicate using the stable delivery id in the payload or aq-webhook-id header before applying side effects.

### How should I retry an AQ API mutation after a timeout?

Send the identical REST request with the same Idempotency-Key. AQ replays the original response instead of executing the mutation twice. Do not generate a new key for a timeout retry. MCP mutating tools offer the same guarantee through their optional idempotency_key argument, which shares the REST slot store.

---

About AQ: AQ is where teams put AI agents to work on everything they do: code that lands as a reviewed pull request, bots that run the jobs that repeat, and an assistant that starts each day, all on the agents and subscriptions they already have, like Claude Code and Codex, on private cloud machines of their own or on their own Mac. Start at [aq.dev](https://aq.dev/).
