The AQ API
Updated October 27, 2026 · first published August 1, 2026 · by the AQ team
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 /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, 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 | /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
- Choose scopes and understand the permission model
- Find the complete REST endpoint map
- Implement workspace, event, and agent-event pagination
- Retry REST writes safely with idempotency keys
- Create, inspect, and close a test workspace
- Start, poll, steer, stop, and archive an AQ agent run
- Follow a run live over server-sent events
- Merge a pull request, and name your client
- Run a crew with role picks and limits, and answer its questions
- Know when a workspace is prepared, and coordinate dependency installs
- Connect and test an MCP client
- Register, verify, deduplicate, and troubleshoot webhooks
- Handle errors and rate limits
- Run the safe production smoke-test checklist
Quickstart: authenticate and make your first request
1. Create an API key
Open AQ 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": "[email protected]",
"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. |
| 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. |
| 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 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}/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. |
| 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.
Request and response schemas, field types, enums, limits, and error responses are defined in the OpenAPI 3.1 document.
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:
statusiswaiting_for_useranderror_codeissubscription_limit.limiton the session says which account (harness,connection_id), when it has room again (resets_at, withresets_at_sourceproviderwhen the harness reported it,estimatewhen AQ holds the account for a default period), and which messages the refused turn used (consumed_message_id,consumed_message_ids).- The same
error_codeandlimitride thestatus_changedprogress event and theworkspace.agent_idlewebhook. - The refused messages are consumed, not replayed. Send them again after
resets_at, or now with anothernative_connection_idorsource.
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). 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.
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 gets403 missing_scope. - Method:
squash(the default),mergeorrebase. - Exact commit:
match_head_shamerges only that commit. If the branch moved, nothing merges and the answer is409 head_mismatch. - Checks: pending or failing checks answer
409 ci_not_green.override_checks: truemerges anyway; every other rule still applies. - Other refusals:
409 merge_blocked(closed, conflicts, a review older than the head) and409 merge_refused(GitHub said no, with its reason). - Answer:
{merged, sha, head_sha, pr_url, pr_number, method, checks_overridden, message}.merged: falsewith 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. 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. |
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, plusagent_session_id,workspace_id, and for a crew memberparent_session_idandrole. Pull requests arrive asworkspace.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
- Create a temporary key with only
workspaces:read. - Call
GET /v1/meand verify the user, team, and scopes. - Call
GET /v1/workspaces?limit=1. - POST an MCP
tools/listrequest and confirm only read tools are advertised. - Call the MCP
list_workspacestool. - Revoke the temporary key and confirm
GET /v1/mereturns401.
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 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.
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.