AI Workforce OneHQDocs

API quickstart

Create an API key and make your first HQ API calls in a few minutes.

1. Create a key

In HQ, open Profile, then API keys, and choose Create key. Give it a name, tick the scopes it needs (for this quickstart, See the AI team and See sessions), and create it. HQ asks you to confirm it is you first.

The key is shown once. Copy it into your secret manager or an environment variable:

export HQ_API_KEY="hq_live_…"

Owners and admins can also create service keys in Settings, Developers. See Authentication for the difference.

2. Check the key

curl https://api-hq.aiworkforceone.com/v1/me \
  -H "Authorization: Bearer $HQ_API_KEY"

The answer describes the key: its organization, its scopes, the version it is pinned to and when it expires.

3. List your AI teams and their sessions

curl "https://api-hq.aiworkforceone.com/v1/teams?limit=10" \
  -H "Authorization: Bearer $HQ_API_KEY"

curl "https://api-hq.aiworkforceone.com/v1/sessions?team=team_3kQ9vX2mR8tLpZ4wYc1aBd&status=running" \
  -H "Authorization: Bearer $HQ_API_KEY"

Lists return { "object": "list", "data": [...], "has_more": true }. To get the next page, pass the last id as starting_after. See Pagination.

4. Send a prompt and watch it run

This needs a key with Type in their own sessions and Read the chat view on the team. Open the session's event stream in one terminal:

curl -N https://api-hq.aiworkforceone.com/v1/sessions/sess_…/events \
  -H "Authorization: Bearer $HQ_API_KEY"

and send the prompt from another. The Idempotency-Key makes a retry safe: it is never typed twice.

curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_…/messages \
  -H "Authorization: Bearer $HQ_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"content":[{"type":"text","text":"List the open pull requests"}]}'

The stream shows the prompt arrive (session.message.status_changed, then delivered), the work (session.tool_use.*) and the answer (session.message.completed, then session.turn.completed). A session signed in with a person's own Claude account takes prompts only from that person's own user key. See Sessions and prompts and Streaming.

5. If something goes wrong

Every error is a problem document with a code and a request_id:

{
  "type": "https://hq.aiworkforceone.com/docs/api/errors/#permission_denied",
  "title": "Permission denied",
  "status": 403,
  "code": "permission_denied",
  "detail": "This key does not have teams:read.",
  "permission": "teams:read",
  "request_id": "6f1c…"
}

See Errors for every code and what to do about it.

If a key leaks

Revoke it at once, from your own code or by hand:

curl -X DELETE https://api-hq.aiworkforceone.com/v1/api_keys/current \
  -H "Authorization: Bearer $HQ_API_KEY"

You can also revoke any of your keys in HQ under Profile, API keys.