# API quickstart

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



## 1. Create a key [#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:

```bash
export HQ_API_KEY="hq_live_…"
```

Owners and admins can also create **service keys** in **Settings**, **Developers**. See
[Authentication](/docs/api/authentication/) for the difference.

## 2. Check the key [#2-check-the-key]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```bash
    curl https://api-hq.aiworkforceone.com/v1/me \
      -H "Authorization: Bearer $HQ_API_KEY"
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    const res = await fetch('https://api-hq.aiworkforceone.com/v1/me', {
      headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}` },
    });
    console.log(await res.json());
    ```
  </Tab>

  <Tab value="Python">
    ```python
    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())
    ```
  </Tab>
</Tabs>

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 [#3-list-your-ai-teams-and-their-sessions]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```bash
    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"
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    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');
    }
    ```
  </Tab>

  <Tab value="Python">
    ```python
    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")
    ```
  </Tab>
</Tabs>

Lists return `{ "object": "list", "data": [...], "has_more": true }`. To get the next page, pass
the last id as `starting_after`. See [Pagination](/docs/api/pagination/).

## 4. Send a prompt and watch it run [#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:

```bash
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.

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```bash
    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"}]}'
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    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", ... }
    ```
  </Tab>

  <Tab value="Python">
    ```python
    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", ...}
    ```
  </Tab>
</Tabs>

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](/docs/api/sessions-and-prompts/) and
[Streaming](/docs/api/streaming/).

## 5. If something goes wrong [#5-if-something-goes-wrong]

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

```json
{
  "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](/docs/api/errors/) for every code and what to do about it.

## If a key leaks [#if-a-key-leaks]

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

```bash
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**.
