# 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/v1
```

Keys 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](/docs/api/oauth/) need the Growth plan or
higher.

## What you get [#what-you-get]

* **API keys** you create in HQ, each with exactly the scopes it needs. See
  [Authentication](/docs/api/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 `object` field, ids are prefixed (`team_…`, `sess_…`),
  timestamps are UTC, and fields are `snake_case`.
* **Cursor pagination** on every list. See [Pagination](/docs/api/pagination/).
* **Standard errors** in RFC 9457 `application/problem+json`. See [Errors](/docs/api/errors/).
* **Dated versions**, so a change can never break your code without notice. See
  [Versioning](/docs/api/versioning/).

## What this version covers [#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](/docs/api/webhooks/) when things happen. The [changelog](/docs/api/changelog/) says what
changed and when.

## What the API never does [#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-contract]

The whole API is described by an OpenAPI 3.1 document, served at `GET /v1/openapi.json` and
rendered as the [API reference](/docs/api/reference/).
