{"openapi":"3.1.0","info":{"title":"AQ API","version":"1.0.0","description":"REST API for AQ workspaces, repos, events, pull requests, previews, agent conversations, and webhooks. Authenticate with an API key created in Settings, sent as a Bearer token. All mutations require an Idempotency-Key header."},"externalDocs":{"description":"Integration guide, quickstarts, MCP tools, and webhook verification","url":"https://aq.dev/docs/api/"},"servers":[{"url":"https://aq.dev"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key from Settings (starts with aq_). Scopes are set at key creation."}},"schemas":{"Workspace":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["active","closed","archived","deleted"]},"source_type":{"type":"string"},"source_url":{"type":["string","null"]},"repo_id":{"type":["string","null"]},"branch_name":{"type":["string","null"]},"base_branch":{"type":["string","null"]},"pr_url":{"type":["string","null"]},"is_private":{"type":"boolean"},"linear_identifier":{"type":["string","null"]},"assignee_email":{"type":["string","null"]},"created_by":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"last_event_at":{"type":["string","null"]},"shared_with_emails":{"type":"array","items":{"type":"string"},"description":"Present on single-workspace reads. The current share roster; omitted from list payloads."}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]},"Repo":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"git_url":{"type":"string"},"default_branch":{"type":"string"},"linear_team_name":{"type":["string","null"]}}},"WorkspaceEvent":{"type":"object","properties":{"id":{"type":"string"},"workspace_id":{"type":"string"},"type":{"type":"string"},"payload":{"type":"object"},"created_at":{"type":"string"},"read_at":{"type":["string","null"]}}},"PullRequest":{"type":"object","properties":{"id":{"type":"string"},"workspace_id":{"type":"string"},"pr_url":{"type":"string"},"pr_number":{"type":["integer","null"]},"repo_owner":{"type":["string","null"]},"repo_name":{"type":["string","null"]},"state":{"type":"string","enum":["open","merged","closed"]},"opened_at":{"type":["string","null"]},"merged_at":{"type":["string","null"]},"closed_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"Preview":{"type":"object","properties":{"id":{"type":"string"},"workspace_id":{"type":"string"},"source":{"type":"string"},"status":{"type":"string","enum":["starting","running","stopped","failed"]},"visibility":{"type":"string","enum":["private","public"]},"url":{"type":["string","null"]},"expo_connect_url":{"type":["string","null"]}}},"AgentSession":{"type":"object","properties":{"id":{"type":"string"},"workspace_id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["queued","running","waiting_for_user","paused","completed","failed","cancelled"]},"budget_state":{"type":"string","enum":["active","waiting","paused","finalized"]},"credits_spent_micros":{"type":"string"},"credit_ceiling_micros":{"type":["string","null"]},"source":{"type":"string","enum":["aq","native"],"description":"Executor zone for the session"},"native_harness":{"type":["string","null"],"description":"Harness id when source=native"},"native_connection_id":{"type":["string","null"],"description":"The connected account (from your Connections page) the native session runs on"},"model_selection_id":{"type":["string","null"],"description":"AQ model alias when source=aq"},"model_label":{"type":"string","description":"Tenant-visible display name captured at start"},"effort":{"type":["string","null"],"description":"Reasoning effort where the chosen option supports it"},"error_code":{"type":["string","null"]},"created_by":{"type":["string","null"]},"created_by_email":{"type":["string","null"],"description":"Whose seat the session runs on (shared-workspace attribution)"},"created_by_name":{"type":["string","null"],"description":"Display name of the creator when the roster knows one"},"run_as_user_id":{"type":["string","null"],"description":"Whose identity the session's turns run under now: a message runs as the person who sends it, so a teammate's message moves this to them"},"run_as_email":{"type":["string","null"]},"run_as_name":{"type":["string","null"]},"viewer_can_drive":{"type":"boolean","description":"Whether the requesting person may send on the thread's own row (run as whoever it runs as); present on the session list only"},"archived_at":{"type":["string","null"],"description":"Set when the tab was closed; the transcript stays readable"},"started_at":{"type":["string","null"]},"ended_at":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"AgentRunEvent":{"type":"object","properties":{"id":{"type":"string"},"seq":{"type":"string","description":"Monotonic per-session ordering; use as after_seq cursor"},"type":{"type":"string"},"payload":{"type":"object"},"created_at":{"type":"string"}}},"AgentMessage":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["user","agent","system"]},"content":{"type":"string"},"created_at":{"type":"string"},"retracted_at":{"type":["string","null"],"description":"Set when a queued user message was retracted; treat it as not delivered"},"claimed_at":{"type":["string","null"],"description":"Set when a user message was admitted into an agent turn; null means it is still queued and retractable"},"created_by":{"type":["string","null"],"description":"Who sent a user message; null on agent and system rows"},"pick":{"type":["object","null"],"description":"Selection captured at submission; null on older messages that inherit the conversation selection.","properties":{"source":{"type":"string","enum":["aq","native"]},"modelSelectionId":{"type":["string","null"]},"nativeHarness":{"type":["string","null"]},"nativeModelId":{"type":["string","null"]},"modelLabel":{"type":"string"},"effort":{"type":["string","null"]},"runAsUserId":{"type":["string","null"],"description":"Whose identity the message runs under; absent on older rows (the creator)"}}}}},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","disabled"]},"disabled_reason":{"type":["string","null"]},"created_at":{"type":"string"}}}}},"paths":{"/v1/me":{"get":{"summary":"Introspect the API key","description":"Returns the acting user, team, and scopes for the presented key.","responses":{"200":{"description":"Key identity","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":["string","null"]}}},"tenant_id":{"type":"string"},"account_id":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"key_id":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/workspaces":{"get":{"summary":"List workspaces","description":"Workspaces visible to the key's user, most recently updated first. Filter server-side with status/repo_id/repo_name/query instead of paging the whole list; use /v1/workspaces/count for 'how many' questions. Requires workspaces:read.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from next_cursor"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma-separated statuses (active, closed, archived, deleted). Default: everything except deleted."},{"name":"repo_id","in":"query","schema":{"type":"string"},"description":"Only workspaces backed by this repo id"},{"name":"repo_name","in":"query","schema":{"type":"string"},"description":"Case-insensitive substring match on the repo name"},{"name":"query","in":"query","schema":{"type":"string"},"description":"Case-insensitive substring match on the workspace title"}],"responses":{"200":{"description":"A page of workspaces","content":{"application/json":{"schema":{"type":"object","properties":{"workspaces":{"type":"array","items":{"$ref":"#/components/schemas/Workspace"}},"next_cursor":{"type":["string","null"]}}}}}},"400":{"description":"Invalid cursor or status filter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}},"post":{"summary":"Create a workspace","description":"Requires workspaces:write and an Idempotency-Key header.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Unique key per logical request. Retries with the same key replay the first response instead of re-executing. Reusing a key with a different body returns 422."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":5000},"repo_id":{"type":"string"},"base_branch":{"type":"string","maxLength":200}},"required":["title"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"workspace":{"$ref":"#/components/schemas/Workspace"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"409":{"description":"First attempt with this Idempotency-Key still running","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"422":{"description":"Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/workspaces/count":{"get":{"summary":"Count workspaces","description":"Workspaces visible to the key's user, grouped by status, with the same filters as the list endpoint. The instant answer to 'how many' questions — never page the list just to count. Requires workspaces:read.","parameters":[{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma-separated statuses (active, closed, archived, deleted). Default: everything except deleted."},{"name":"repo_id","in":"query","schema":{"type":"string"},"description":"Only workspaces backed by this repo id"},{"name":"repo_name","in":"query","schema":{"type":"string"},"description":"Case-insensitive substring match on the repo name"},{"name":"query","in":"query","schema":{"type":"string"},"description":"Case-insensitive substring match on the workspace title"}],"responses":{"200":{"description":"Workspace counts","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"by_status":{"type":"object","additionalProperties":{"type":"integer"}}}}}}},"400":{"description":"Invalid status filter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/workspaces/{id}":{"get":{"summary":"Get a workspace","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The workspace","content":{"application/json":{"schema":{"type":"object","properties":{"workspace":{"$ref":"#/components/schemas/Workspace"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/workspaces/{id}/close":{"post":{"summary":"Close a workspace","description":"Stops the workspace's terminals and previews. Requires workspaces:write and an Idempotency-Key header.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Unique key per logical request. Retries with the same key replay the first response instead of re-executing. Reusing a key with a different body returns 422."}],"responses":{"200":{"description":"Closed","content":{"application/json":{"schema":{"type":"object","properties":{"workspace":{"$ref":"#/components/schemas/Workspace"}}}}}},"400":{"description":"This workspace cannot be closed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/workspaces/{id}/events":{"get":{"summary":"List workspace events","description":"Append-only event log (PRs opened/merged, agent errors, Linear activity). Requires events:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"before","in":"query","schema":{"type":"string"},"description":"ISO timestamp cursor from next_before"}],"responses":{"200":{"description":"A page of events (newest first)","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceEvent"}},"next_before":{"type":["string","null"]}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/workspaces/{id}/prs":{"get":{"summary":"List workspace pull requests","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Pull requests","content":{"application/json":{"schema":{"type":"object","properties":{"prs":{"type":"array","items":{"$ref":"#/components/schemas/PullRequest"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/workspaces/{id}/previews":{"get":{"summary":"List workspace previews","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dev-server previews","content":{"application/json":{"schema":{"type":"object","properties":{"previews":{"type":"array","items":{"$ref":"#/components/schemas/Preview"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/repos":{"get":{"summary":"List repos","responses":{"200":{"description":"Connected repositories","content":{"application/json":{"schema":{"type":"object","properties":{"repos":{"type":"array","items":{"$ref":"#/components/schemas/Repo"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/workspaces/{id}/agent":{"post":{"summary":"Start an AQ Composer run in a workspace","description":"Give the agent a task in plain language; it codes in the workspace, asks when something is ambiguous, and commits the reviewed change to the workspace branch (you decide when to push or open a PR). Pick the executor zone (source: 'native' for the user's own CLI, explicit 'aq' to bill AQ credits; omitting both source and native_harness is rejected) and model. An Idempotency-Key must never be reused across different picks, because replay returns the ORIGINAL session and ignores the new body. Requires agent:run and an Idempotency-Key header.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Unique key per logical request. Retries with the same key replay the first response instead of re-executing. Reusing a key with a different body returns 422."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","maxLength":12000},"source":{"type":"string","enum":["aq","native"],"description":"Executor zone. 'native' runs the user's own CLI subscription (free of AQ credits); 'aq' bills the seat's AQ credits and must be chosen explicitly. Omitting source is rejected (400 source_required) unless native_harness is set, which implies 'native'; it never falls back to the billed path."},"native_harness":{"type":["string","null"],"description":"Harness id when source=native"},"native_model_id":{"type":["string","null"],"description":"Model id within the harness when source=native"},"native_connection_id":{"type":["string","null"],"description":"Which of your connected accounts of that harness runs the session. Omit for the account you used last."},"model_selection_id":{"type":["string","null"],"description":"AQ model alias when source=aq. Omit for the default (Auto); named models come from the composer catalog."},"effort":{"type":["string","null"],"description":"Reasoning effort, where the chosen option supports it"}},"required":["message","source"]}}}},"responses":{"201":{"description":"Run created (queued; a worker starts it within seconds)","content":{"application/json":{"schema":{"type":"object","properties":{"agent_session":{"$ref":"#/components/schemas/AgentSession"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited, or too many active runs for this team","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/agent-sessions/{id}":{"get":{"summary":"Get an agent run","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The run","content":{"application/json":{"schema":{"type":"object","properties":{"agent_session":{"$ref":"#/components/schemas/AgentSession"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/agent-sessions/{id}/events":{"get":{"summary":"List an agent run's progress events","description":"Ordered typed events (plan, edit, test_result, review_finding, status_changed...). Poll with after_seq for incremental reads; page backwards with before_seq (or tail=1 for the newest page). has_more is true when another page exists in the direction you queried.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"after_seq","in":"query","schema":{"type":"string"}},{"name":"before_seq","in":"query","schema":{"type":"string"}},{"name":"tail","in":"query","schema":{"type":"string","enum":["0","1"]},"description":"1 = return the newest page (still oldest-first)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":200}}],"responses":{"200":{"description":"Events in order","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/AgentRunEvent"}},"has_more":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/agent-sessions/{id}/messages":{"get":{"summary":"Read the run's transcript","description":"Returns the newest transcript page in chronological order. Retracted tombstones remain present with retracted_at set.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":200}}],"responses":{"200":{"description":"Messages","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/AgentMessage"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}},"post":{"summary":"Send a message to the run","description":"Queues a follow-up for the next turn, steers a running agent, or answers its question and resumes a waiting run. deliver=now additionally interrupts the in-flight turn so the queued batch drives the next wake. Requires an Idempotency-Key header.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Unique key per logical request. Retries with the same key replay the first response instead of re-executing. Reusing a key with a different body returns 422."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","maxLength":12000},"deliver":{"type":"string","enum":["queue","now"],"description":"'queue' (default) waits for the current turn to finish; 'now' stops it and starts the next turn with the queued batch."},"pick":{"type":"object","description":"Model/subscription for this message, applied between turns. Omission captures the conversation's current selection. Only the conversation owner can choose a different selection.","properties":{"source":{"type":"string","enum":["aq","native"]},"modelSelectionId":{"type":"string"},"nativeHarness":{"type":"string"},"nativeModelId":{"type":"string"},"effort":{"type":"string"}},"required":["source"]}},"required":["content"]}}}},"responses":{"201":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean"},"message_id":{"type":"string","description":"Durable message id; use it to retract the message while claimed_at is null"},"delivery":{"type":"string","enum":["queue","now"],"description":"Observed disposition: now means the message joined an immediate wake; queue means it is waiting for the current turn"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"409":{"description":"The run already ended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/agent-sessions/{id}/messages/{messageId}":{"delete":{"summary":"Retract a queued message","description":"Pulls a queued follow-up back before a turn claims it. 409 once the message already reached the agent. Requires an Idempotency-Key header.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"messageId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Unique key per logical request. Retries with the same key replay the first response instead of re-executing. Reusing a key with a different body returns 422."}],"responses":{"200":{"description":"Retracted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"409":{"description":"The message already reached the agent, or the run ended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/agent-sessions/{id}/messages/order":{"patch":{"summary":"Reorder queued messages","description":"Sets the delivery order of the still-queued follow-ups. message_ids must be the complete current queue in its new order; 409 queue_changed when a row was claimed or retracted in between. Requires an Idempotency-Key header.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Unique key per logical request. Retries with the same key replay the first response instead of re-executing. Reusing a key with a different body returns 422."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message_ids":{"type":"array","items":{"type":"string"},"minItems":1}},"required":["message_ids"]}}}},"responses":{"200":{"description":"Reordered","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"409":{"description":"The queue changed, or the run ended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/agent-sessions/{id}/messages/{messageId}/deliver":{"post":{"summary":"Run a queued message next","description":"Moves the queued message to the front and, if a turn is in flight, stops it so the next turn starts with this message. Requires an Idempotency-Key header.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"messageId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Unique key per logical request. Retries with the same key replay the first response instead of re-executing. Reusing a key with a different body returns 422."}],"responses":{"200":{"description":"Scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"delivery":{"type":"string","enum":["queue","now"],"description":"now means a wake started with this message; queue means it leads the queue and waits for the current turn"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"409":{"description":"The message already reached the agent, the queue changed, or the run ended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/agent-sessions/{id}/interrupt":{"post":{"summary":"Stop the agent's current turn","description":"Kills the in-flight work; the conversation stays open and the next message resumes it. Partial work stays in the workspace. Requires an Idempotency-Key header.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Unique key per logical request. Retries with the same key replay the first response instead of re-executing. Reusing a key with a different body returns 422."}],"responses":{"200":{"description":"Stopped","content":{"application/json":{"schema":{"type":"object","properties":{"agent_session":{"$ref":"#/components/schemas/AgentSession"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"409":{"description":"The conversation already ended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/agent-sessions/{id}/archive":{"post":{"summary":"Close an agent conversation","description":"Stops anything in flight and archives the session: it leaves the workspace's tab strip, the transcript stays readable by id. Requires an Idempotency-Key header.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Unique key per logical request. Retries with the same key replay the first response instead of re-executing. Reusing a key with a different body returns 422."}],"responses":{"200":{"description":"Archived","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/webhooks":{"get":{"summary":"List webhook endpoints","description":"Requires webhooks:manage. Also returns the full list of event types.","responses":{"200":{"description":"Webhook endpoints","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"event_types":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}},"post":{"summary":"Create a webhook endpoint","description":"Requires webhooks:manage and an Idempotency-Key header. The signing secret is returned exactly once. Deliveries are signed: aq-signature: t=<unix>,v1=<hex hmac-sha256 of `t.body`>.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Unique key per logical request. Retries with the same key replay the first response instead of re-executing. Reusing a key with a different body returns 422."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Public https endpoint"},"description":{"type":"string","maxLength":500},"event_types":{"type":"array","items":{"type":"string"},"description":"Empty = all events"}},"required":["url"]}}}},"responses":{"201":{"description":"Created (secret shown once)","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"},"secret":{"type":"string"}}}}}},"400":{"description":"Invalid URL or event types","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/v1/webhooks/{id}":{"delete":{"summary":"Delete a webhook endpoint","description":"Requires webhooks:manage and an Idempotency-Key header.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Unique key per logical request. Retries with the same key replay the first response instead of re-executing. Reusing a key with a different body returns 422."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found (or not visible to this key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable snake_case code"},"message":{"type":"string"}},"required":["error"]}}}}}}}}}