HQ API overview
Drive your AI teams from your own code, CI jobs and products with the HQ API.
The HQ API lets your own code read and drive your organization in AI Workforce One HQ: your AI teams, their sessions and schedules, their Cloud Computers, secrets and variables, billing and the audit log.
It is a REST API with JSON bodies, served from its own host:
https://api-hq.aiworkforceone.com/v1Keys for it start with hq_live_.
API keys are on every plan. During a trial the API can only read, and your organization can hold one key; choose a plan to make changes. OAuth apps need the Growth plan or higher.
What you get
- API keys you create in HQ, each with exactly the scopes it needs. See Authentication.
- The same rules as HQ. A key can never do more than the person or role behind it can do in HQ, and it is checked again on every request.
- Stable shapes. Every object has an
objectfield, ids are prefixed (team_…,sess_…), timestamps are UTC, and fields aresnake_case. - Cursor pagination on every list. See Pagination.
- Standard errors in RFC 9457
application/problem+json. See Errors. - Dated versions, so a change can never break your code without notice. See Versioning.
What this version covers
This first version reads: your organization, people and invitations, AI teams and their Cloud Computers, sessions and their usage, schedules and their runs, secret names, variables, templates, usage, your subscription and invoices, the audit log and your API keys. It also writes, sends prompts to sessions and streams their output, and calls your own URLs with signed webhooks when things happen. The changelog says what changed and when.
What the API never does
Some actions stay in HQ, where they are protected by a fresh sign-in check, and a leaked key can never take them:
- reveal a secret value (the API returns secret names, never values);
- create or roll API keys (a key can only revoke itself);
- sign in to Claude or ChatGPT, or use someone else's personal sign-in;
- change anyone's organization role, remove someone from the organization, change owners, or change billing or security settings (inviting people and choosing who can reach an AI team are in the API).
The contract
The whole API is described by an OpenAPI 3.1 document, served at GET /v1/openapi.json and
rendered as the API reference.