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"const res = await fetch('https://api-hq.aiworkforceone.com/v1/me', {
headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}` },
});
console.log(await res.json());import os, requests
res = requests.get(
"https://api-hq.aiworkforceone.com/v1/me",
headers={"Authorization": f"Bearer {os.environ['HQ_API_KEY']}"},
)
print(res.json())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"const headers = { Authorization: `Bearer ${process.env['HQ_API_KEY']}` };
const teams = await (await fetch('https://api-hq.aiworkforceone.com/v1/teams?limit=10', { headers })).json();
for (const team of teams.data) {
const url = `https://api-hq.aiworkforceone.com/v1/sessions?team=${team.id}&status=running`;
const sessions = await (await fetch(url, { headers })).json();
console.log(team.name, sessions.data.length, 'running');
}import os, requests
headers = {"Authorization": f"Bearer {os.environ['HQ_API_KEY']}"}
base = "https://api-hq.aiworkforceone.com/v1"
teams = requests.get(f"{base}/teams", params={"limit": 10}, headers=headers).json()
for team in teams["data"]:
sessions = requests.get(
f"{base}/sessions", params={"team": team["id"], "status": "running"}, headers=headers
).json()
print(team["name"], len(sessions["data"]), "running")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"}]}'const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_…/messages', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
'Idempotency-Key': crypto.randomUUID(),
'Content-Type': 'application/json',
},
body: JSON.stringify({ content: [{ type: 'text', text: 'List the open pull requests' }] }),
});
console.log(res.status, await res.json()); // 202 { object: "message", status: "accepted", ... }import os, uuid, requests
res = requests.post(
"https://api-hq.aiworkforceone.com/v1/sessions/sess_…/messages",
headers={
"Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={"content": [{"type": "text", "text": "List the open pull requests"}]},
)
print(res.status_code, res.json()) # 202 {"object": "message", "status": "accepted", ...}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.