# Cloud Computer sizes and Boost URL: /docs/ai-teams/cloud-computers Every AI Team runs on its own Cloud Computer. Boost gives a team more processors, memory and concurrent sessions. Organization owners and admins change the size. Every AI Team starts on a **Standard** Cloud Computer. When a team needs more room, give it a **Boost**. The size applies to that team only. | Size | Processors | Memory | Concurrent sessions | | --------- | ------------- | ------ | ------------------- | | Standard | 2 shared vCPU | 4 GB | 5 | | Boost | 2 vCPU | 8 GB | 12 | | Boost Pro | 4 vCPU | 16 GB | 24 | | Boost Max | 8 vCPU | 32 GB | 40 | Concurrent sessions is the most a team can run at once. A new session also needs room on the Cloud Computer: see [When the Cloud Computer is busy](#when-the-cloud-computer-is-busy). Professional includes one Boost. Other Boosts are add-ons, charged per team per month. See [Billing and plans](/docs/billing/) for prices. ## Change a team's size [#change-a-teams-size] Open the team and select **Settings**. **AI Team Cloud Computer** shows the sizes, with the current one marked. Select the size you want and confirm. A bigger size is charged today for the rest of the billing period, prorated to the day. A smaller one credits your next invoice. The team restarts on the new Cloud Computer with everything in place. This usually takes about 5 to 6 minutes. Your sessions pause and come back on their own. You can also assign Boosts from **Billing**, under **Add-ons**. Organization owners and admins change a team's size and buy Boosts. During a trial, start your paid plan first. ## When a team runs short of memory or processor [#when-a-team-runs-short-of-memory-or-processor] When a team's Cloud Computer is almost out of memory, or its processor has been working at full capacity, HQ says so on the team's page, in its **Settings** and at the top of its sessions. Owners and admins see **Upgrade Cloud Computer** with the price of the next size up. Everyone else sees who to ask. Running fewer AI Employees at the same time also helps. ## When the Cloud Computer is busy [#when-the-cloud-computer-is-busy] Most sessions use little memory, so a team can run many at once. One heavy task, such as a large build, a data job or a browser, can still fill the Cloud Computer. When its memory is at 80% or more, or its processor has been working at full capacity for a while, a new session does not start, even if the team is below its concurrent sessions. HQ says: > This AI Team's Cloud Computer is busy right now, so another session could not start. Stop a session you no longer need, or move the team to a bigger size, then try again. Sessions that are already running keep running. Stop a session you no longer need, or give the team a bigger size. A scheduled run that finds the Cloud Computer busy waits or is skipped, the same as when every session slot is taken (see [Schedules](/docs/schedules/)). On the largest size your organization can buy, there is no upgrade button. When a bigger Cloud Computer exists with more of what the team is short of, HQ says so and that it is available on request. Owners and admins can select **Contact support** to ask for one. Everyone else is asked to talk to an owner or admin. ## When a new size takes effect [#when-a-new-size-takes-effect] When the new size applies depends on what the team is doing at the time. ### A running team [#a-running-team] * **A bigger size** applies now. The team restarts on the new Cloud Computer with everything in place. This usually takes about 5 to 6 minutes. * **A smaller size** waits for the team's next restart, so your work is never stopped to make the machine smaller. HQ shows **Restart now to apply** if you'd rather not wait. ### A stopped team [#a-stopped-team] Nothing restarts. HQ shows "Boost Max applies the next time this team starts." (with the size you picked). The next time anyone starts a session on the team, its Cloud Computer starts on the new size, in one start. **Open sessions** takes you there. Occasionally a start comes up on the old size first, for example when the new size is briefly unavailable in our cloud region. The team still starts, and a bigger size then follows once it is running, the same way as on a running team. ### A sleeping team [#a-sleeping-team] A sleeping team wakes on its current size, exactly as you left it. A bigger size then applies once it is running, the same way as on a running team. A smaller size applies at the team's next restart. ### A team that is starting [#a-team-that-is-starting] If the size changes just before the team starts, HQ shows "This team is starting on Boost Max." and it starts on the new size. If the start is already under way, a bigger size applies once the team is running, and a smaller one at its next restart. ### If you restart to apply the change [#if-you-restart-to-apply-the-change] HQ only says "Restarting now" when the restart actually started. Otherwise it tells you when the new size applies: the next time the team starts, as it starts, or once it is running. If something else is still changing the Cloud Computer, HQ asks you to try again once it's running. ## Sleep and wake [#sleep-and-wake] A Cloud Computer sleeps when nobody uses it and nothing runs. Opening a session, or a scheduled run, wakes it. Waking takes 15 to 30 seconds up to 16 GB, and 30 to 45 seconds from 32 GB. ## Related [#related] --- # Create an AI Team URL: /docs/ai-teams An AI Team is a team of AI Employees with its own Cloud Computer, files, secrets and schedules. Organization owners and admins create them. Each AI Team gets its own **AI Team Cloud Computer**: a private computer in the cloud where its AI Employees work. A team's files, secrets, variables and schedules belong to that team only. Your plan sets how many AI Teams you can have. ## Create a team [#create-a-team] Select **AI Teams** in the sidebar, then **Add AI Team**. The dialog shows how many AI Teams your plan includes and how many you use. **From scratch** gives you an empty team. **From a template** copies a team someone shared with you: paste its link, and the team arrives with its AI Employees, skills, schedules and the list of secrets it needs. Before a template team is created, HQ lists the hooks, connectors and commands it can run, and you confirm each one. Give the team a name and, if you like, a description. Choose **Claude Code** (Anthropic) or **Codex** (OpenAI). The engine can't be changed after the team is created. Under **Secrets and variables for this team**, attach what the team needs from your vault. Nothing is attached until you confirm it here. You can also do it later from the team's **Secrets** tab. Select **Create AI Team**, then **Done**. The team is ready to open. Organization owners and admins create and delete AI Teams. A team owner runs the team: renames it, manages who has access, and updates or restarts its Cloud Computer. ## Inside a team [#inside-a-team] Open a team to see its sessions, how many run now, its Cloud Computer size, its storage and its AI Employees. The tabs list the team's **AI Employees**, **Sessions**, **Secrets**, **Variables** and **Schedules**. Select **New session** to start work, or **Settings** to change the team. ## Delete a team [#delete-a-team] Open the team's **Settings** and select **Delete AI Team** at the bottom. Its sessions stop at once. Its files are kept for 30 days in case you change your mind (contact support to restore the team), then erased. A Boost you bought for the team is released. ## Related [#related] --- # AI Team settings URL: /docs/ai-teams/settings Rename a team, decide who can see its sessions, set a team API key, turn on the browser and remove your saved sign-ins. Team owners change a team's settings. Open a team and select **Settings** to change it. Each section saves on its own. ## Name, description and people [#name-description-and-people] Under **Team**, change the name and description and select **Save**. The engine is shown but can't be changed. **Manage who is on this team** opens the team's access on [People](/docs/people/), where you give each person **Owner**, **Editor** or **Viewer** on the team. ## Who can see sessions [#who-can-see-sessions] Under **Access**, choose who sees the team's sessions by default: * **Everyone on the team sees all sessions.** The default. Anyone on the team can watch any session, read only unless they own it. * **People see only their own sessions.** Members see the sessions they own. Team owners still see every session. Only a session's owner can ever type in it. An owner can also share one session with specific people from that session's **Share** button. A session's conversation belongs to the team, not to one person: it stays with the team when the session is handed to someone else. Claude logins and personal settings are never shared. Each person signs in with their own Claude account. ## Team API key [#team-api-key] A team API key bills to your team's own Anthropic Console account. It is used only by sessions and schedules set to **Team API key**, never for someone's personal login. Select **Set API key** to add one. ## Your sign-ins [#your-sign-ins] If you saved your Claude sign-in on this team's Cloud Computer, you can remove it here. Only you can remove yours. ## Browser for AI Employees [#browser-for-ai-employees] When the team's Cloud Computer supports it, **Enable browser** gives your AI Employees a web browser they can use. You can watch it, take control of it and hand it back with [Browser View](/docs/sessions/browser-view/). **Turn off browser** closes it at once, also in running sessions; saved sign-ins are kept unless you tick **Also delete saved sign-ins**. ## Your browser sign-ins [#your-browser-sign-ins] The sites you stay signed in to in your AI Employee's browser on this team. Select **Sign out** next to a site to forget it, or **Clear everything** to forget them all. If the team shares one Cloud Computer between its members, you turn saved sign-ins on here yourself, after reading the warning. See [Stay signed in to sites](/docs/sessions/browser-view/#stay-signed-in-to-sites). Team owners change the name, access, session visibility and team API key, and organization owners and admins are team owners on every team. Team owners enable the browser for the whole team; editors can enable it for sessions on their own Claude login. Anyone removes their own sign-ins and browser sign-ins. ## Related [#related] --- # When a Cloud Computer sleeps URL: /docs/ai-teams/sleep An AI Team Cloud Computer that nobody is using goes to sleep and wakes exactly as it was. What keeps it awake, and what happens to a question Claude asked that nobody answered. An AI Team Cloud Computer that nobody is using, and that has no work running, goes to sleep after about 15 minutes. Sleep keeps its memory. When it wakes, every session is exactly where it was, including what is on its screen. ## What keeps it awake [#what-keeps-it-awake] * Someone is at the team: in HQ in the browser, in VS Code or with `hq`. * Claude is working: writing an answer, running a tool, or a process it started is still using the processor. * A command in a terminal session is using the processor, such as a long build that prints nothing. A terminal waiting at its prompt does not keep it awake. * Any other program on the Cloud Computer is using a noticeable share of the processor, such as a job left running in the background. * Remote control (`/remote-control`) is on in a session. * A scheduled prompt is due soon. * An app preview is in use. * An AI Employee is waiting on a "Needs you" request (for up to 30 minutes). ## A question nobody answered [#a-question-nobody-answered] Claude sometimes stops to ask you something: a question with choices, a plan to approve, a permission prompt, or a menu such as `/model`. The session then waits for you. Today, a Cloud Computer with a question open on screen stays awake until the question is answered. Letting it sleep behind a question that nobody is answering is coming, and is off for now. When it is on, it works like this. Work can go on behind the question: subagents, background commands, test runners and containers keep running. So the Cloud Computer stays awake while any of this is true: * any command Claude started is still running, attached to the session or detached from it (with `nohup`, `&`, or in `tmux` or `screen`), even one that looks stuck or uses no processor; * a command is running in a terminal of the Cloud Computer; * a Docker container is running, or a Docker build or pull is in progress; * a program left running in the background is listening on a port; * something on the Cloud Computer is using more than a little of the processor (2 % of one core, measured over the last two minutes). It can go to sleep once the question has sat completely still, at the earliest 15 minutes after the last time the session's screen changed, a new command started, or any of the above was true. The other rules on this page still apply, so it can stay awake longer. If anyone typed into the session, or a prompt was delivered to it (a schedule or an API message), after Claude's status line was last on screen, the Cloud Computer stays awake until the question is answered. The same holds if remote control was on in that session the last time its status line was on screen, so you can still answer from your phone. Sleeping never answers the question. When you come back, the Cloud Computer wakes and the question is still on screen, waiting for you. ## Related [#related] * [Cloud Computer sizes and Boost](/docs/ai-teams/cloud-computers/) * [Sessions](/docs/sessions/) * [Schedules](/docs/schedules/) --- # Storage for AI Teams URL: /docs/ai-teams/storage How your organization's storage is shared by its AI Teams, how a team's disk grows, and how owners and admins set a cap or a reserve for each AI Team. Pooled storage is reaching organizations over the coming weeks. Until it reaches yours, each AI Team grows up to an even share of your organization's storage, and the Storage tab in Billing is not shown yet. ## One pool for the whole organization [#one-pool-for-the-whole-organization] Your plan includes an amount of storage for the whole organization. Each extra AI Team you buy adds its share, and each storage block adds 100 GB. All of it is one pool that your AI Teams share. Every AI Team has its own disk. A new AI Team starts with a small disk, and the disk grows on its own, 10 GB at a time, when it is about 85% full. It can grow into any part of the pool that no other AI Team is using or has reserved. A storage block can be used in full by a single AI Team. A disk never shrinks and nothing on it is ever removed to make room. A stopped or sleeping AI Team keeps its disk, and that space stays counted as used, so another AI Team can never grow into it. ## When the pool is full [#when-the-pool-is-full] When the AI Teams' disks use the whole pool: * A team's disk stops growing. Its data is safe and nothing is removed. Team Settings, under **Storage**, says **Growth paused** and why. * A new AI Team cannot be created, because there is no room for its first disk. You are asked to add storage first. To make room, add a 100 GB storage block in **Billing**, under **Plan & add-ons**, or lower a reserve (see below). An owner or admin sees an **Add 100 GB** button on the team's Storage section when the pool is the reason a team cannot grow. ## When a disk is almost full [#when-a-disk-is-almost-full] HQ warns you before an AI Team's disk fills up, in the same places it warns about a busy processor or low memory: the **Cloud Computer** pill at the top of a session, and the card on the AI Team's overview and **Settings**. The pill shows **Disk** and a percentage; open it to read the warning. The percentage counts the room the disk can still grow into. A disk that is 85% full today but can still grow a lot does not warn, because it grows by itself. The warning comes as the disk gets close to the most it can grow to: its cap, your trial or plan allowance, or what is left in the pool. If a disk fills faster than it can grow, it warns too. It warns at: | Disk full | What it means | | --------- | --------------------------------------------------- | | 85% | Time to make room. | | 90% | Make room soon: see below for what happens at 100%. | | 95% | The disk is about to run out of space. | What 100% means: * Part of every disk (5%) is kept for the system, so 100% is when your files can no longer be saved. * If the AI Team uses Docker, 100% comes earlier: Docker is stopped when only about 1 GB or 3% of the disk is left, whichever is more, and that restarts the Cloud Computer and ends every running session. The percentage already counts this, so 95% always comes before Docker is stopped. A warning goes away once the disk is 5 points below the line, so it does not come and go while you clean up. To make room: * Delete files you no longer need from the AI Team's folder. * Clear `/tmp`. Each session's `/tmp` is on the team's disk. * Remove Docker images and containers you no longer use (for example, `docker image prune`). Or get more space. The warning names the fix that applies: * When a cap stops the disk, someone who can change storage limits raises the AI Team's cap under **Settings**, **Storage**. * During a trial, an owner or admin starts the paid plan in **Billing**; storage can be added after that. * When the pool or the plan allowance is full, an owner or admin adds storage in **Billing**. * With unlimited storage there is nothing to add; making room is the fix. Everyone else sees a note to ask an organization owner or admin. ## Caps and reserves [#caps-and-reserves] Organization owners and admins can set two limits on any AI Team, from the team's **Settings**, under **Storage**, or from **Billing**, under **Storage**, with **Edit**: * **Cap**: the AI Team never grows past this size. The smallest cap is 10 GB. A cap below the current disk does not shrink it and removes no data. It only stops the disk from growing. * **Reserve**: storage held for this AI Team. Other AI Teams cannot grow into it, even while this team's disk is smaller. A reserve cannot be more than the cap, and you can only reserve space the pool still has free. Leave a field empty for no cap or no reserve. Every change is recorded in the activity log. The **Storage** tab in **Billing** shows the pool (disks, reserved and free space) and, for each AI Team, its disk, cap, reserve, how far it can grow, and whether growth is paused. ## Who can see and change storage [#who-can-see-and-change-storage] | Who | Sees | Can change caps and reserves | | --------------------------- | ----------------------------------------- | ---------------------------- | | Organization owner or admin | Every AI Team's storage and the pool | Yes | | Organization member | The storage of the AI Teams they can open | No | Members see their AI Team's disk, how far it can grow, and its cap and reserve, but not the sizes of other AI Teams. ## Trials and unlimited plans [#trials-and-unlimited-plans] * **Trial**: an AI Team grows up to the 20 GB a trial includes. Caps and reserves can still be set. * **Unlimited storage** (Enterprise): there is no pool to share. A cap can still be set on any AI Team; a reserve does not apply. ## What is kept when the Cloud Computer restarts [#what-is-kept-when-the-cloud-computer-restarts] The AI Team's disk is kept: the team's folder, and your home folder, `$HOME`, with everything you install or save in it. The rest of the Cloud Computer comes fresh from the system image every time it restarts (Update, Restart or wake from sleep). So install your own tools into `$HOME`, for example a program in `$HOME/.local/bin`, and keep sign-in tokens and settings under `$HOME/.config`. The folder `/home/node` belongs to the system image and is read-only: saving a tool there fails right away with "Permission denied", instead of seeming to work and disappearing at the next restart. Some tools come with every Cloud Computer, so there is nothing to install or keep for them: `git`, `python3`, `curl`, `jq`, ImageMagick, `ripgrep`, `ffmpeg` (with `ffprobe`) and `unzip`. For a Node tool, this works on every Cloud Computer. The first line puts `$HOME/.local/bin` on your `PATH` for every future session, once: ```sh echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.bashrc" npm install -g --prefix "$HOME/.local" ``` ## Units [#units] Storage is counted in GB of 1024 MB each, the same unit used everywhere else in HQ. --- # Agency keys URL: /docs/api/agency-keys One key for your agency, acting for one client at a time with the HQ-Account header. What it can do, what it never can, and how your clients stay in control. An **agency key** belongs to your agency, not to one client. Each request names the client it acts for in the `HQ-Account` header: ```bash curl https://api-hq.aiworkforceone.com/v1/teams \ -H "Authorization: Bearer $HQ_AGENCY_KEY" \ -H "HQ-Account: bright-dental" ``` The value is the client's slug, the part of its address in your console. Every response is about that client only, exactly as if one of your Account managers were working in it. ## Create an agency key [#create-an-agency-key] In your agency's HQ, open **Settings**, then **Developers**, and create a key with the type **Agency key**. Agency owners and Account managers can create one. You confirm it is you first, and the key is shown once: store it in your secret manager. An agency key: * acts as your agency's **Account manager** role, never as a person; * reaches every AI team of the client it acts for (it cannot be narrowed to some teams); * lasts up to one year, like a service key, and switches off after 90 days unused. ## Which client: HQ-Account [#which-client-hq-account] * An agency key **needs** `HQ-Account` on every request. Without it the answer is `400 invalid_request`. * Any other key or app token **must not** send it: the answer is `400 invalid_request`. * A slug that is not one of your agency's current clients is `404 not_found`, the same answer for a client of another agency, a direct customer, or a slug that does not exist. With an SDK, pass the client once: ```ts const hq = new HQ({ apiKey: process.env.HQ_AGENCY_KEY, account: 'bright-dental' }); ``` ```python hq = HQ(api_key=os.environ["HQ_AGENCY_KEY"], account="bright-dental") ``` Use one client per SDK instance. ## What your clients control [#what-your-clients-control] Your clients decide what their provider may do, in **Settings**, **Provider access**. Your agency key follows their choice on every request: | The client chose | Your agency key | | ------------------------- | -------------------------------------------------------------------------------------------------------- | | Full access (the default) | Works, within the scopes you gave the key | | Billing only | Plan and billing reads only; anything else is `403 permission_denied` with `reason: agency_access_level` | | No access | `403 client_access_disabled` | | Owners only | `403 permission_denied` with `reason: delegation_ceiling`: a key is never an owner | | Terminal view off | No session history or chat | | File reading off | No file reads | A change takes effect on your next request. ## What an agency key never does [#what-an-agency-key-never-does] Whatever a client allows and whatever scopes the key has, an agency key never: * reads a secret value or a variable value, or changes a secret or a variable; * types into a session, starts one, or uses anyone's personal Claude or ChatGPT sign-in; * creates or changes a schedule, writes or downloads files, or downloads session history; * invites people, changes who has access to a team, or creates or deletes a team; * manages the client's API keys, apps, webhooks, roles, security settings, ownership, cancellation or payment method. These answer `403 permission_denied` with `reason: delegation_ceiling`. A key cannot even be created with these scopes. ## When it stops working [#when-it-stops-working] | Situation | Answer | | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | The key is revoked (in HQ, or by itself with `DELETE /api_keys/current`), expired or unused for 90 days | `401 invalid_credentials` | | Your agency account is suspended, on hold by HQ Support, or more than 3 days past due | `403 agency_suspended` | | The client turned its provider's access off | `403 client_access_disabled` | | The client is no longer one of your clients | `404 not_found` | | The client is on hold because of your agency's account (day 14) | Reads work; every change is `403 agency_suspended` | ## Limits and retries [#limits-and-retries] * **Rate limits** apply per key (600 requests a minute across all your clients, on each API server) and per client (a budget for your agency in that client, separate from the client's own). See [Rate limits](/docs/api/rate-limits/). * **Idempotency keys** are kept per key per client: the same `Idempotency-Key` sent for two different clients is two different requests. See [Idempotency](/docs/api/idempotency/). ## Audit [#audit] Every change your key makes is recorded in the client's audit log as "\ support", with the key and the link it used, and a copy is recorded in your agency's own audit log, without the client's content. --- # Authentication URL: /docs/api/authentication API keys, the difference between your own keys and service keys, scopes, expiry, allowlists, rolling and revoking. Every request carries an API key in the `Authorization` header: ```bash curl https://api-hq.aiworkforceone.com/v1/me -H "Authorization: Bearer $HQ_API_KEY" ``` The API reads keys from that header only. It never reads a key from a query string, and it never accepts an HQ sign-in cookie: a browser signed in to HQ cannot call the API by accident. ## Two kinds of key [#two-kinds-of-key] | | Your own key | Service key | | ----------------------- | ------------------------------------ | -------------------------------------------------------- | | Created in | **Profile**, **API keys** | **Settings**, **Developers** (owners and admins) | | Acts as | You | The organization, with a role you pick (Member or Admin) | | Can do | At most what you can do in HQ, today | At most what its role can do | | When its creator leaves | Stops working | Keeps working; owners and admins are asked to review it | | Longest life | 90 days | 1 year | Use your own key for your scripts and experiments. Use a service key for CI and production systems that must keep working when people change. When the person who created a service key leaves the organization, the key keeps working: it belongs to the organization. The owners and admins are emailed the list of such keys, and **Settings**, **Developers** marks each one **Creator left**. Revoke the ones you no longer need. To keep one, roll it: the new key is yours. A service key never acts as a person, so it can never use anyone's personal Claude or ChatGPT sign-in. A Member-role service key reaches no AI team on its own; give it the Admin role to reach every AI team, or narrow it to some teams. ## Scopes [#scopes] A key holds **scopes**: the HQ permissions it may use, such as `teams:read` or `audit:read`. Pick only what the key needs. When you create a key, scopes above your own access are turned off. **Read only, everything I can see** ticks every read scope you hold and nothing that changes anything (not even waking a Cloud Computer). Every change a key makes shows in the HQ audit log as made "via API key" with the key's name, or "via" the app's name and "(OAuth)" for an OAuth app. Someone who cannot see the organization's keys or installed apps reads "via an API key" or "via an OAuth app". On every request the key's scopes are checked against what its person or role can do **right now**. If someone's access is reduced in HQ, every key they hold is reduced on its next request, with no change to the key. A request without the needed scope answers `403 permission_denied`, naming the missing permission. ## Limiting a key [#limiting-a-key] * **AI teams.** Restrict a key to some AI teams. Anything on another team answers `404`, as if it did not exist, and lists leave other teams out: secrets and variables shared with other teams only, the org chart's teams and the usage of other teams. Organization-wide secrets and variables stay visible. The audit log covers every team, so such a key cannot read it (`403`). Listing API keys, it sees itself and keys limited to its own teams, without their IP details. * **IP allowlist.** Give a key up to 32 addresses or ranges. A call from anywhere else answers `403 ip_not_allowed`. ## Expiry and unused keys [#expiry-and-unused-keys] Keys always expire: your own keys within 90 days, service keys within a year. A key nobody uses for 90 days switches off on its own. An expired or switched-off key answers `401 invalid_credentials`. If your organization requires two-factor authentication, your own keys work only while you have it turned on (`403 two_factor_required` otherwise). Changing your password does not stop your keys: the email HQ sends lists them, so you can revoke any you do not recognise. ## New location notices [#new-location-notices] The first time a key is used from a network it has never been used from, HQ emails the person it acts as, or, for a service key, the organization's owners and admins. If it was not you or your automation, revoke the key. A key used from very many networks gets one notice saying so, then at most one a day while new networks keep appearing. ## Rolling a key [#rolling-a-key] **Roll** makes a new key with the same name, scopes and limits. You choose how long the old key keeps working (none, 1 hour, 24 hours or 7 days) so your systems can switch over. The new key is shown once, like a new key. If you revoke the new key, the old one stops at the same moment, even inside its overlap: revoking after a roll is how you respond to a leak. ## Revoking a key [#revoking-a-key] Revoking takes effect on the key's next request. You can revoke your own keys in HQ, admins can revoke any key in **Settings**, **Developers**, and a key can revoke itself: ```bash curl -X DELETE https://api-hq.aiworkforceone.com/v1/api_keys/current \ -H "Authorization: Bearer $HQ_API_KEY" ``` ## Test and live keys [#test-and-live-keys] Keys start with `hq_live_` in production and `hq_test_` in the test environment. A key only works in its own environment. ## Keeping keys safe [#keeping-keys-safe] * Store keys in a secret manager or your CI's secrets, never in code. * Never ship a key in a browser or mobile app. * Give each system its own key, with only the scopes it needs, so you can revoke one without the others. The key appears in HQ only once, when it is created. HQ stores only a keyed hash of it and can never show it again. ## OAuth apps [#oauth-apps] To let **other** software act for a person in HQ (your product, used by people in other organizations), register an [OAuth app](/docs/api/oauth/) instead of handing out keys. The person approves it for one organization, it never does more than they can, and it never sends prompts. Its access token goes in the same `Authorization: Bearer` header. --- # API changelog URL: /docs/api/changelog What changed in the HQ API, by dated version. ## 2026-11-01 [#2026-11-01] The first version of the HQ API. ### In the first version [#in-the-first-version] * API keys: your own keys and service keys, with scopes, AI team limits, IP allowlists, expiry and rolling. Keys are created in HQ; over the API a key can read the organization's keys and revoke itself. * Read endpoints for your organization, its 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, and the audit log. * Writes: AI teams and their members, invitations, schedules (and running one now), secrets (values are write-only) and variables. * Sessions: start, stop, restart, rename and delete; send a prompt and follow its delivery; answer a question; interrupt. Who may type into a session follows whose Claude account it runs on. * A live event stream per session (server-sent events) with resume. * Cloud Computers: start, stop, update and resize, followed as operations. * Files: list a folder, read (masked) and write text files, create and delete. * Idempotency keys on every write, required where a repeat would do real work twice. * Webhooks: signed endpoints (Standard Webhooks) for replies finishing, prompt delivery, operations, secrets, API keys and endpoint health, with retries over about 3 days, a 30-day delivery log, retry and replay, secret rolling with an overlap, and `GET /events`. * Cursor pagination, RFC 9457 errors and per-key rate limits. * OAuth apps: register an app (Growth and up), let people approve it for one organization with authorization code and PKCE, rotating refresh tokens, revocation and discovery metadata. Third-party apps are off in an organization until an admin turns them on. An app never sends prompts. * SDKs for TypeScript (`@aiworkforceoneofficial/hq-sdk`) and Python (`aiworkforceone-hq`), with retries, idempotency, a resumable event stream, operation polling and webhook verification. ### Changes within 2026-11-01 [#changes-within-2026-11-01] Changed within this version, without a new version date. * New: `POST /schedules/{schedule_id}/move_to_session_owner` moves a schedule that reuses a session to that session's current owner, after the session was reassigned in HQ. It takes no body, and over the API only the session's owner can call it, with their own user key. A schedule that already runs as the owner is returned unchanged. See [Schedules](/docs/api/reference/schedules/). * `PATCH /schedules/{schedule_id}` that changes the `prompt`, the `target_session` or `create_new_session` of a schedule on someone's own Claude login (`run_with: personal`) answers `403 session_not_owned` unless your key acts as that person: the session's owner for a schedule that reuses a session, the schedule's creator for one that starts a new session each run. Renaming, rescheduling, enabling and disabling are unchanged. * A schedule `prompt` that contains a control character (tabs and line breaks are fine) or the text `kr-run:` is now refused with `422 validation_failed` on `POST /schedules` and `PATCH /schedules/{schedule_id}`, like a prompt that starts with `/`, `!` or `#`. `detail` says which rule it broke. See [Schedules](/docs/api/reference/schedules/). * Files: a folder entry carries `protected`. It is always `false` for now; it is for an upcoming feature that lets an AI team protect its Claude files. * Audit events: for that same upcoming feature, a key without `files:protected.read` will get `protected` in place of AI Employee and skill names (and the file paths that carry them) in the events of an AI team that protects them. See [Audit](/docs/api/reference/audit/). * `HQ-Account` is now refused with `400 invalid_request` on any credential that is not an [agency key](/docs/api/agency-keys/). It was ignored before; send it only with an agency key. * While a client's provider has put it on hold, every write answers `403 agency_suspended`, whatever key makes it (the client's own keys included). Reads keep working. * Cloud Computer operations: a resize `succeeds` only once the machine runs the new size. While an operation, an update or a resize is under way (also one started in HQ), another start, update or resize answers `409 operation_conflict` (it answered `409 workspace_updating` in some cases). A refused request no longer leaves a `failed` operation or sends `operation.failed`, and an update that starts nothing answers `200` with the computer (it answered a `failed` operation). * A move to a smaller tier on a running Cloud Computer answers `200` with the computer and the new `change_pending` field, not an operation: it applies at the next restart, as in HQ. * A prompt to a sleeping Cloud Computer answers `queued` with `waiting_for: "wake"` (it answered `accepted`), and the event stream reports `session.status` `asleep` for it (it said `unknown`). * Retrying `POST /webhook_endpoints` or a secret roll with the same `Idempotency-Key` answers the endpoint again, without `secret` and with `secret_omitted: true` (it answered an empty body). * A prompt to a session that is waiting for someone to deliver or deny a message from another Claude session answers `blocked_by_moment` and waits (it was typed into that dialog, lost, and the waiting message was declined). Answer it in the session's terminal in HQ and the prompt goes in. * `403 permission_denied` now says when the key has the scope but the person it acts as (or a service key's role) does not have the permission: `reason: "holder_permission"`. Without `reason`, the key itself lacks the scope, as before. * A prompt to a Cloud Computer that is just starting to go to sleep answers `accepted`: sending it keeps the machine awake. Only a machine that is asleep or waking answers `waiting_for: "wake"`. * A prompt to a session whose machine woke from sleep is delivered without anyone opening the session in HQ first (it failed `reconnecting`). A session that is signed out of Claude fails with `code: "login_required"`. * A prompt to a running Cloud Computer whose session is signed out of Claude fails with `code: "login_required"` within seconds. It waited 5 minutes and failed `wake_timeout`, and could record a wake of the machine that never happened. * Retrying a `DELETE` with the same `Idempotency-Key` answers the first `204` again, with `Idempotent-Replayed: true`. It answered `404` once the schedule, session or AI team was gone. * A message one Claude session receives from another (a teammate or helper session) is a `session.notice` with `kind: "peer_message"` and a short `text`, in the event stream and in `/items`. It was a `session.message.completed` with `role: "user"` carrying the raw text. The message itself is not sent (HQ's Chat view can open it; the API leaves it out on purpose for now). Routine status messages between sessions (idle, shutdown and plan-approval handshakes) that arrive together are one such notice, with a `text` like `3 status updates from another session (release-check)`. * A message from another session that Claude holds until the person decides (the two sessions' permission modes differ) is a `session.notice` with `kind: "peer_held"`, without the message itself. Its `session.input_required` (`kind: "peer_hold"`) has the fixed title `A message from another session is waiting`, without the name the sender gives itself. * When Claude asks whether to resume a long, idle conversation, the session's `session.input_required` has `kind: "resume_offer"`, the one choice `resume`, and `answerable_via_api: false`: answer it in HQ. A scheduled run resumes the conversation on its own: schedules always continue the session's conversation, and resuming a long conversation uses part of your Claude usage limit. * `POST /v1/sessions/{id}/interrupt` answers `409 held_peer_message` and presses nothing while Claude is holding a message from another session (Esc declined that message before). * A background job a session started that finished (a command or a helper run in the background) is a `session.notice` with `kind: "background_job"` and a one-line `text` such as `Background job finished: Run the tests (exit code 0)` (`Helper finished: …` for a helper). It sent nothing before. A notice with `kind: "error"` now says what to do for the kind of failure (Claude busy, a usage limit and when it resets, an expired login, a conversation too long, a lost connection), where it always said "Claude ran into a problem with this reply." * Each status a prompt moves through is its own `session.message.status_changed` event with its own `id`, on the event stream and in webhooks. A prompt that retried sent the same `id` again for a repeated `typing` or `queued`, so a client that drops duplicates by `id` missed them, and a webhook endpoint received only the first of each. * A key restricted to some AI teams is refused webhook management with `403 team_restricted`, the code of every other organization-wide refusal (it was `403 permission_denied`). * `400 invalid_request` for an unknown `HQ-Version` now carries the current version in its own `HQ-Version` header. * A `starting_after` on `GET /v1/audit_events` or `GET /v1/billing/invoices` that is not one of that list's ids now says so ("starting_after is not an audit event id.", "… not an invoice id."). It named an organization id before. The code (`invalid_cursor`) is unchanged. * A bad `?after=` on the session event stream now says "after is not a cursor this stream sent." It named `Last-Event-ID` before, even when only `?after=` was sent. The `errors[].field` and the code (`invalid_cursor`) are unchanged. * An empty `Last-Event-ID` header on the session event stream now counts as no header, so the stream resumes from `?after=` when you send one. It was ignored before: the stream started from the beginning, and a bad `?after=` was not refused. A bad one now answers `400 invalid_request` (`invalid_cursor`, field `after`). * Unknown field names echoed in errors are now cut to 64 characters. * A schedule with neither or both of `target_session` and `create_new_session: true` (on `POST /schedules`, or a `PATCH /schedules/{schedule_id}` that leaves it so) now says "Specify exactly one of target_session or create_new_session: true." and lists both fields in `errors` (code `exactly_one`). It named fields the API does not have. The status and code (`422 validation_failed`) are unchanged. * Errors about an AI team now say "team" in `detail`, as the rest of the API does: "No such team.", "A team with this name already exists.", "Team limit reached." and others. Some said "workspace". Status codes and `code` values are unchanged. * `409 workspace_paused` is now documented: creating with `start`, starting or restarting a session on a paused AI team answers it. Starting and creating with `start` are unchanged; a restart of a running session now leaves it running (it was stopped first, and then not started again). See [Errors](/docs/api/errors/#workspace_paused). * `409 workspace_updating` is now documented: creating with `start`, starting or restarting a session while the AI team's Cloud Computer is being updated or resized answers it. The behavior is unchanged. See [Errors](/docs/api/errors/#workspace_updating). * `PATCH /schedules/{schedule_id}` can switch a schedule's mode with one field: `create_new_session: true` clears its `target_session`, and `target_session` turns `create_new_session` off. Either switch was refused with `422 validation_failed` before. --- # Deprecation policy URL: /docs/api/deprecation-policy How much notice you get before anything in the HQ API goes away. * **Dated versions.** A breaking change ships under a new `HQ-Version`. Keys pinned to an older version keep the old behaviour. See [Versioning](/docs/api/versioning/). * **Notice.** Before an old dated version stops working we give at least **6 months** of notice. Responses served at that version carry `Deprecation` and `Sunset` headers, and we email the owners of keys still pinned to it 90, 30 and 7 days before. * **The major version.** `/v1` stays supported for at least **24 months** after a `/v2` exists. * **Every change** is in the [changelog](/docs/api/changelog/). --- # Errors URL: /docs/api/errors Every HQ API error is an RFC 9457 problem document. This page lists every code. An error answers with `Content-Type: application/problem+json`: ```json { "type": "https://hq.aiworkforceone.com/docs/api/errors/#not_found", "title": "Not found", "status": 404, "code": "not_found", "detail": "No such team.", "request_id": "6f1c2a…" } ``` * `code` is stable; switch on it. The list of codes may grow. * `type` links to the code's entry on this page. * `request_id` identifies the request. Quote it when you contact support. It is also in the `Request-Id` response header. * Some codes add fields: `permission`, `reason`, `errors`, `limit_scope`, `retry_after`. ## Codes [#codes] ### invalid_request [#invalid_request] `400`. A query parameter, header or body is malformed or unknown. `errors[]` names each field and why, for example `{ "field": "bogus", "code": "unknown_parameter" }`. An unknown name longer than 64 characters is cut to 64, ending in `…`, in `errors[].field` and in `detail`. Fix the request; retrying it unchanged fails again. ### invalid_credentials [#invalid_credentials] `401`. The key is missing, malformed, unknown, revoked, expired, switched off for being unused, past its roll date, or for the other environment. The answer is the same for every case on purpose. Check the key in HQ. ### permission_denied [#permission_denied] `403`. The key does not hold the permission the request needs, or its person or role no longer can. `permission` names it. Add the scope (create a new key) or ask an owner for the access. A key restricted to some AI teams gets this on `GET /audit_events`: the audit log covers the whole organization, so it needs a key for all teams. An [agency key](/docs/api/agency-keys/) also gets `reason`: `delegation_ceiling` when no agency key can ever do this in a client (a secret value, a keystroke in a session, a schedule change, …), or when the key is not linked to that client; `agency_access_level` when the client's access level for its provider does not include it. Without `reason`, the key itself was not created with that scope. When the key has the scope but the person it acts as (or, for a service key, its role) does not have the permission, `reason` is `holder_permission`: the key is fine, and the fix is the person's access, not a new key. Ask an owner or admin to change their role. ### protected_path [#protected_path] `403`. The AI team protects this file (its owners turned on Protected files), and the key, or the person it acts as, may not open or change it. A key needs the `files:protected.read` scope to open protected files and `files:protected.write` to change them, and its person needs the same permissions on the team. `detail` says which. Listings show such a file or folder as one entry with `protected: true`. Ask an owner of the team for access. ### ip_not_allowed [#ip_not_allowed] `403`. The key has an IP allowlist and this request came from outside it. ### two_factor_required [#two_factor_required] `403`. Your organization requires two-factor authentication, and the person this key acts as has not turned it on. They turn it on in HQ, and the same key works again. Service keys are not affected. ### third_party_apps_disabled [#third_party_apps_disabled] `403`. An [OAuth app](/docs/api/oauth/)'s token, in an organization whose owners or admins turned third-party apps off. The app works again when they turn them back on in **Settings**, **Developers**. API keys, and apps the organization registered itself, are not affected. ### plan_required [#plan_required] `403`. Your organization's plan does not include the API right now, or its subscription has ended. ### client_access_disabled [#client_access_disabled] `403`. An [agency key](/docs/api/agency-keys/) named a client that has turned its provider's access off. Only the client's owner can turn it back on. ### agency_suspended [#agency_suspended] `403`. An [agency key](/docs/api/agency-keys/)'s agency account is not active (suspended, or more than 3 days past due), so its keys cannot act for its clients. Also every change to a client whose provider's account was suspended: the client can still read its data. ### org_suspended [#org_suspended] `403`. HQ Support has suspended changes to your organization. Every request that changes something gets this; reading still works, and a key can still revoke itself. Contact support to restore changes. ### not_found [#not_found] `404`. The object does not exist, belongs to another organization, is outside the key's AI teams, or the id has the wrong prefix (a `team_` id where a `sess_` id belongs). These cases are indistinguishable on purpose. ### team_restricted [#team_restricted] `403`. The key is restricted to some AI teams, and the request would change something that reaches the whole organization: an org-wide secret or variable, an invitation, a new AI team, a webhook endpoint. Use a key for all teams. (Within its teams the same key works: a secret shared only with them, for example.) ### session_not_owned [#session_not_owned] `403`. The session runs on a person's own Claude account, and only that person's own user key may type into it. See [Sessions and prompts](/docs/api/sessions-and-prompts/). ### agent_config_protected [#agent_config_protected] `403`. A service key cannot change the AI team's agent configuration at the root of its files: `.claude/`, `.codex/`, `CLAUDE.md`, `AGENTS.md`, `CLAUDE.local.md`, `AGENTS.override.md` and `.mcp.json`, nor reach them through a linked folder. Use the user key of the person making the change. ### personal_login_not_available [#personal_login_not_available] `422`. The request needs a person (a session on their own Claude account, a schedule that runs as them), and a service key has none. Use a user key. ### operation_conflict [#operation_conflict] `409`. The AI team already has an operation in progress; `operation` names it. Wait for it, then retry. The machine being changed from HQ (an update or a resize) answers the same, without `operation`. See [Operations](/docs/api/operations/). ### computer_busy [#computer_busy] `409`. Sessions are running on the Cloud Computer. Send `force` (stop) or `restart` (update) to go ahead anyway. ### workspace_paused [#workspace_paused] `409`. The AI team is paused, so none of its sessions can start (a create with `start`, a start or a restart). A team paused after sustained heavy CPU use is cleared with `POST /teams/{team_id}/computer/unpause` (`compute:unpause`, org owners and admins). A hold placed by support or by your provider is lifted only by them; contact support. ### workspace_updating [#workspace_updating] `409`. The AI team's Cloud Computer is being updated or resized, so none of its sessions can start (a create with `start`, a start or a restart). Retry once it finishes; `GET /teams/{team_id}/computer` shows its state. ### machine_busy [#machine_busy] `409`. The AI team has a free session slot, but its Cloud Computer is too busy for another session: its memory is at 80% or more, or its processor has been working at full capacity for a while. Nothing starts (a create with `start`, a start or a restart; a create leaves the session stopped). Stop a session you no longer need, or move the team to a bigger size, then retry. Running a schedule now answers the same. ### protected_files_shell [#protected_files_shell] `403`. The AI team protects its files, and the key, or the person it acts as, may not open AND change them, so it cannot run Codex on the team: creating, starting or restarting a Codex session, or creating, changing, enabling or running a Codex schedule. A shell can read and change any file, and Codex runs commands. Claude sessions are not affected. Ask an owner of the team for access. Running a schedule now answers `409` with this code instead when the key may run it but the person the schedule runs as may not: the run is skipped, nothing starts. ### runner_needs_update [#runner_needs_update] `409`. The AI team protects its files, and its Cloud Computer runs an image too old to enforce that, so a key that may not open protected files is refused every file on the team until the computer is updated. An owner updates it in HQ. Keys that may open protected files are not affected. ### engine_unavailable [#engine_unavailable] `409`. This session's conversation cannot be followed over the API right now (for example, its engine is not available on the API yet). ### idempotency_in_progress [#idempotency_in_progress] `409`. A request with the same `Idempotency-Key` is still running. Wait `Retry-After` seconds and retry with the same key. See [Idempotency](/docs/api/idempotency/). ### idempotency_key_reused [#idempotency_key_reused] `422`. This `Idempotency-Key` was already used for a different request. Use a new key. ### misdirected [#misdirected] `421`. The request reached the wrong server. Retry it once, with the same `Idempotency-Key`. ### too_many_streams [#too_many_streams] `429`. The session or the organization has as many open event streams as it may. Close one first. ### not_configured [#not_configured] `503`. This API is not fully set up on our side. Retry later. ### payload_too_large [#payload_too_large] `413`. The request body is too large. ### validation_failed [#validation_failed] `422`. The request was well formed but its values were refused. ### rate_limited [#rate_limited] `429`. Too many requests for the key (`limit_scope: "credential"`) or the organization (`limit_scope: "org"`), or too many invalid keys from your address (`limit_scope: "ip"`). Wait `retry_after` seconds (also in the `Retry-After` header) and retry. See [Rate limits](/docs/api/rate-limits/). ### internal [#internal] `500`. Something went wrong on our side. Retry with backoff, and quote the `request_id` if it persists. ### upstream_unavailable [#upstream_unavailable] `502` or `503`. A part of HQ the request needed did not answer. Retry with backoff. --- # Idempotency URL: /docs/api/idempotency Retry a write safely with an Idempotency-Key, and know when a key is required. A network error leaves you not knowing whether a write happened. Send an `Idempotency-Key` header with any `POST`, `PUT`, `PATCH` or `DELETE`, and a retry with the same key and the same body gets the first answer back instead of doing the work twice. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_…/messages \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "Idempotency-Key: 6c1f2b0e-run-42" \ -H "Content-Type: application/json" \ -d '{"content":[{"type":"text","text":"Summarise the open pull requests"}]}' ``` * Use a new key for each new action, for example a UUID. Up to 255 printable ASCII characters. * A key belongs to the key that sent it and lasts 24 hours. * A replayed answer carries `Idempotent-Replayed: true`, the same status and body, and the same `Location` header for a create. A retried `DELETE` answers its first `204` again, even though the object is gone. * The same key with a different request (another body, query, path or route) is refused: `422 idempotency_key_reused`. * While the first request is still running, a retry is refused with `409 idempotency_in_progress` and `Retry-After`. Wait, then retry with the same key. * Answers that say "try again" are not stored, so a retry runs for real: `409` conflicts, `421` misdirected, `429` rate limits and `5xx` errors. ## Where a key is required [#where-a-key-is-required] These writes start something you cannot take back, so they refuse a request without a key (`400 invalid_request`, field `Idempotency-Key`): | Request | Why | | ------------------------------------------------------------------ | ------------------------------------------------------- | | `POST /teams/{team_id}/sessions` | Starts a session. | | `POST /sessions/{session_id}/messages` | Types into the session. A prompt is typed at most once. | | `POST /sessions/{session_id}/actions` | Answers a question or a permission request. | | `POST /teams/{team_id}/computer/start`, `stop`, `update`, `resize` | Changes the machine. | | `POST /schedules/{schedule_id}/runs` | Runs a schedule now. | Everywhere else the key is optional and works the same way. ## A secret is never replayed [#a-secret-is-never-replayed] `POST /secrets` and the other secret writes store their answer for replay like any other write. The answer never contains the secret's value, so the stored copy does not either. What is stored about the request itself is a keyed digest, never the value or a plain hash of it. A webhook endpoint's signing secret is shown once, in the answer to `POST /webhook_endpoints` and `POST /webhook_endpoints/{webhook_endpoint_id}/rotate_secret`, and it is not stored for a replay. A retry with the same key answers the same endpoint without `secret` and with `secret_omitted: true`. If you lost the first answer, roll the secret to get a new one. --- # HQ API overview URL: /docs/api 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/). --- # OAuth apps URL: /docs/api/oauth Let your product act for a person in HQ with their consent. Authorization code with PKCE, refresh rotation, revocation and what an app can never do. An **OAuth app** lets other software act for one person in HQ, in the one organization they pick, after they approve it. Use it when your product is used by people in organizations other than yours. For your own automation, use an [API key](/docs/api/authentication/) instead. An app never does more than the person who approved it can do there. On top of that, an app can **never**: * send a prompt, answer a question card or interrupt, in any session; * create a session, or write or run a schedule (a schedule's run is a prompt); * use anyone's personal Claude or ChatGPT login; * read the organization's API keys or manage its webhooks. ## Register an app [#register-an-app] In HQ, open **Settings**, then **Developers**, then **OAuth apps**, and choose **Register app** (owners and admins, on the Growth plan and up). Give it: * a **name** people see on the approval page; * a **type**: **Confidential** for a server that can keep a client secret, or **Public** for a browser or desktop app that cannot (it relies on PKCE alone); * its **redirect URIs**: `https` URLs, or `http://127.0.0.1` or `http://[::1]` for an app on the same computer. They are matched **exactly**: a trailing slash, a different path or an extra query is a different URI. The one exception is the port of a `127.0.0.1` or `[::1]` URI, which may be any port, so a desktop app can listen wherever it finds a free one; * the **permissions** it may ask for. You get a **client id** (`hq_app_…`, public) and, for a confidential app, a **client secret** (`hq_ocs_…`), shown **once**. Roll the secret any time with an overlap of up to 7 days. Deleting an app removes it from every organization that approved it: every approval and every token of it stops at once, and its client id and secrets stop working. Each of those organizations sees the removal in its audit log. ## Let members approve apps [#let-members-approve-apps] Third-party apps are **off** in every organization until an owner or admin turns on **Let members allow third-party apps** in **Settings**, **Developers**. Apps your own organization registered always work. Turning it off stops every other organization's app at once, and they work again when it is turned back on. Owners and admins see every member's apps there and can remove any of them. Each person sees their own under **Profile**, **Apps**. ## The flow [#the-flow] ### 1. Send the person to HQ [#1-send-the-person-to-hq] Make a PKCE pair: a random `code_verifier` (43 to 128 characters) and its `code_challenge = BASE64URL(SHA256(code_verifier))`. Then redirect the browser to: ```text https://hq.aiworkforceone.com/oauth/authorize ?response_type=code &client_id=hq_app_… &redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback &scope=teams%3Aread%20sessions%3Aread%20sessions%3Achat.read &state=… &code_challenge=… &code_challenge_method=S256 ``` `state` is required (check it when the person comes back), and only `S256` is accepted. The person signs in if needed, picks **one** organization, sees what the app will be able to do in plain words, and chooses **Allow access** or **Deny**. ### 2. Handle the callback [#2-handle-the-callback] HQ redirects to your `redirect_uri` with `code`, your `state` and `iss=https://api-hq.aiworkforceone.com` (check `iss` too). On **Deny** it sends `error=access_denied`. A request HQ could not accept comes back as `error=invalid_request`, `invalid_scope` or `unsupported_response_type`. An unknown client or an unregistered redirect URI never redirects anywhere. ### 3. Exchange the code [#3-exchange-the-code] The code lives **60 seconds** and works **once**. ```bash curl -X POST https://api-hq.aiworkforceone.com/oauth/token \ -u "hq_app_…:$HQ_CLIENT_SECRET" \ -d grant_type=authorization_code \ -d code=hq_oac_… \ -d redirect_uri=https://example.com/oauth/callback \ -d code_verifier=… ``` A public app sends `client_id=hq_app_…` in the body instead of `-u`. The answer: ```json { "access_token": "hq_oat_acme_…", "token_type": "Bearer", "expires_in": 900, "refresh_token": "hq_ort_acme_…", "scope": "teams:read sessions:read sessions:chat.read" } ``` ### 4. Call the API [#4-call-the-api] Use the access token exactly like an API key: ```bash curl https://api-hq.aiworkforceone.com/v1/me -H "Authorization: Bearer $HQ_ACCESS_TOKEN" ``` `GET /v1/me` answers `kind: "oauth"`, the app, the organization the person picked and the scopes. Access tokens last **15 minutes**. ### 5. Refresh [#5-refresh] ```bash curl -X POST https://api-hq.aiworkforceone.com/oauth/token \ -u "hq_app_…:$HQ_CLIENT_SECRET" \ -d grant_type=refresh_token \ -d refresh_token=hq_ort_acme_… ``` Every refresh returns a **new** refresh token; the old one is used up. You may pass a narrower `scope`, never a wider one. A refresh token unused for 30 days stops working. **Never use a refresh token twice.** HQ treats a used refresh token (or a code that already got tokens) presented again as stolen: it revokes the whole chain of tokens **and** the approval, and the person has to approve the app again. Store the new refresh token before you use the new access token. A code whose exchange was refused (a wrong verifier, say) is simply used up: presenting it again is `invalid_grant`, and the approval stays. ### Revoke [#revoke] ```bash curl -X POST https://api-hq.aiworkforceone.com/oauth/revoke \ -u "hq_app_…:$HQ_CLIENT_SECRET" \ -d token=hq_ort_acme_… ``` Revoking either token ends the whole chain. The answer is always `200`, even for an unknown token. ## Discovery [#discovery] `GET https://api-hq.aiworkforceone.com/.well-known/oauth-authorization-server` publishes the endpoints, `S256`, the client authentication methods and every scope an app may ask for (RFC 8414). ## Errors [#errors] The token and revoke endpoints answer the OAuth error shape, `{ "error", "error_description" }`: | `error` | When | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `invalid_client` | Wrong or missing client credentials, a secret sent for a public app, or a turned-off app (`401` with HTTP Basic) | | `invalid_grant` | The code or refresh token is wrong, expired, used, revoked, or for another app; the verifier or the redirect URI does not match; or the person is no longer a member | | `invalid_scope` | A refresh asked for more than the token had | | `invalid_request` | A parameter is missing, or the body is not a form | | `unsupported_grant_type` | Anything but `authorization_code` or `refresh_token` | | `slow_down` (`429`) | Too many refused requests from your address or for your client id, or too many revocations for your client. Wait the `Retry-After` seconds | On `/v1`, a token whose organization turned third-party apps off gets [`third_party_apps_disabled`](/docs/api/errors/#third_party_apps_disabled); everything else is the same as for a key, starting with [`invalid_credentials`](/docs/api/errors/#invalid_credentials). --- # Operations URL: /docs/api/operations Follow a Cloud Computer start, stop, update or resize until it finishes. Starting, stopping, updating or resizing an AI team's Cloud Computer takes from seconds to minutes. These requests answer `202 Accepted` with an **operation**, and you poll it until it is done. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_…/computer/start \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` ```json { "object": "operation", "id": "op_…", "kind": "computer.start", "status": "running", "target": { "type": "team", "id": "team_…" }, "requested": {}, "error": null, "created_by": { "kind": "user_key", "key": "key_…", "label": "jean@example.com" }, "created_at": "2026-11-02T09:00:00Z", "updated_at": "2026-11-02T09:00:00Z", "completed_at": null } ``` Then `GET /v1/operations/{operation_id}`. While it runs, the answer carries `Retry-After: 5`: poll no faster than that. | `status` | Meaning | | ------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `queued`, `running` | Still going. | | `succeeded` | Done: the machine is running (start), stopped (stop), on the current system software (update) or on the new size (resize). | | `failed` | `error.code` and `error.message` say why, for example `timeout` (it did not finish within 30 minutes). | | `canceled` | Something else replaced it. | `GET /v1/operations` lists the operations of the AI teams your key can see, newest first. An operation is kept for 30 days. ## One at a time per AI team [#one-at-a-time-per-ai-team] A team runs one operation at a time. Asking for another while one runs is refused with `409 operation_conflict`, and `operation` names the one in progress so you can wait for it. The same `409 operation_conflict` answers while the machine is being changed from HQ (an update or a resize someone started there, or a scheduled update); then there is no `operation` to name, so retry after a minute. A request that is refused (a permission, no Boost slot to assign, a conflict) creates no operation and sends no `operation.failed` webhook. ## Nothing to do [#nothing-to-do] A start on a machine that is already running, or a resize to the size it already has, answers `200` with the Cloud Computer and no operation. So does an update that has nothing to start now (the machine is current, or it is stopped and boots the current system software at its next start); `update_available` on the Cloud Computer says whether an update is still pending. ## Resizing to a smaller tier [#resizing-to-a-smaller-tier] Moving a running machine to a smaller tier does not interrupt it: the new size applies at its next restart, as in HQ. The resize answers `200` with the Cloud Computer, `tier` set to the new tier and `change_pending: true`, and no operation. To apply it now, send `POST /v1/teams/{team_id}/computer/update` with `{"restart": true}`. A stopped machine gets the new size when it next starts. ## Stop and update refuse while sessions run [#stop-and-update-refuse-while-sessions-run] `stop` and `update` refuse with `409 computer_busy` while sessions are running on the machine. Send `{"force": true}` (stop) or `{"restart": true}` (update) to go ahead and stop them. ## Who may [#who-may] | Request | Permission | | ------------------------------------- | ----------------- | | Start a sleeping machine | `compute:wake` | | Start a stopped machine, stop, update | `compute:rebuild` | | Resize | `compute:resize` | | Unpause | `compute:unpause` | | Read operations | `compute:read` | --- # Pagination URL: /docs/api/pagination Cursor pagination with limit, starting_after and ending_before. Every list returns newest first, in this envelope: ```json { "object": "list", "data": [ { "object": "team", "id": "team_…" } ], "has_more": true } ``` ## Parameters [#parameters] | Parameter | What it does | | ---------------- | ------------------------------------------------------------------------- | | `limit` | How many objects to return, 1 to 100. Default 20. | | `starting_after` | An object id from the previous page: return the objects after it (older). | | `ending_before` | An object id: return the objects before it (newer). | Use one cursor at a time. Pages are positioned by each object's creation time and id, so objects created or deleted between two calls never make a page skip or repeat anything. ## Reading every page [#reading-every-page] ```bash curl "https://api-hq.aiworkforceone.com/v1/teams?limit=100" -H "Authorization: Bearer $HQ_API_KEY" # then, while has_more is true: curl "https://api-hq.aiworkforceone.com/v1/teams?limit=100&starting_after=team_LAST_ID" \ -H "Authorization: Bearer $HQ_API_KEY" ``` ## Filters [#filters] Some lists take filters, for example `GET /v1/sessions?team=team_…&status=running` or `GET /v1/audit_events?created[gte]=2026-11-01T00:00:00Z`. Each endpoint lists its filters in the [reference](/docs/api/reference/). A parameter a list does not know is an error, not ignored: `400 invalid_request`, with `errors[0].field` naming it. A typo can never silently return a wider list. A `created[gte]` or `created[lte]` value must be an RFC 3339 timestamp with a year from 0001 to 9999\. Anything else, year 0000 included, is `400 invalid_request` with `errors[0].code` `invalid_value` and `errors[0].field` naming the parameter, for example `created[lte]`. ## Lists that page forward only [#lists-that-page-forward-only] The audit log, schedule runs and invoices take `starting_after` only. --- # API quickstart URL: /docs/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] ```bash curl https://api-hq.aiworkforceone.com/v1/me \ -H "Authorization: Bearer $HQ_API_KEY" ``` ```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()); ``` ```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()) ``` 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] ```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" ``` ```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'); } ``` ```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") ``` 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. ```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"}]}' ``` ```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", ... } ``` ```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", ...} ``` 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**. --- # Rate limits URL: /docs/api/rate-limits Requests per minute per key and per organization, and the headers that report them. Each key has a budget of requests per minute, and so does its organization across all its keys. The budget refills continuously. These numbers are provisional while the API is new, and may change. The `RateLimit-Policy` header on every response always states the budget that applies to your key, so read it rather than hard-coding the table. | Plan | Per key, per minute | Per organization, per minute | | ---------- | ------------------- | ---------------------------- | | Trial | 60 | 60 | | Solo | 120 | 240 | | Starter | 300 | 600 | | Growth | 600 | 1,200 | | Scale | 1,200 | 3,000 | | Enterprise | 2,400 | 6,000 | During the trial, keys can only read and an organization can hold one key. ## Costly requests [#costly-requests] A few requests also spend from a smaller budget of their own, because each one starts real work. These are provisional too. | Plan | Sessions created per minute (organization) | Cloud Computer operations per 10 minutes (AI team) | Invitations per day (organization) | Open event streams (organization) | | ---------- | ------------------------------------------ | -------------------------------------------------- | ---------------------------------- | --------------------------------- | | Trial | 0 | 0 | 0 | 2 | | Solo | 5 | 6 | 10 | 5 | | Starter | 10 | 6 | 20 | 10 | | Growth | 20 | 6 | 50 | 20 | | Scale | 40 | 12 | 100 | 50 | | Enterprise | 80 | 24 | 200 | 100 | Over one of these, the answer is `429 rate_limited` with `limit_scope` naming the budget (`session_create`, `computer_op` or `invite`) and `retry_after`. Too many open streams is `429 too_many_streams`. A session also takes at most 4 streams at once. ## Headers [#headers] Every response reports the key's budget: ``` RateLimit-Policy: "credential";q=300;w=60, "org";q=600;w=60 RateLimit: "credential";r=297;t=1 ``` `q` is the budget, `w` the window in seconds, `r` what is left and `t` the seconds until the budget is full again. ## Over the limit [#over-the-limit] An [agency key](/docs/api/agency-keys/) has its own budgets: 600 requests a minute per key on each API server (the cap is per server, so the total across servers can be higher), and a separate budget for your agency in each client, the size of that client's organization budget. Agency traffic never spends the client's own budget. Over the client budget, `limit_scope` is `agency_client`. The answer is `429 rate_limited` with `limit_scope` (`credential`, `org` or `agency_client`), `retry_after` and a `Retry-After` header. Wait that long, then retry. Back off further if it happens again. An address that keeps sending invalid keys is refused for a while before its keys are even checked: `429 rate_limited` with `limit_scope: "ip"`. During that wait a valid key from the same address is refused too, so fix the bad key first. Our edge also limits requests per IP address. Those refusals can arrive without a problem document, so treat every `429` as "wait and retry". --- # API keys URL: /docs/api/reference/api-keys The keys of your organization. Read only; create, roll and revoke keys in HQ. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} ## List API keys [#list-api-keys] Every key of the organization, newest first. Metadata only, never a secret. How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). Only active or only revoked keys. One of `active`, `revoked`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [ApiKey](#apikey) objects. A page of keys. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/api_keys \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/api_keys', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/api_keys", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "api_key", "id": "key_ff7QejQ24AGmu5tv2IXIdw", "name": "CI deploy bot", "kind": "service_key", "prefix": "hq_live_acme_7Gm2", "last4": "Lk2Q", "acting_user": null, "role": "sys:member", "scopes": ["teams:read", "sessions:read"], "team_scope": "all", "teams": null, "ip_allowlist": ["203.0.113.0/24"], "api_version": "2026-11-01", "status": "active", "created_at": "2026-10-01T09:12:44.000Z", "created_by": "user_yFfQdB3rxA41x3cTD5fx2Q", "expires_at": "2027-10-01T09:12:44.000Z", "last_used_at": "2026-10-14T16:02:11.000Z", "last_used_ip": "203.0.113.24", "revoked_at": null, "revoked_reason": null, "rotated_from": null, "rotation_grace_until": null } ], "has_more": false } ``` ## Revoke the calling key [#revoke-the-calling-key] The key making this request revokes itself, at once. Use it the moment a key leaks. Any key may call it; nothing else about keys can be changed through the API. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Revoked. The next request with this key gets 401. An RFC 9457 problem. ```bash curl -X DELETE https://api-hq.aiworkforceone.com/v1/api_keys/current \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/api_keys/current', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(res.status); ``` ```python import os import requests res = requests.delete( "https://api-hq.aiworkforceone.com/v1/api_keys/current", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.status_code) ``` Revoked. The next request with this key gets 401. ## Get an API key [#get-an-api-key] An API key id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [ApiKey](#apikey) object. The key. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/api_keys/key_ff7QejQ24AGmu5tv2IXIdw \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/api_keys/key_ff7QejQ24AGmu5tv2IXIdw', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/api_keys/key_ff7QejQ24AGmu5tv2IXIdw", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "api_key", "id": "key_ff7QejQ24AGmu5tv2IXIdw", "name": "CI deploy bot", "kind": "service_key", "prefix": "hq_live_acme_7Gm2", "last4": "Lk2Q", "acting_user": null, "role": "sys:member", "scopes": ["teams:read", "sessions:read"], "team_scope": "all", "teams": null, "ip_allowlist": ["203.0.113.0/24"], "api_version": "2026-11-01", "status": "active", "created_at": "2026-10-01T09:12:44.000Z", "created_by": "user_yFfQdB3rxA41x3cTD5fx2Q", "expires_at": "2027-10-01T09:12:44.000Z", "last_used_at": "2026-10-14T16:02:11.000Z", "last_used_ip": "203.0.113.24", "revoked_at": null, "revoked_reason": null, "rotated_from": null, "rotation_grace_until": null } ``` ## Objects [#objects] ### ApiKey [#apikey] An API key. Never carries the key itself. Open-ended; more credential kinds may be added. The first characters of the key, for recognising it. One of `all`, `selected`. Null when the key has none, and always null unless the caller is an owner or admin key for all teams. Open-ended: active, expiring_rotation, revoked, expired. Always null unless the caller is an owner or admin key for all teams. ```json title="The ApiKey object" { "object": "api_key", "id": "key_ff7QejQ24AGmu5tv2IXIdw", "name": "CI deploy bot", "kind": "service_key", "prefix": "hq_live_acme_7Gm2", "last4": "Lk2Q", "acting_user": null, "role": "sys:member", "scopes": ["teams:read", "sessions:read"], "team_scope": "all", "teams": null, "ip_allowlist": ["203.0.113.0/24"], "api_version": "2026-11-01", "status": "active", "created_at": "2026-10-01T09:12:44.000Z", "created_by": "user_yFfQdB3rxA41x3cTD5fx2Q", "expires_at": "2027-10-01T09:12:44.000Z", "last_used_at": "2026-10-14T16:02:11.000Z", "last_used_ip": "203.0.113.24", "revoked_at": null, "revoked_reason": null, "rotated_from": null, "rotation_grace_until": null } ``` --- # Audit log URL: /docs/api/reference/audit The organization's audit log. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} ## List audit events [#list-audit-events] Newest first, within your plan's audit retention. Pages forward with `starting_after`. Reading the audit log through the API is itself recorded in the audit log. On an AI team that turned on Protected files, a key that lacks `files:protected.read` (or whose person lacks it) gets `protected` in place of every AI Employee or skill name in that team's events: an AI Employee key in `details`, and on an event that names a file under `.claude/agents` or `.claude/skills`, every path in it (`resource_id` and the paths in `details`). An event with no team is treated this way when any team hides its AI Employees from the key. How many objects to return, 1 to 100. Default 20. Return events older than this audit event id. Only events with this action, for example `api_key.created`. Only events by this email address. Only events at or after this time. Only events at or before this time. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [AuditEvent](#auditevent) objects. A page of audit events. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/audit_events \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/audit_events', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/audit_events", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "audit_event", "id": "aud_eyJ0cyI6IjIwMjYtMTAtMTRUMTY6MDI6MTEuMzE4WiIsImlkIjoiOGM0ZjJhMTktNWQzZS00YjdhLTlmNjEtMmUwYzdkNWEzYjg0In0", "action": "api_key.created", "actor": { "email": "maya.chen@example.com", "name": "Maya Chen" }, "resource_type": "api_key", "resource_id": "key_ff7QejQ24AGmu5tv2IXIdw", "team": null, "details": { "name": "CI deploy bot", "scopes": ["teams:read", "sessions:read"] }, "ip_address": "203.0.113.24", "created_at": "2026-10-14T16:02:11.318Z" } ], "has_more": false, "retention_days": 90 } ``` ## Objects [#objects] ### AuditEvent [#auditevent] ```json title="The AuditEvent object" { "object": "audit_event", "id": "aud_eyJ0cyI6IjIwMjYtMTAtMTRUMTY6MDI6MTEuMzE4WiIsImlkIjoiOGM0ZjJhMTktNWQzZS00YjdhLTlmNjEtMmUwYzdkNWEzYjg0In0", "action": "api_key.created", "actor": { "email": "maya.chen@example.com", "name": "Maya Chen" }, "resource_type": "api_key", "resource_id": "key_ff7QejQ24AGmu5tv2IXIdw", "team": null, "details": { "name": "CI deploy bot", "scopes": ["teams:read", "sessions:read"] }, "ip_address": "203.0.113.24", "created_at": "2026-10-14T16:02:11.318Z" } ``` --- # Billing URL: /docs/api/reference/billing Your plan, this period's usage and your invoices. Read only. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} ## Get this period's usage [#get-this-periods-usage] Running minutes, data transfer and storage, per AI team, for the current period. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Usage](#usage) object. The usage. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/usage \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/usage', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/usage", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "usage", "period": { "start": "2026-10-01T00:00:00.000Z", "end": "2026-11-01T00:00:00.000Z" }, "measured_at": "2026-10-15T06:00:00.000Z", "egress": { "used_gb": 12.4, "allowance_gb": 100, "over_allowance": false, "throttled": false }, "storage": { "provisioned_gb": 50, "limit_gb": 200 }, "teams": [ { "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Research", "running_minutes": 8640, "egress_gb": 12.4, "storage_gb": 20 } ], "totals": { "running_minutes": 8640, "egress_gb": 12.4, "storage_gb": 20 } } ``` ## Get your subscription [#get-your-subscription] A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Subscription](#subscription) object. The subscription. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/billing/subscription \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/billing/subscription', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/billing/subscription", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "subscription", "plan": "growth", "status": "active", "trial_ends_at": null, "current_period_end": "2026-11-28T00:00:00.000Z", "cancel_at_period_end": false } ``` ## List invoices [#list-invoices] Newest first. Pages forward with `starting_after` (an invoice id). Download links are not included: open invoices from Billing in HQ. How many objects to return, 1 to 100. Default 20. Return invoices older than this invoice id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [Invoice](#invoice) objects. A page of invoices. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/billing/invoices \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/billing/invoices', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/billing/invoices", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "invoice", "id": "in_1QzX8mK2eZvKYlo2C3tB9fRw", "number": "ACME-0012", "status": "paid", "amount_due": 49700, "amount_paid": 49700, "currency": "usd", "description": null, "period_start": "2026-09-28T00:00:00.000Z", "period_end": "2026-10-28T00:00:00.000Z", "created_at": "2026-09-28T00:04:12.000Z" } ], "has_more": false } ``` ## Objects [#objects] ### Usage [#usage] ```json title="The Usage object" { "object": "usage", "period": { "start": "2026-10-01T00:00:00.000Z", "end": "2026-11-01T00:00:00.000Z" }, "measured_at": "2026-10-15T06:00:00.000Z", "egress": { "used_gb": 12.4, "allowance_gb": 100, "over_allowance": false, "throttled": false }, "storage": { "provisioned_gb": 50, "limit_gb": 200 }, "teams": [ { "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Research", "running_minutes": 8640, "egress_gb": 12.4, "storage_gb": 20 } ], "totals": { "running_minutes": 8640, "egress_gb": 12.4, "storage_gb": 20 } } ``` ### Subscription [#subscription] ```json title="The Subscription object" { "object": "subscription", "plan": "growth", "status": "active", "trial_ends_at": null, "current_period_end": "2026-11-28T00:00:00.000Z", "cancel_at_period_end": false } ``` ### Invoice [#invoice] In the smallest currency unit. ```json title="The Invoice object" { "object": "invoice", "id": "in_1QzX8mK2eZvKYlo2C3tB9fRw", "number": "ACME-0012", "status": "paid", "amount_due": 49700, "amount_paid": 49700, "currency": "usd", "description": null, "period_start": "2026-09-28T00:00:00.000Z", "period_end": "2026-10-28T00:00:00.000Z", "created_at": "2026-09-28T00:04:12.000Z" } ``` --- # Cloud Computers URL: /docs/api/reference/cloud-computers The machine each AI team runs on. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} ## Get an AI team's Cloud Computer [#get-an-ai-teams-cloud-computer] Its size, power state, pause and update state. An AI team id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Computer](#computer) object. The Cloud Computer. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "computer", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "state": "running", "tier": "standard", "boost_source": null, "max_sessions": 4, "paused": false, "paused_at": null, "resize_state": "idle", "change_pending": false, "update_state": "idle", "update_available": false, "last_updated_at": "2026-10-12T03:15:40.000Z" } ``` ## Start the Cloud Computer [#start-the-cloud-computer] Wakes a sleeping machine (needs `compute:wake`), or starts a stopped one (also needs `compute:rebuild`). Returns an operation to follow, or the computer when it already runs. Requires an `Idempotency-Key`. An AI team id. Required here. The same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422; while the first request is still running, 409 `idempotency_in_progress`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Computer](#computer) object. Already running; nothing to do. Started. Follow the operation. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer/start \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer/start', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer/start", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.json()) ``` ```json title="Response 200" { "object": "computer", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "state": "running", "tier": "standard", "boost_source": null, "max_sessions": 4, "paused": false, "paused_at": null, "resize_state": "idle", "change_pending": false, "update_state": "idle", "update_available": false, "last_updated_at": "2026-10-12T03:15:40.000Z" } ``` ## Stop the Cloud Computer [#stop-the-cloud-computer] A full stop (not a sleep). The team's files stay. Refused with 409 `computer_busy` while a session runs, unless `force` is true. Requires an `Idempotency-Key`. An AI team id. Required here. The same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422; while the first request is still running, 409 `idempotency_in_progress`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Stop even while sessions run (they stop with it). **Returns** a [Computer](#computer) object. Not running; nothing to do. Stopping. Follow the operation. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer/stop \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"force":false}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer/stop', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ force: false }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer/stop", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"force": False}, ) print(res.json()) ``` ```json title="Response 200" { "object": "computer", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "state": "running", "tier": "standard", "boost_source": null, "max_sessions": 4, "paused": false, "paused_at": null, "resize_state": "idle", "change_pending": false, "update_state": "idle", "update_available": false, "last_updated_at": "2026-10-12T03:15:40.000Z" } ``` ## Update the Cloud Computer [#update-the-cloud-computer] Rebuilds the machine on the current system software, keeping every file. `restart: true` restarts it even when it is current, and is required while sessions run (409 `computer_busy` otherwise). While another operation, an update or a resize runs, the answer is 409 `operation_conflict`. Requires an `Idempotency-Key`. An AI team id. Required here. The same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422; while the first request is still running, 409 `idempotency_in_progress`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Restart even when the machine is current; needed while sessions run. **Returns** a [Computer](#computer) object. Nothing started. Already up to date, or nothing to update now (`update_available` says whether an update is pending). Updating. Follow the operation. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer/update \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"restart":true}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer/update', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ restart: true }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer/update", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"restart": True}, ) print(res.json()) ``` ```json title="Response 200" { "object": "computer", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "state": "running", "tier": "standard", "boost_source": null, "max_sessions": 4, "paused": false, "paused_at": null, "resize_state": "idle", "change_pending": false, "update_state": "idle", "update_available": false, "last_updated_at": "2026-10-12T03:15:40.000Z" } ``` ## Resize the Cloud Computer [#resize-the-cloud-computer] Moves the team to a Boost tier the organization owns a free slot of (409 when it has none), or back to standard. Requires an `Idempotency-Key`. A larger tier on a live machine is a `202` operation that succeeds once the machine runs the new size. A smaller tier on a running machine applies at its next restart, as in HQ: the answer is `200` with the computer, `change_pending: true`, and no operation; send `POST …/computer/update` with `restart: true` to apply it now. A stopped machine gets the new size at its next start (also `200`). While another operation, an update or a resize runs, the answer is 409 `operation_conflict`, with `operation` naming the blocking operation when it was started over the API. An AI team id. Required here. The same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422; while the first request is still running, 409 `idempotency_in_progress`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. One of `standard`, `boost`, `boost_pro`, `boost_max`. **Returns** a [Computer](#computer) object. Nothing to follow. Already on this tier, or the new tier is recorded and applies at the next restart or start (`change_pending`). Resizing. Follow the operation. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer/resize \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"tier":"standard"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer/resize', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ tier: 'standard' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer/resize", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"tier": "standard"}, ) print(res.json()) ``` ```json title="Response 200" { "object": "computer", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "state": "running", "tier": "standard", "boost_source": null, "max_sessions": 4, "paused": false, "paused_at": null, "resize_state": "idle", "change_pending": false, "update_state": "idle", "update_available": false, "last_updated_at": "2026-10-12T03:15:40.000Z" } ``` ## Unpause the Cloud Computer [#unpause-the-cloud-computer] Clears an abuse pause. The machine comes back with its next session or wake. An AI team id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Computer](#computer) object. The computer. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer/unpause \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer/unpause', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/computer/unpause", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.json()) ``` ```json title="Response 200" { "object": "computer", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "state": "running", "tier": "standard", "boost_source": null, "max_sessions": 4, "paused": false, "paused_at": null, "resize_state": "idle", "change_pending": false, "update_state": "idle", "update_available": false, "last_updated_at": "2026-10-12T03:15:40.000Z" } ``` ## Objects [#objects] ### Computer [#computer] Open-ended: running, starting, suspending, suspended, resuming, stopping, stopped, resizing, updating, error. True while the machine still has the size of an earlier tier. A move to a smaller tier on a running Cloud Computer applies at its next restart (send POST /v1/teams/\{team_id}/computer/update with restart: true to apply it now); a stopped one gets the new size at its next start. A sleeping one wakes on its current size; a bigger tier then applies once it is running, a smaller one at its next restart. ```json title="The Computer object" { "object": "computer", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "state": "running", "tier": "standard", "boost_source": null, "max_sessions": 4, "paused": false, "paused_at": null, "resize_state": "idle", "change_pending": false, "update_state": "idle", "update_available": false, "last_updated_at": "2026-10-12T03:15:40.000Z" } ``` --- # Essentials URL: /docs/api/reference/essentials Health, the contract itself, and the calling credential. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} ## Check the API is up [#check-the-api-is-up] No credential needed. `version` is the deployed build. **Returns** a [Health](#health) object. The API is serving. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/health ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/health'); console.log(await res.json()); ``` ```python import requests res = requests.get("https://api-hq.aiworkforceone.com/v1/health") print(res.json()) ``` ```json title="Response 200" { "ok": true, "version": "sha256:4f2a9c81d3b7e6052a1f8c4d9e3b7a6f0c2d5e8b1a4f7c9d2e6b3a8f1c5d7e90" } ``` ## Get this contract [#get-this-contract] The OpenAPI 3.1 document this server implements, as JSON. No credential needed. The OpenAPI document. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/openapi.json ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/openapi.json'); console.log(await res.json()); ``` ```python import requests res = requests.get("https://api-hq.aiworkforceone.com/v1/openapi.json") print(res.json()) ``` ```json title="Response 200" { "openapi": "3.1.0", "info": { "title": "AI Workforce One HQ API", "version": "2026-11-01" }, "servers": [ { "url": "https://api-hq.aiworkforceone.com/v1" } ], "paths": { "/health": {} } } ``` ## Describe the calling key [#describe-the-calling-key] The key making this request, its organization, scopes, version and expiry. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Credential](#credential) object. The calling credential. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/me \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/me', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/me", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "credential", "id": "key_ff7QejQ24AGmu5tv2IXIdw", "kind": "user_key", "name": "CI deploy bot", "org": { "id": "org_3SvwLF4ulih8bHz5KtmNOO", "slug": "acme" }, "acting_user": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "email": "maya.chen@example.com" }, "role": null, "scopes": ["teams:read", "sessions:read", "sessions:chat.read"], "team_scope": "all", "teams": null, "api_version": "2026-11-01", "expires_at": "2027-10-01T00:00:00.000Z" } ``` ## Objects [#objects] ### Health [#health] The deployed image digest. ```json title="The Health object" { "ok": true, "version": "sha256:4f2a9c81d3b7e6052a1f8c4d9e3b7a6f0c2d5e8b1a4f7c9d2e6b3a8f1c5d7e90" } ``` ### Credential [#credential] The key's id (`key_…`), or for an OAuth app the grant's (`grant_…`). Open-ended; more credential kinds may be added. The key's name, or the OAuth app's. Present for an OAuth app only. The organization this request acts in. For an agency key, the client named in HQ-Account. Present for an agency key only. The agency the key belongs to. The member a user key or an OAuth app acts as. Null for a service key or an agency key. A service key's role, or an agency key's (always sys:admin). One of `all`, `selected`. ```json title="The Credential object" { "object": "credential", "id": "key_ff7QejQ24AGmu5tv2IXIdw", "kind": "user_key", "name": "CI deploy bot", "org": { "id": "org_3SvwLF4ulih8bHz5KtmNOO", "slug": "acme" }, "acting_user": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "email": "maya.chen@example.com" }, "role": null, "scopes": ["teams:read", "sessions:read", "sessions:chat.read"], "team_scope": "all", "teams": null, "api_version": "2026-11-01", "expires_at": "2027-10-01T00:00:00.000Z" } ``` --- # Files URL: /docs/api/reference/files The files on an AI team's disk, addressed through one of its sessions. Paths are relative to the team's files; a path that leaves them is refused. Reads are masked like the terminal. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} ## List a folder [#list-a-folder] One folder's entries, paged with `cursor`. No `path` lists the team's root. On an AI team that turned on Protected files, a key that lacks `files:protected.read` (or whose person lacks it) sees each protected file or folder as one entry with `protected: true` and no size, and listing inside one is 403 protected_path. A session id. The folder's path, relative to the team's files. Omit for the root. The `next_cursor` of the previous page. Entries per page, 1 to 2000. Default 1000. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [FileListing](#filelisting) object. The folder's entries. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "session": "sess_0a843Y2wTmED2k3FJPP56X", "path": "reports", "data": [ { "object": "file_entry", "name": "weekly.md", "path": "reports/weekly.md", "type": "file", "size": 4182, "modified_at": "2026-10-12T07:06:40.000Z", "ignored": false, "linked": false, "protected": false } ], "has_more": false, "next_cursor": null, "truncated": false } ``` ## Create an empty file [#create-an-empty-file] Never replaces an existing file (409). Write its content with PUT /files/content. On an AI team that turned on Protected files, changing a protected path (or a folder that contains one) needs `files:protected.write` on the key and its person: 403 protected_path otherwise. A service key cannot change the agent configuration at the root (`.claude/`, `.codex/`, `CLAUDE.md`, `AGENTS.md`, `CLAUDE.local.md`, `AGENTS.override.md`, `.mcp.json`, or a linked folder reaching them): 403 agent_config_protected. A session id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [File](#file) object. The new file. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"path":"reports/q4-plan.md"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ path: 'reports/q4-plan.md' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"path": "reports/q4-plan.md"}, ) print(res.json()) ``` ```json title="Response 201" { "object": "file", "path": "reports/weekly.md", "size": 4182, "modified_at": "2026-10-12T07:06:40.000Z" } ``` ## Delete a file or a folder [#delete-a-file-or-a-folder] A folder is deleted with everything in it. Template-protected files cannot be deleted. On an AI team that turned on Protected files, changing a protected path (or a folder that contains one) needs `files:protected.write` on the key and its person: 403 protected_path otherwise. A service key cannot change the agent configuration at the root (`.claude/`, `.codex/`, `CLAUDE.md`, `AGENTS.md`, `CLAUDE.local.md`, `AGENTS.override.md`, `.mcp.json`, or a linked folder reaching them): 403 agent_config_protected. A session id. The file's path, relative to the team's files (`notes/plan.md`). Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Deleted. An RFC 9457 problem. ```bash curl -X DELETE "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files?path=reports%2Fweekly.md" \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files?path=reports%2Fweekly.md', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(res.status); ``` ```python import os import uuid import requests res = requests.delete( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files?path=reports%2Fweekly.md", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.status_code) ``` Deleted. ## Read a text file [#read-a-text-file] The file's text, with any of the team's secret values replaced by `[REDACTED]`, as in the terminal. A binary file is refused (415). On an AI team that turned on Protected files, a key that lacks `files:protected.read` (or whose person lacks it) is refused a protected file with 403 protected_path, also when the path is a link to it, and gets 409 runner_needs_update while the team's Cloud Computer runs an older image. A session id. The file's path, relative to the team's files (`notes/plan.md`). A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [FileContent](#filecontent) object. The file and its text. An RFC 9457 problem. ```bash curl "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files/content?path=reports%2Fweekly.md" \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files/content?path=reports%2Fweekly.md', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files/content?path=reports%2Fweekly.md", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "file", "path": "reports/weekly.md", "size": 4182, "modified_at": "2026-10-12T07:06:40.000Z", "encoding": "utf-8", "content": "# Weekly brief\n\n## Pricing\n\nThree competitors changed their pricing.\n" } ``` ## Write a text file [#write-a-text-file] Creates or replaces the file's text (at most 2 MB). Pass `base_modified_at` from your last read to be refused (409) if it changed since. Writing `[REDACTED]` back over a secret is refused. Template-protected files are read-only. On an AI team that turned on Protected files, changing a protected path (or a folder that contains one) needs `files:protected.write` on the key and its person: 403 protected_path otherwise. A service key cannot change the agent configuration at the root (`.claude/`, `.codex/`, `CLAUDE.md`, `AGENTS.md`, `CLAUDE.local.md`, `AGENTS.override.md`, `.mcp.json`, or a linked folder reaching them): 403 agent_config_protected. A session id. The file's path, relative to the team's files (`notes/plan.md`). Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. UTF-8 text, at most 2 MB. The `modified_at` you last read; a newer file is refused (409). **Returns** a [File](#file) object. The file as written. An RFC 9457 problem. ```bash curl -X PUT "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files/content?path=reports%2Fweekly.md" \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"content":"# Q4 plan\n\nShip the pricing page.\n"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files/content?path=reports%2Fweekly.md', { method: 'PUT', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ content: '# Q4 plan\n\nShip the pricing page.\n' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.put( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files/content?path=reports%2Fweekly.md", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"content": "# Q4 plan\n\nShip the pricing page.\n"}, ) print(res.json()) ``` ```json title="Response 200" { "object": "file", "path": "reports/weekly.md", "size": 4182, "modified_at": "2026-10-12T07:06:40.000Z" } ``` ## Objects [#objects] ### FileListing [#filelisting] ```json title="The FileListing object" { "object": "list", "session": "sess_0a843Y2wTmED2k3FJPP56X", "path": "reports", "data": [ { "object": "file_entry", "name": "weekly.md", "path": "reports/weekly.md", "type": "file", "size": 4182, "modified_at": "2026-10-12T07:06:40.000Z", "ignored": false, "linked": false, "protected": false } ], "has_more": false, "next_cursor": null, "truncated": false } ``` ### File [#file] ```json title="The File object" { "object": "file", "path": "reports/weekly.md", "size": 4182, "modified_at": "2026-10-12T07:06:40.000Z" } ``` ### FileContent [#filecontent] ```json title="The FileContent object" { "object": "file", "path": "reports/weekly.md", "size": 4182, "modified_at": "2026-10-12T07:06:40.000Z", "encoding": "utf-8", "content": "# Weekly brief\n\n## Pricing\n\nThree competitors changed their pricing.\n" } ``` --- # API reference URL: /docs/api/reference Every endpoint of the HQ API, grouped by resource. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} Every endpoint below is served under `https://api-hq.aiworkforceone.com/v1`. The machine-readable contract is at `GET /v1/openapi.json`. Each endpoint shows the permission it needs, its parameters, a request in cURL, JavaScript and Python, and an example response. Send your key as `Authorization: Bearer ` and pin a dated version with `HQ-Version`. | Resource | Endpoints | | ------------------------------------------------------- | --------- | | [Essentials](/docs/api/reference/essentials/) | 3 | | [API keys](/docs/api/reference/api-keys/) | 3 | | [Organization](/docs/api/reference/organization/) | 8 | | [AI teams](/docs/api/reference/teams/) | 10 | | [Cloud Computers](/docs/api/reference/cloud-computers/) | 6 | | [Operations](/docs/api/reference/operations/) | 2 | | [Sessions](/docs/api/reference/sessions/) | 16 | | [Files](/docs/api/reference/files/) | 5 | | [Schedules](/docs/api/reference/schedules/) | 11 | | [Secrets](/docs/api/reference/secrets/) | 13 | | [Variables](/docs/api/reference/variables/) | 10 | | [Templates](/docs/api/reference/templates/) | 2 | | [Billing](/docs/api/reference/billing/) | 3 | | [Audit log](/docs/api/reference/audit/) | 1 | | [Webhooks](/docs/api/reference/webhooks/) | 13 | --- # Operations URL: /docs/api/reference/operations Long-running changes to a Cloud Computer, and how they settled. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} ## List operations [#list-operations] Newest first, on the AI teams the key's holder can see. Kept 30 days. How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). Only operations on this AI team. Only operations in this state. One of `running`, `succeeded`, `failed`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [Operation](#operation) objects. A page of operations. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/operations \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/operations', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/operations", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "operation", "id": "op_pgDHKopuDeR6aX2GPYNtx5", "kind": "computer.resize", "status": "running", "target": { "type": "team", "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd" }, "requested": { "tier": "boost" }, "error": null, "created_by": { "kind": "service_key", "key": "key_ff7QejQ24AGmu5tv2IXIdw", "label": "CI deploy bot" }, "created_at": "2026-10-14T16:10:00.000Z", "updated_at": "2026-10-14T16:10:04.000Z", "completed_at": null } ], "has_more": false } ``` ## Get an operation [#get-an-operation] Poll until `status` is `succeeded` or `failed`; `Retry-After` says when to ask again. An operation id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Operation](#operation) object. The operation. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/operations/op_pgDHKopuDeR6aX2GPYNtx5 \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/operations/op_pgDHKopuDeR6aX2GPYNtx5', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/operations/op_pgDHKopuDeR6aX2GPYNtx5", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "operation", "id": "op_pgDHKopuDeR6aX2GPYNtx5", "kind": "computer.resize", "status": "running", "target": { "type": "team", "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd" }, "requested": { "tier": "boost" }, "error": null, "created_by": { "kind": "service_key", "key": "key_ff7QejQ24AGmu5tv2IXIdw", "label": "CI deploy bot" }, "created_at": "2026-10-14T16:10:00.000Z", "updated_at": "2026-10-14T16:10:04.000Z", "completed_at": null } ``` ## Objects [#objects] ### Operation [#operation] A change the reconcilers carry out. It settles as succeeded or failed. Open-ended: computer.start, computer.stop, computer.update, computer.resize, webhook_endpoint.replay. running, succeeded or failed. ```json title="The Operation object" { "object": "operation", "id": "op_pgDHKopuDeR6aX2GPYNtx5", "kind": "computer.resize", "status": "running", "target": { "type": "team", "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd" }, "requested": { "tier": "boost" }, "error": null, "created_by": { "kind": "service_key", "key": "key_ff7QejQ24AGmu5tv2IXIdw", "label": "CI deploy bot" }, "created_at": "2026-10-14T16:10:00.000Z", "updated_at": "2026-10-14T16:10:04.000Z", "completed_at": null } ``` --- # Organization URL: /docs/api/reference/organization Your organization, its people and its pending invitations. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} ## Get your organization [#get-your-organization] A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Org](#org) object. The organization. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/org \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/org', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/org", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "org", "id": "org_3SvwLF4ulih8bHz5KtmNOO", "name": "Acme Robotics", "slug": "acme", "plan": "growth", "plan_status": "active", "trial_ends_at": null, "current_period_end": "2026-11-28T00:00:00.000Z", "cancel_at_period_end": false, "created_at": "2026-03-04T11:20:00.000Z" } ``` ## Get the org chart [#get-the-org-chart] People, AI teams and who each team reports to. Emails only for an admin's key. On an AI team that turned on Protected files, a key that lacks `files:protected.read` (or whose person lacks it) gets `ai_employee_count` and `skill_count` as null for that team. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [OrgChart](#orgchart) object. The org chart. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/org/chart \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/org/chart', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/org/chart", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "org_chart", "owners": [ { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen", "email": "maya.chen@example.com", "title": "CTO" } ], "people": [ { "id": "user_82yssFqK4JG6pUfKfe95V3", "name": "Sam Okafor", "email": "sam.okafor@example.com", "title": "Platform lead", "role": "admin" } ], "pending_invites": [ { "id": "inv_osw5IZUY55lbPHG4sHWkxl", "email": "priya.patel@example.com", "role": "member", "title": "Data analyst" } ], "teams": [ { "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Research", "engine": "claude", "reports_to": [ { "user": "user_82yssFqK4JG6pUfKfe95V3", "role": "owner" } ], "ai_employee_count": 3, "skill_count": 12, "running_sessions": 2, "schedule_count": 4, "next_run_at": "2026-10-19T07:00:00.000Z" } ] } ``` ## List members [#list-members] How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). Only members with this role. One of `owner`, `admin`, `member`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [Member](#member) objects. A page of members. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/members \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/members', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/members", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "member", "id": "user_82yssFqK4JG6pUfKfe95V3", "name": "Sam Okafor", "email": "sam.okafor@example.com", "role": "admin", "title": "Platform lead", "two_factor_enabled": true, "joined_at": "2026-03-09T15:41:02.000Z", "last_login_at": "2026-10-14T08:03:57.000Z" } ], "has_more": false } ``` ## Get a member [#get-a-member] A member's user id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Member](#member) object. The member. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/members/user_82yssFqK4JG6pUfKfe95V3 \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/members/user_82yssFqK4JG6pUfKfe95V3', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/members/user_82yssFqK4JG6pUfKfe95V3", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "member", "id": "user_82yssFqK4JG6pUfKfe95V3", "name": "Sam Okafor", "email": "sam.okafor@example.com", "role": "admin", "title": "Platform lead", "two_factor_enabled": true, "joined_at": "2026-03-09T15:41:02.000Z", "last_login_at": "2026-10-14T08:03:57.000Z" } ``` ## List pending invitations [#list-pending-invitations] How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [Invite](#invite) objects. A page of invitations. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/invites \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/invites', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/invites", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "invite", "id": "inv_osw5IZUY55lbPHG4sHWkxl", "email": "priya.patel@example.com", "role": "member", "title": "Data analyst", "invited_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" }, "created_at": "2026-10-13T10:00:00.000Z", "expires_at": "2026-10-20T10:00:00.000Z" } ], "has_more": false } ``` ## Invite someone [#invite-someone] Emails an invitation to join as a member or an admin (never an owner). The plan's seat limit applies (Professional has none), and the API sends at most a daily number of invitations per organization. A key restricted to some AI teams cannot do this (403 team_restricted). Inviting an admin needs members:role.assign in the key's own grant, which no API key can hold, so invite admins in HQ (403). Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. One of `member`, `admin`. **Returns** a [Invite](#invite) object. The invitation. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/invites \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"email":"priya.patel@example.com"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/invites', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ email: 'priya.patel@example.com' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/invites", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"email": "priya.patel@example.com"}, ) print(res.json()) ``` ```json title="Response 201" { "object": "invite", "id": "inv_osw5IZUY55lbPHG4sHWkxl", "email": "priya.patel@example.com", "role": "member", "title": "Data analyst", "invited_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" }, "created_at": "2026-10-13T10:00:00.000Z", "expires_at": "2026-10-20T10:00:00.000Z" } ``` ## Revoke an invitation [#revoke-an-invitation] An invitation id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Revoked. Its link no longer works. An RFC 9457 problem. ```bash curl -X DELETE https://api-hq.aiworkforceone.com/v1/invites/inv_osw5IZUY55lbPHG4sHWkxl \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/invites/inv_osw5IZUY55lbPHG4sHWkxl', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(res.status); ``` ```python import os import uuid import requests res = requests.delete( "https://api-hq.aiworkforceone.com/v1/invites/inv_osw5IZUY55lbPHG4sHWkxl", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.status_code) ``` Revoked. Its link no longer works. ## Resend an invitation [#resend-an-invitation] Sends a new link (the old one stops working) and extends the expiry. An invitation id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Invite](#invite) object. The invitation. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/invites/inv_osw5IZUY55lbPHG4sHWkxl/resend \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/invites/inv_osw5IZUY55lbPHG4sHWkxl/resend', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/invites/inv_osw5IZUY55lbPHG4sHWkxl/resend", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.json()) ``` ```json title="Response 200" { "object": "invite", "id": "inv_osw5IZUY55lbPHG4sHWkxl", "email": "priya.patel@example.com", "role": "member", "title": "Data analyst", "invited_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" }, "created_at": "2026-10-13T10:00:00.000Z", "expires_at": "2026-10-20T10:00:00.000Z" } ``` ## Objects [#objects] ### Org [#org] ```json title="The Org object" { "object": "org", "id": "org_3SvwLF4ulih8bHz5KtmNOO", "name": "Acme Robotics", "slug": "acme", "plan": "growth", "plan_status": "active", "trial_ends_at": null, "current_period_end": "2026-11-28T00:00:00.000Z", "cancel_at_period_end": false, "created_at": "2026-03-04T11:20:00.000Z" } ``` ### OrgChart [#orgchart] ```json title="The OrgChart object" { "object": "org_chart", "owners": [ { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen", "email": "maya.chen@example.com", "title": "CTO" } ], "people": [ { "id": "user_82yssFqK4JG6pUfKfe95V3", "name": "Sam Okafor", "email": "sam.okafor@example.com", "title": "Platform lead", "role": "admin" } ], "pending_invites": [ { "id": "inv_osw5IZUY55lbPHG4sHWkxl", "email": "priya.patel@example.com", "role": "member", "title": "Data analyst" } ], "teams": [ { "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Research", "engine": "claude", "reports_to": [ { "user": "user_82yssFqK4JG6pUfKfe95V3", "role": "owner" } ], "ai_employee_count": 3, "skill_count": 12, "running_sessions": 2, "schedule_count": 4, "next_run_at": "2026-10-19T07:00:00.000Z" } ] } ``` ### Member [#member] One of `owner`, `admin`, `member`. ```json title="The Member object" { "object": "member", "id": "user_82yssFqK4JG6pUfKfe95V3", "name": "Sam Okafor", "email": "sam.okafor@example.com", "role": "admin", "title": "Platform lead", "two_factor_enabled": true, "joined_at": "2026-03-09T15:41:02.000Z", "last_login_at": "2026-10-14T08:03:57.000Z" } ``` ### Invite [#invite] ```json title="The Invite object" { "object": "invite", "id": "inv_osw5IZUY55lbPHG4sHWkxl", "email": "priya.patel@example.com", "role": "member", "title": "Data analyst", "invited_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" }, "created_at": "2026-10-13T10:00:00.000Z", "expires_at": "2026-10-20T10:00:00.000Z" } ``` --- # Schedules URL: /docs/api/reference/schedules Schedules and their run history. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} ## List schedules [#list-schedules] How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). Only schedules of this AI team. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [Schedule](#schedule) objects. A page of schedules. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/schedules \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/schedules", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "schedule", "id": "sched_lCh70bFOv9IaUYUWyFgTif", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Monday market brief", "enabled": true, "cron": "0 8 * * 1", "timezone": "Europe/London", "frequency": "weekly", "run_times": ["08:00"], "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.", "target_session": null, "create_new_session": true, "on_stopped_session": "restart", "run_with": "team_key", "engine": "claude", "last_run_at": "2026-10-12T07:00:00.000Z", "last_run_status": "success", "next_run_at": "2026-10-19T07:00:00.000Z", "created_at": "2026-09-21T13:44:09.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ], "has_more": false } ``` ## Create a schedule [#create-a-schedule] A schedule runs as the member the user key acts as (a service key cannot create one yet). Pointing it at a session that runs on someone else's personal login is refused. Never a prompt that would run as a command: see `prompt` for what is refused. Schedules always continue the session's conversation so Claude keeps its context. Resuming a long conversation uses part of your Claude usage limit. On an AI team that turned on Protected files, a Codex schedule needs `files:protected.read` and `files:protected.write` on the key and its person: 403 `protected_files_shell` otherwise. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. The task, as you would type it. Refused with `422 validation_failed` (the reason is in `detail`) when it starts with `/`, `!` or `#` (a command, not a task), when it contains a control character (tabs and line breaks are fine), or when it contains `kr-run:`, which HQ reserves for its own run marker. An IANA time zone, for example Europe/London. One of `daily`, `specific_days`, `weekly`, `monthly`, `once`. For `once`. HH:mm. Run in this existing session. Send exactly one of target_session or create_new_session true. Start a new session for each run. Send exactly one of target_session or create_new_session true. One of `restart`, `skip_notify`. With create_new_session only. One of `personal`, `team_key`. One of `claude`, `codex`. **Returns** a [Schedule](#schedule) object. The schedule. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/schedules \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Monday market brief", "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.", "timezone": "Europe/London", "frequency": "weekly", "run_time": "08:00" }' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ team: 'team_3kQ9vX2mR8tLpZ4wYc1aBd', name: 'Monday market brief', prompt: 'Summarise the competitor news of the last 7 days into reports/weekly.md.', timezone: 'Europe/London', frequency: 'weekly', run_time: '08:00', }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/schedules", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={ "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Monday market brief", "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.", "timezone": "Europe/London", "frequency": "weekly", "run_time": "08:00", }, ) print(res.json()) ``` ```json title="Response 201" { "object": "schedule", "id": "sched_lCh70bFOv9IaUYUWyFgTif", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Monday market brief", "enabled": true, "cron": "0 8 * * 1", "timezone": "Europe/London", "frequency": "weekly", "run_times": ["08:00"], "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.", "target_session": null, "create_new_session": true, "on_stopped_session": "restart", "run_with": "team_key", "engine": "claude", "last_run_at": "2026-10-12T07:00:00.000Z", "last_run_status": "success", "next_run_at": "2026-10-19T07:00:00.000Z", "created_at": "2026-09-21T13:44:09.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Get a schedule [#get-a-schedule] A schedule id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Schedule](#schedule) object. The schedule. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "schedule", "id": "sched_lCh70bFOv9IaUYUWyFgTif", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Monday market brief", "enabled": true, "cron": "0 8 * * 1", "timezone": "Europe/London", "frequency": "weekly", "run_times": ["08:00"], "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.", "target_session": null, "create_new_session": true, "on_stopped_session": "restart", "run_with": "team_key", "engine": "claude", "last_run_at": "2026-10-12T07:00:00.000Z", "last_run_status": "success", "next_run_at": "2026-10-19T07:00:00.000Z", "created_at": "2026-09-21T13:44:09.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Update a schedule [#update-a-schedule] Any of the create fields but the team. A user key only. On an AI team that turned on Protected files, a Codex schedule's edit needs `files:protected.read` and `files:protected.write` on the key and its person: 403 `protected_files_shell` otherwise. A schedule id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. The same rules as on create. One of `daily`, `specific_days`, `weekly`, `monthly`, `once`. Switches the schedule to run in this existing session (turns create_new_session off). true switches the schedule to a new session for each run (clears target_session). One of `restart`, `skip_notify`. One of `personal`, `team_key`. One of `claude`, `codex`. **Returns** a [Schedule](#schedule) object. The schedule. An RFC 9457 problem. ```bash curl -X PATCH https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"run_time":"09:30","enabled":true}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ run_time: '09:30', enabled: true }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.patch( "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"run_time": "09:30", "enabled": True}, ) print(res.json()) ``` ```json title="Response 200" { "object": "schedule", "id": "sched_lCh70bFOv9IaUYUWyFgTif", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Monday market brief", "enabled": true, "cron": "0 8 * * 1", "timezone": "Europe/London", "frequency": "weekly", "run_times": ["08:00"], "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.", "target_session": null, "create_new_session": true, "on_stopped_session": "restart", "run_with": "team_key", "engine": "claude", "last_run_at": "2026-10-12T07:00:00.000Z", "last_run_status": "success", "next_run_at": "2026-10-19T07:00:00.000Z", "created_at": "2026-09-21T13:44:09.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Delete a schedule [#delete-a-schedule] A schedule id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Deleted. An RFC 9457 problem. ```bash curl -X DELETE https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(res.status); ``` ```python import os import uuid import requests res = requests.delete( "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.status_code) ``` Deleted. ## List a schedule's runs [#list-a-schedules-runs] Newest first. Pages forward with `starting_after`. A schedule id. How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Only runs with this result. One of `success`, `failed`, `skipped`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [ScheduleRun](#schedulerun) objects. A page of runs. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "schedule_run", "id": "run_4K76tZDj56MBIaHaI02P1e", "schedule": "sched_lCh70bFOv9IaUYUWyFgTif", "session": "sess_U9qrDsTXdBGkZFRLFNOCaR", "status": "success", "outcome": "proven", "started_at": "2026-10-12T07:00:02.000Z", "completed_at": "2026-10-12T07:06:48.000Z", "tokens_used": 40210, "cost_usd": 0.58, "triggered_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ], "has_more": false } ``` ## Run a schedule now [#run-a-schedule-now] Fires the schedule's stored prompt now. 202 with the run once it exists (it continues on its own), or `queued: true` when the plan queues runs while every session slot is busy; 409 naming why a run was skipped. Requires an `Idempotency-Key`. On an AI team that turned on Protected files, a Codex run needs `files:protected.read` and `files:protected.write` on the key and its person: 403 `protected_files_shell` otherwise. A Codex run whose schedule's author lacks them is skipped: 409 `protected_files_shell`. A schedule id. Required here. The same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422; while the first request is still running, 409 `idempotency_in_progress`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [ScheduleRunRequest](#schedulerunrequest) object. The run started, or was queued. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.json()) ``` ```json title="Response 202" { "object": "schedule_run_request", "queued": true, "run": "run_4K76tZDj56MBIaHaI02P1e", "session": null } ``` ## Get a schedule run [#get-a-schedule-run] A schedule id. A schedule run id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [ScheduleRun](#schedulerun) object. The run. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs/run_4K76tZDj56MBIaHaI02P1e \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs/run_4K76tZDj56MBIaHaI02P1e', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs/run_4K76tZDj56MBIaHaI02P1e", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "schedule_run", "id": "run_4K76tZDj56MBIaHaI02P1e", "schedule": "sched_lCh70bFOv9IaUYUWyFgTif", "session": "sess_U9qrDsTXdBGkZFRLFNOCaR", "status": "success", "outcome": "proven", "started_at": "2026-10-12T07:00:02.000Z", "completed_at": "2026-10-12T07:06:48.000Z", "tokens_used": 40210, "cost_usd": 0.58, "triggered_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Enable a schedule [#enable-a-schedule] On an AI team that turned on Protected files, a Codex schedule needs `files:protected.read` and `files:protected.write` on the key and its person: 403 `protected_files_shell` otherwise. A schedule id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Schedule](#schedule) object. The schedule, enabled. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/enable \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/enable', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/enable", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.json()) ``` ```json title="Response 200" { "object": "schedule", "id": "sched_lCh70bFOv9IaUYUWyFgTif", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Monday market brief", "enabled": true, "cron": "0 8 * * 1", "timezone": "Europe/London", "frequency": "weekly", "run_times": ["08:00"], "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.", "target_session": null, "create_new_session": true, "on_stopped_session": "restart", "run_with": "team_key", "engine": "claude", "last_run_at": "2026-10-12T07:00:00.000Z", "last_run_status": "success", "next_run_at": "2026-10-19T07:00:00.000Z", "created_at": "2026-09-21T13:44:09.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Disable a schedule [#disable-a-schedule] A schedule id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Schedule](#schedule) object. The schedule, disabled. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/disable \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/disable', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/disable", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.json()) ``` ```json title="Response 200" { "object": "schedule", "id": "sched_lCh70bFOv9IaUYUWyFgTif", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Monday market brief", "enabled": true, "cron": "0 8 * * 1", "timezone": "Europe/London", "frequency": "weekly", "run_times": ["08:00"], "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.", "target_session": null, "create_new_session": true, "on_stopped_session": "restart", "run_with": "team_key", "engine": "claude", "last_run_at": "2026-10-12T07:00:00.000Z", "last_run_status": "success", "next_run_at": "2026-10-19T07:00:00.000Z", "created_at": "2026-09-21T13:44:09.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Move a schedule to its session's owner [#move-a-schedule-to-its-sessions-owner] A schedule that reuses a session runs on the Claude login of the person it runs as (`created_by`). When the session is reassigned to someone else, the schedule stops running until it is moved. This moves it to the session's current owner: from then on it runs on their Claude login, and `created_by` names them. It only ever moves to the session's current owner, so it takes no body. Over the API only the session's owner can do this, with their own user key: it puts the schedule on their own Claude login. Organization owners and admins and team owners move a teammate's schedule in HQ. A schedule that already runs as the owner is returned unchanged (safe to retry). Schedules that start a new session each run, and schedules on the team's API key, cannot be moved, and a schedule never moves to an owner who can't manage schedules on the team (`409 owner_cannot_manage_schedules`). A schedule id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Schedule](#schedule) object. The schedule, now running as the session's owner. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/move_to_session_owner \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/move_to_session_owner', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/move_to_session_owner", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.json()) ``` ```json title="Response 200" { "object": "schedule", "id": "sched_lCh70bFOv9IaUYUWyFgTif", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Monday market brief", "enabled": true, "cron": "0 8 * * 1", "timezone": "Europe/London", "frequency": "weekly", "run_times": ["08:00"], "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.", "target_session": null, "create_new_session": true, "on_stopped_session": "restart", "run_with": "team_key", "engine": "claude", "last_run_at": "2026-10-12T07:00:00.000Z", "last_run_status": "success", "next_run_at": "2026-10-19T07:00:00.000Z", "created_at": "2026-09-21T13:44:09.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Objects [#objects] ### Schedule [#schedule] ```json title="The Schedule object" { "object": "schedule", "id": "sched_lCh70bFOv9IaUYUWyFgTif", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Monday market brief", "enabled": true, "cron": "0 8 * * 1", "timezone": "Europe/London", "frequency": "weekly", "run_times": ["08:00"], "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.", "target_session": null, "create_new_session": true, "on_stopped_session": "restart", "run_with": "team_key", "engine": "claude", "last_run_at": "2026-10-12T07:00:00.000Z", "last_run_status": "success", "next_run_at": "2026-10-19T07:00:00.000Z", "created_at": "2026-09-21T13:44:09.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ### ScheduleRun [#schedulerun] ```json title="The ScheduleRun object" { "object": "schedule_run", "id": "run_4K76tZDj56MBIaHaI02P1e", "schedule": "sched_lCh70bFOv9IaUYUWyFgTif", "session": "sess_U9qrDsTXdBGkZFRLFNOCaR", "status": "success", "outcome": "proven", "started_at": "2026-10-12T07:00:02.000Z", "completed_at": "2026-10-12T07:06:48.000Z", "tokens_used": 40210, "cost_usd": 0.58, "triggered_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ### ScheduleRunRequest [#schedulerunrequest] The run id (poll GET /schedules/\{schedule_id}/runs/\{run_id}). ```json title="The ScheduleRunRequest object" { "object": "schedule_run_request", "queued": true, "run": "run_4K76tZDj56MBIaHaI02P1e", "session": null } ``` --- # Secrets URL: /docs/api/reference/secrets Secret names and where they apply. A secret value is never returned. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} ## List an AI team's secrets [#list-an-ai-teams-secrets] Names, scope and teams. A value is never returned. An AI team id. How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [Secret](#secret) objects. A page of secrets. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "secret", "id": "sec_vbGigyDOkNeK3aNzDuiclU", "name": "GITHUB_TOKEN", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:11:12.000Z", "updated_at": "2026-10-01T08:30:00.000Z" } ], "has_more": false } ``` ## Create an AI team's secret [#create-an-ai-teams-secret] The value is write-only: no response carries it, and there is no reveal route on the API. An AI team id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Secret](#secret) object. The secret (never its value). An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"name":"STRIPE_API_KEY","value":"your-stripe-key"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'STRIPE_API_KEY', value: 'your-stripe-key' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"name": "STRIPE_API_KEY", "value": "your-stripe-key"}, ) print(res.json()) ``` ```json title="Response 201" { "object": "secret", "id": "sec_vbGigyDOkNeK3aNzDuiclU", "name": "GITHUB_TOKEN", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:11:12.000Z", "updated_at": "2026-10-01T08:30:00.000Z" } ``` ## Get an AI team's secret [#get-an-ai-teams-secret] An AI team id. A secret id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Secret](#secret) object. The secret, without its value. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "secret", "id": "sec_vbGigyDOkNeK3aNzDuiclU", "name": "GITHUB_TOKEN", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:11:12.000Z", "updated_at": "2026-10-01T08:30:00.000Z" } ``` ## Delete an AI team's secret [#delete-an-ai-teams-secret] An AI team id. A secret id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Done. An RFC 9457 problem. ```bash curl -X DELETE https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(res.status); ``` ```python import os import uuid import requests res = requests.delete( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.status_code) ``` Done. ## List organization secrets [#list-organization-secrets] Names, scope and teams. A value is never returned. How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [Secret](#secret) objects. A page of secrets. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/secrets \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/secrets', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/secrets", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "secret", "id": "sec_vbGigyDOkNeK3aNzDuiclU", "name": "GITHUB_TOKEN", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:11:12.000Z", "updated_at": "2026-10-01T08:30:00.000Z" } ], "has_more": false } ``` ## Create an org secret [#create-an-org-secret] Org-wide (`scope: org`) or shared with chosen teams (`scope: selected`). The value is write-only: no response carries it, and there is no reveal route on the API. A key restricted to some AI teams creates only `selected` secrets, for teams inside its restriction (an org-wide one is 403 team_restricted, another team 404). Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. One of `org`, `selected`. With `scope: selected` only. **Returns** a [Secret](#secret) object. The secret (never its value). An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/secrets \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"name":"GITHUB_TOKEN","value":"your-github-token"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/secrets', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'GITHUB_TOKEN', value: 'your-github-token' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/secrets", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"name": "GITHUB_TOKEN", "value": "your-github-token"}, ) print(res.json()) ``` ```json title="Response 201" { "object": "secret", "id": "sec_vbGigyDOkNeK3aNzDuiclU", "name": "GITHUB_TOKEN", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:11:12.000Z", "updated_at": "2026-10-01T08:30:00.000Z" } ``` ## Get an organization secret [#get-an-organization-secret] A secret id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Secret](#secret) object. The secret, without its value. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "secret", "id": "sec_vbGigyDOkNeK3aNzDuiclU", "name": "GITHUB_TOKEN", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:11:12.000Z", "updated_at": "2026-10-01T08:30:00.000Z" } ``` ## Delete an org secret [#delete-an-org-secret] A secret id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Done. An RFC 9457 problem. ```bash curl -X DELETE https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(res.status); ``` ```python import os import uuid import requests res = requests.delete( "https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.status_code) ``` Done. ## Replace an org secret's value [#replace-an-org-secrets-value] The value is write-only: no response carries it, and there is no reveal route on the API. A secret id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Secret](#secret) object. The secret (never its value). An RFC 9457 problem. ```bash curl -X PUT https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/value \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"value":"your-new-token"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/value', { method: 'PUT', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ value: 'your-new-token' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.put( "https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/value", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"value": "your-new-token"}, ) print(res.json()) ``` ```json title="Response 200" { "object": "secret", "id": "sec_vbGigyDOkNeK3aNzDuiclU", "name": "GITHUB_TOKEN", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:11:12.000Z", "updated_at": "2026-10-01T08:30:00.000Z" } ``` ## Set the teams a selected secret reaches [#set-the-teams-a-selected-secret-reaches] A secret id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Secret](#secret) object. The secret (never its value). An RFC 9457 problem. ```bash curl -X PUT https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"teams":["team_3kQ9vX2mR8tLpZ4wYc1aBd"]}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams', { method: 'PUT', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ teams: ['team_3kQ9vX2mR8tLpZ4wYc1aBd'] }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.put( "https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"]}, ) print(res.json()) ``` ```json title="Response 200" { "object": "secret", "id": "sec_vbGigyDOkNeK3aNzDuiclU", "name": "GITHUB_TOKEN", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:11:12.000Z", "updated_at": "2026-10-01T08:30:00.000Z" } ``` ## Share a selected secret with one more team [#share-a-selected-secret-with-one-more-team] A secret id. An AI team id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Done. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(res.status); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.status_code) ``` Done. ## Stop sharing a selected secret with a team [#stop-sharing-a-selected-secret-with-a-team] A secret id. An AI team id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Done. An RFC 9457 problem. ```bash curl -X DELETE https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(res.status); ``` ```python import os import uuid import requests res = requests.delete( "https://api-hq.aiworkforceone.com/v1/secrets/sec_vbGigyDOkNeK3aNzDuiclU/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.status_code) ``` Done. ## Replace an AI team's secret value [#replace-an-ai-teams-secret-value] The value is write-only: no response carries it, and there is no reveal route on the API. An AI team id. A secret id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Secret](#secret) object. The secret (never its value). An RFC 9457 problem. ```bash curl -X PUT https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU/value \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"value":"your-new-token"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU/value', { method: 'PUT', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ value: 'your-new-token' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.put( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/secrets/sec_vbGigyDOkNeK3aNzDuiclU/value", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"value": "your-new-token"}, ) print(res.json()) ``` ```json title="Response 200" { "object": "secret", "id": "sec_vbGigyDOkNeK3aNzDuiclU", "name": "GITHUB_TOKEN", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:11:12.000Z", "updated_at": "2026-10-01T08:30:00.000Z" } ``` ## Objects [#objects] ### Secret [#secret] A secret's name and where it applies. Deliberately has no value field. One of `org`, `team`. ```json title="The Secret object" { "object": "secret", "id": "sec_vbGigyDOkNeK3aNzDuiclU", "name": "GITHUB_TOKEN", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:11:12.000Z", "updated_at": "2026-10-01T08:30:00.000Z" } ``` --- # Sessions URL: /docs/api/reference/sessions The sessions running on your AI teams. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} ## List sessions [#list-sessions] The sessions the key's holder can see, narrowed by the key's team restriction. How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). Only sessions of this AI team. Only sessions in this state. One of `starting`, `running`, `stopped`, `error`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [Session](#session) objects. A page of sessions. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/sessions \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/sessions", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "session", "id": "sess_0a843Y2wTmED2k3FJPP56X", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Weekly competitor scan", "status": "running", "engine": "claude", "run_with": "personal", "owner": "user_yFfQdB3rxA41x3cTD5fx2Q", "permission_mode": "default", "token_count": 184320, "cost_usd": 2.41, "last_activity_at": "2026-10-14T16:05:31.000Z", "created_at": "2026-10-14T15:20:02.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ], "has_more": false } ``` ## Get a session [#get-a-session] A session id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Session](#session) object. The session. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "session", "id": "sess_0a843Y2wTmED2k3FJPP56X", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Weekly competitor scan", "status": "running", "engine": "claude", "run_with": "personal", "owner": "user_yFfQdB3rxA41x3cTD5fx2Q", "permission_mode": "default", "token_count": 184320, "cost_usd": 2.41, "last_activity_at": "2026-10-14T16:05:31.000Z", "created_at": "2026-10-14T15:20:02.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Rename a session [#rename-a-session] The name only. Who a session belongs to, its mode and its terminal stay in HQ. A session id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Session](#session) object. The session. An RFC 9457 problem. ```bash curl -X PATCH https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"name":"Competitor scan, October"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Competitor scan, October' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.patch( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"name": "Competitor scan, October"}, ) print(res.json()) ``` ```json title="Response 200" { "object": "session", "id": "sess_0a843Y2wTmED2k3FJPP56X", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Weekly competitor scan", "status": "running", "engine": "claude", "run_with": "personal", "owner": "user_yFfQdB3rxA41x3cTD5fx2Q", "permission_mode": "default", "token_count": 184320, "cost_usd": 2.41, "last_activity_at": "2026-10-14T16:05:31.000Z", "created_at": "2026-10-14T15:20:02.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Delete a session [#delete-a-session] An org owner or admin only. Stops it if it runs, then deletes it and its schedules. A session id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Deleted. An RFC 9457 problem. ```bash curl -X DELETE https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(res.status); ``` ```python import os import uuid import requests res = requests.delete( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.status_code) ``` Deleted. ## Get a session's token usage [#get-a-sessions-token-usage] The newest `limit` usage samples, returned oldest first. A session id. How many objects to return, 1 to 100. Default 20. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [SessionUsage](#sessionusage) object. The usage samples. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/usage \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/usage', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/usage", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "session_usage", "session": "sess_0a843Y2wTmED2k3FJPP56X", "samples": [ { "at": "2026-10-14T15:00:00.000Z", "tokens": 12880, "cost_usd": 0.17 }, { "at": "2026-10-14T16:00:00.000Z", "tokens": 40112, "cost_usd": 0.52 } ] } ``` ## Create a session [#create-a-session] Creates a session on the AI team and, unless `start` is false, starts it. `run_with: "personal"` binds the member the user key acts as (their own Claude or ChatGPT login); a service key cannot (422 `personal_login_not_available`). `run_with: "team_key"` also needs `sessions:run_with_team_key` on the team. The plan's session limit applies. When the AI team is paused, a start answers 409 `workspace_paused`, and while its Cloud Computer is being updated or resized, 409 `workspace_updating`; while it is too busy for another session, 409 `machine_busy` (either way the session is created, stopped). Requires an `Idempotency-Key`. On an AI team that turned on Protected files, a Codex session (named, or the team's only engine) needs `files:protected.read` and `files:protected.write` on the key and its person: 403 `protected_files_shell` otherwise. An AI team id. Required here. The same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422; while the first request is still running, 409 `idempotency_in_progress`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. personal: the user key's own member's login. team_key: the AI team's key. One of `personal`, `team_key`. Required on a team that runs both engines. One of `claude`, `codex`. One of `default`, `acceptEdits`, `bypassPermissions`. **Returns** a [Session](#session) object. The session, starting (or stopped when `start` was false). An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/sessions \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"run_with":"personal"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/sessions', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ run_with: 'personal' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/sessions", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"run_with": "personal"}, ) print(res.json()) ``` ```json title="Response 201" { "object": "session", "id": "sess_0a843Y2wTmED2k3FJPP56X", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Weekly competitor scan", "status": "running", "engine": "claude", "run_with": "personal", "owner": "user_yFfQdB3rxA41x3cTD5fx2Q", "permission_mode": "default", "token_count": 184320, "cost_usd": 2.41, "last_activity_at": "2026-10-14T16:05:31.000Z", "created_at": "2026-10-14T15:20:02.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Start a session [#start-a-session] Starts a stopped session. Its owner, or an org owner or admin, may start it. A service key never starts an unclaimed personal-login session (starting it would bind a login). When the AI team is paused, the answer is 409 `workspace_paused`; while its Cloud Computer is being updated or resized, 409 `workspace_updating`; while it is too busy for another session, 409 `machine_busy`. On an AI team that turned on Protected files, a Codex session start needs `files:protected.read` and `files:protected.write` on the key and its person: 403 `protected_files_shell` otherwise. A session id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Session](#session) object. The session, starting. Follow `GET /sessions/{session_id}` or its event stream. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/start \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/start', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/start", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.json()) ``` ```json title="Response 202" { "object": "session", "id": "sess_0a843Y2wTmED2k3FJPP56X", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Weekly competitor scan", "status": "running", "engine": "claude", "run_with": "personal", "owner": "user_yFfQdB3rxA41x3cTD5fx2Q", "permission_mode": "default", "token_count": 184320, "cost_usd": 2.41, "last_activity_at": "2026-10-14T16:05:31.000Z", "created_at": "2026-10-14T15:20:02.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Stop a session [#stop-a-session] A session id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Session](#session) object. The session, stopped. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/stop \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/stop', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/stop", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.json()) ``` ```json title="Response 200" { "object": "session", "id": "sess_0a843Y2wTmED2k3FJPP56X", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Weekly competitor scan", "status": "running", "engine": "claude", "run_with": "personal", "owner": "user_yFfQdB3rxA41x3cTD5fx2Q", "permission_mode": "default", "token_count": 184320, "cost_usd": 2.41, "last_activity_at": "2026-10-14T16:05:31.000Z", "created_at": "2026-10-14T15:20:02.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Restart a session [#restart-a-session] Stops and starts the session. `fresh` starts a new conversation instead of resuming. When the AI team is paused, the answer is 409 `workspace_paused`; while its Cloud Computer is being updated or resized, 409 `workspace_updating`; while it is too busy for another session, 409 `machine_busy`. Either way a running session keeps running. On an AI team that turned on Protected files, a Codex session restart needs `files:protected.read` and `files:protected.write` on the key and its person: 403 `protected_files_shell` otherwise. A session id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Start a new conversation instead of resuming the last one. **Returns** a [Session](#session) object. The session, starting again. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/restart \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"fresh":false}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/restart', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ fresh: false }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/restart", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"fresh": False}, ) print(res.json()) ``` ```json title="Response 202" { "object": "session", "id": "sess_0a843Y2wTmED2k3FJPP56X", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Weekly competitor scan", "status": "running", "engine": "claude", "run_with": "personal", "owner": "user_yFfQdB3rxA41x3cTD5fx2Q", "permission_mode": "default", "token_count": 184320, "cost_usd": 2.41, "last_activity_at": "2026-10-14T16:05:31.000Z", "created_at": "2026-10-14T15:20:02.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Interrupt the current turn [#interrupt-the-current-turn] Presses Esc in the session, as the Chat view's Stop button does. The same keyboard rule as sending a message applies. While Claude is holding a message from another session, Esc would decline it: the answer is `409 held_peer_message` and nothing is pressed. Deliver or deny the message in the session in HQ, then interrupt again. A session id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Esc was pressed. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/interrupt \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/interrupt', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(res.status); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/interrupt", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.status_code) ``` Esc was pressed. ## List a session's conversation [#list-a-sessions-conversation] The conversation as HQ's Chat view shows it: messages, tool uses, thinking markers and notices, masked. Newest page by default; page with the `start_cursor` / `end_cursor` the response returns. Never wakes a sleeping machine (409 while it sleeps). A session id. A cursor from this session (`end_cursor`, or an event `id`); return what follows it. A cursor from this session (`start_cursor`); return what precedes it. How many objects to return, 1 to 100. Default 20. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [SessionItemList](#sessionitemlist) object. A page of items, oldest first. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/items \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/items', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/items", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "session_item", "id": "item_M2Y5YTBjMmU3YjFkNGE2ODo1MTg3Nw", "type": "message", "seq": 214, "at": "2026-10-14T16:05:31.000Z", "engine": "claude", "role": "assistant", "content": [ { "type": "text", "text": "Three competitors changed their pricing this week. The brief is in reports/weekly.md." } ] } ], "has_more": false, "start_cursor": "c1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsIm8iOjQ4MjEzfQ", "end_cursor": "c1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsIm8iOjUxODc3fQ" } ``` ## Get a tool use's or a thinking block's detail [#get-a-tool-uses-or-a-thinking-blocks-detail] The masked detail behind an item's `detail_ref` (256 KiB at most). A session id. A session item id. The item's `detail_ref`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [SessionItemDetail](#sessionitemdetail) object. The detail. An RFC 9457 problem. ```bash curl "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/items/item_M2Y5YTBjMmU3YjFkNGE2ODo1MTg3Nw/detail?ref=d1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsInUiOltbNTE4NzcsMV1dLCJyIjpbWzUyNDEwLDBdXX0" \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/items/item_M2Y5YTBjMmU3YjFkNGE2ODo1MTg3Nw/detail?ref=d1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsInUiOltbNTE4NzcsMV1dLCJyIjpbWzUyNDEwLDBdXX0', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/items/item_M2Y5YTBjMmU3YjFkNGE2ODo1MTg3Nw/detail?ref=d1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsInUiOltbNTE4NzcsMV1dLCJyIjpbWzUyNDEwLDBdXX0", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "session_item_detail", "kind": "diff", "tool": "Edit", "target": ["reports/weekly.md"], "files": null, "diff": [ { "path": "reports/weekly.md", "before": "## Pricing\n\nNo changes.\n", "after": "## Pricing\n\nThree competitors changed their pricing.\n" } ], "output": null, "error": null, "thinking": null, "truncated": false } ``` ## Stream a session's events [#stream-a-sessions-events] Server-Sent Events: `session.message.completed`, `session.tool_use.started|completed|failed`, `session.thinking.completed`, `session.notice`, `session.status`, `session.input_required`, `session.turn.completed` and `session.message.status_changed`, each a JSON event envelope. Reconnect with `Last-Event-ID` to resume without a gap. `: ping` every 15 s; `stream.rotate` at 50 minutes (reconnect); `stream.reset` when you fell behind (list the items, then reconnect). A stream never wakes the machine. At most 4 streams per session. A session id. A cursor from this session (`end_cursor`, or an event `id`); return what follows it. The `id` of the last event you received. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. The event stream. An RFC 9457 problem. ```bash curl -N https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/events \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/events', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); const decoder = new TextDecoder(); for await (const chunk of res.body) { process.stdout.write(decoder.decode(chunk, { stream: true })); } ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/events", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, stream=True, ) for line in res.iter_lines(decode_unicode=True): print(line) ``` ```text title="Response 200" id: c1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsIm8iOjUxODc3fQ event: session.message.completed data: {"id":"evt_9OvoJuvytSGhqe71vQ9tqx","object":"event","type":"session.message.completed","api_version":"2026-11-01","created_at":"2026-10-14T16:05:31.000Z","org_id":"org_3SvwLF4ulih8bHz5KtmNOO","team_id":"team_3kQ9vX2mR8tLpZ4wYc1aBd","resource":{"type":"session","id":"sess_0a843Y2wTmED2k3FJPP56X"},"data":{"session_id":"sess_0a843Y2wTmED2k3FJPP56X","item_id":"item_M2Y5YTBjMmU3YjFkNGE2ODo1MTg3Nw","seq":214,"at":"2026-10-14T16:05:31.000Z","engine":"claude","role":"assistant","content":[{"type":"text","text":"The brief is in reports/weekly.md."}]}} event: session.turn.completed data: {"id":"evt_Q2m8XcR4tV7bN1kL9pZ3wD","object":"event","type":"session.turn.completed","api_version":"2026-11-01","created_at":"2026-10-14T16:05:33.000Z","org_id":"org_3SvwLF4ulih8bHz5KtmNOO","team_id":"team_3kQ9vX2mR8tLpZ4wYc1aBd","resource":{"type":"session","id":"sess_0a843Y2wTmED2k3FJPP56X"},"data":{"session_id":"sess_0a843Y2wTmED2k3FJPP56X"}} ``` ## Send a message [#send-a-message] Sends a prompt to a running session; follow `session.message.status_changed` on the event stream, or this message. A personal-login session accepts messages only from its owner's own user key (403 `session_not_owned` for anyone else); a team-key session needs `sessions:run_with_team_key`. A sleeping machine is woken (`waiting_for: "wake"`). A prompt is typed at most once. Requires an `Idempotency-Key`. A session id. Required here. The same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422; while the first request is still running, 409 `idempotency_in_progress`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Message](#message) object. Accepted. Delivery continues in the background. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/messages \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "content": [ { "type": "text", "text": "List the open pull requests" } ] }' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ content: [{ type: 'text', text: 'List the open pull requests' }] }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/messages", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={ "content": [{"type": "text", "text": "List the open pull requests"}], }, ) print(res.json()) ``` ```json title="Response 202" { "object": "message", "id": "msg_jtGNtRjFCseJiNrAp3v6bQ", "session": "sess_0a843Y2wTmED2k3FJPP56X", "status": "accepted", "waiting_for": null, "code": null, "text_bytes": 27, "image_count": 0, "delivered_item": null, "deadline_at": "2026-10-14T16:20:31.000Z", "created_at": "2026-10-14T16:05:31.000Z", "updated_at": "2026-10-14T16:05:31.000Z" } ``` ## Get a message's delivery state [#get-a-messages-delivery-state] A session id. A message id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Message](#message) object. The message. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/messages/msg_jtGNtRjFCseJiNrAp3v6bQ \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/messages/msg_jtGNtRjFCseJiNrAp3v6bQ', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/messages/msg_jtGNtRjFCseJiNrAp3v6bQ", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "message", "id": "msg_jtGNtRjFCseJiNrAp3v6bQ", "session": "sess_0a843Y2wTmED2k3FJPP56X", "status": "accepted", "waiting_for": null, "code": null, "text_bytes": 27, "image_count": 0, "delivered_item": null, "deadline_at": "2026-10-14T16:20:31.000Z", "created_at": "2026-10-14T16:05:31.000Z", "updated_at": "2026-10-14T16:05:31.000Z" } ``` ## Answer a permission, plan or question card [#answer-a-permission-plan-or-question-card] Answers the card a `session.input_required` event announced (`answerable_via_api: true`), naming its `instance_id` and `digest`. The server re-reads the screen and types only the recorded keys for the choice. The keyboard rule of messages applies. Requires an `Idempotency-Key`. A session id. Required here. The same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422; while the first request is still running, 409 `idempotency_in_progress`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. One of `select`, `toggle`, `otherText`, `next`, `back`, `review`, `submit`, `cancel`. **Returns** a [SessionActionResult](#sessionactionresult) object. The answer was applied. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/actions \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"instance_id":"m_8f2c41","digest":"a3f9c27e"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/actions', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ instance_id: 'm_8f2c41', digest: 'a3f9c27e' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/actions", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"instance_id": "m_8f2c41", "digest": "a3f9c27e"}, ) print(res.json()) ``` ```json title="Response 200" { "object": "session_action", "status": "applied", "digest": "b71d04c5" } ``` ## Objects [#objects] ### Session [#session] Open-ended: starting, running, stopped, error. personal (the owner's own login) or team_key. ```json title="The Session object" { "object": "session", "id": "sess_0a843Y2wTmED2k3FJPP56X", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Weekly competitor scan", "status": "running", "engine": "claude", "run_with": "personal", "owner": "user_yFfQdB3rxA41x3cTD5fx2Q", "permission_mode": "default", "token_count": 184320, "cost_usd": 2.41, "last_activity_at": "2026-10-14T16:05:31.000Z", "created_at": "2026-10-14T15:20:02.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ### SessionUsage [#sessionusage] ```json title="The SessionUsage object" { "object": "session_usage", "session": "sess_0a843Y2wTmED2k3FJPP56X", "samples": [ { "at": "2026-10-14T15:00:00.000Z", "tokens": 12880, "cost_usd": 0.17 }, { "at": "2026-10-14T16:00:00.000Z", "tokens": 40112, "cost_usd": 0.52 } ] } ``` ### SessionItemList [#sessionitemlist] ```json title="The SessionItemList object" { "object": "list", "data": [ { "object": "session_item", "id": "item_M2Y5YTBjMmU3YjFkNGE2ODo1MTg3Nw", "type": "message", "seq": 214, "at": "2026-10-14T16:05:31.000Z", "engine": "claude", "role": "assistant", "content": [ { "type": "text", "text": "Three competitors changed their pricing this week. The brief is in reports/weekly.md." } ] } ], "has_more": false, "start_cursor": "c1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsIm8iOjQ4MjEzfQ", "end_cursor": "c1.eyJmIjoiM2Y5YTBjMmU3YjFkNGE2OCIsIm8iOjUxODc3fQ" } ``` ### SessionItemDetail [#sessionitemdetail] Open-ended: diff, command, file_list, raw, thinking. ```json title="The SessionItemDetail object" { "object": "session_item_detail", "kind": "diff", "tool": "Edit", "target": ["reports/weekly.md"], "files": null, "diff": [ { "path": "reports/weekly.md", "before": "## Pricing\n\nNo changes.\n", "after": "## Pricing\n\nThree competitors changed their pricing.\n" } ], "output": null, "error": null, "thinking": null, "truncated": false } ``` ### Message [#message] A prompt sent over the API. Its text is never stored or returned. Open-ended: accepted, queued, typing, submitted, delivered, unconfirmed, blocked_by_moment, failed. While queued: wake, ready or moment. Why it failed, when it did. The conversation item that proved delivery. ```json title="The Message object" { "object": "message", "id": "msg_jtGNtRjFCseJiNrAp3v6bQ", "session": "sess_0a843Y2wTmED2k3FJPP56X", "status": "accepted", "waiting_for": null, "code": null, "text_bytes": 27, "image_count": 0, "delivered_item": null, "deadline_at": "2026-10-14T16:20:31.000Z", "created_at": "2026-10-14T16:05:31.000Z", "updated_at": "2026-10-14T16:05:31.000Z" } ``` ### SessionActionResult [#sessionactionresult] The card's new digest, for a next press on the same card. ```json title="The SessionActionResult object" { "object": "session_action", "status": "applied", "digest": "b71d04c5" } ``` --- # AI teams URL: /docs/api/reference/teams AI teams, who can reach them, and their AI Employees. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} ## List AI teams [#list-ai-teams] The AI teams the key's holder can read, narrowed by the key's team restriction. On an AI team that turned on Protected files, a key that lacks `files:protected.read` (or whose person lacks it) gets `ai_employee_count` and `skill_count` as null for that team. How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [Team](#team) objects. A page of AI teams. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/teams \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/teams", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "team", "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Research", "description": "Market and competitor research.", "color": "#0E7C57", "icon": "flask-conical", "engine_mode": "claude", "engines": ["claude"], "session_count": 5, "running_session_count": 2, "ai_employee_count": 3, "skill_count": 12, "storage_bytes_used": 734003200, "template": null, "created_at": "2026-03-04T11:32:18.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ], "has_more": false } ``` ## Create an AI team [#create-an-ai-team] An empty AI team. The plan's team limit applies. Creating a team from a template stays in HQ in this version (it asks you to consent to what the template runs). A key restricted to some AI teams cannot do this (403 team_restricted). Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. A hex color. An icon name. The engine the team runs, default `claude`. The field is `engine`, not `provider`: any other field is `400 invalid_request`. One of `claude`, `codex`, `both`. **Returns** a [Team](#team) object. The new team. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/teams \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"name":"Research"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Research' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/teams", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"name": "Research"}, ) print(res.json()) ``` ```json title="Response 201" { "object": "team", "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Research", "description": "Market and competitor research.", "color": "#0E7C57", "icon": "flask-conical", "engine_mode": "claude", "engines": ["claude"], "session_count": 5, "running_session_count": 2, "ai_employee_count": 3, "skill_count": 12, "storage_bytes_used": 734003200, "template": null, "created_at": "2026-03-04T11:32:18.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Get an AI team [#get-an-ai-team] An AI team id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Team](#team) object. The AI team. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "team", "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Research", "description": "Market and competitor research.", "color": "#0E7C57", "icon": "flask-conical", "engine_mode": "claude", "engines": ["claude"], "session_count": 5, "running_session_count": 2, "ai_employee_count": 3, "skill_count": 12, "storage_bytes_used": 734003200, "template": null, "created_at": "2026-03-04T11:32:18.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Update an AI team [#update-an-ai-team] Its name, description, color and icon. A team owner may change these. An AI team id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Team](#team) object. The team. An RFC 9457 problem. ```bash curl -X PATCH https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"name":"Research desk","color":"#0E7C57"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Research desk', color: '#0E7C57' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.patch( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"name": "Research desk", "color": "#0E7C57"}, ) print(res.json()) ``` ```json title="Response 200" { "object": "team", "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Research", "description": "Market and competitor research.", "color": "#0E7C57", "icon": "flask-conical", "engine_mode": "claude", "engines": ["claude"], "session_count": 5, "running_session_count": 2, "ai_employee_count": 3, "skill_count": 12, "storage_bytes_used": 734003200, "template": null, "created_at": "2026-03-04T11:32:18.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## Delete an AI team [#delete-an-ai-team] Stops its sessions and deletes it. Its disk is erased afterwards. Org owners and admins. An AI team id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Deleted. An RFC 9457 problem. ```bash curl -X DELETE https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(res.status); ``` ```python import os import uuid import requests res = requests.delete( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.status_code) ``` Deleted. ## List who can reach an AI team [#list-who-can-reach-an-ai-team] The people granted access to the team and their team role. An AI team id. How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [TeamMember](#teammember) objects. A page of team members. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "team_member", "user": "user_82yssFqK4JG6pUfKfe95V3", "name": "Sam Okafor", "email": "sam.okafor@example.com", "role": "editor", "granted_at": "2026-03-10T09:00:00.000Z", "granted_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ], "has_more": false } ``` ## Give a member access to an AI team [#give-a-member-access-to-an-ai-team] Grants (or changes) a member's role on the team. A team owner who is not an org owner or admin cannot change an org owner's or admin's access, nor demote the last team owner. An AI team id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. A member's user id. One of `owner`, `editor`, `viewer`. **Returns** a [TeamMember](#teammember) object. The grant. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"user":"user_82yssFqK4JG6pUfKfe95V3","role":"editor"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ user: 'user_82yssFqK4JG6pUfKfe95V3', role: 'editor' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"user": "user_82yssFqK4JG6pUfKfe95V3", "role": "editor"}, ) print(res.json()) ``` ```json title="Response 201" { "object": "team_member", "user": "user_82yssFqK4JG6pUfKfe95V3", "name": "Sam Okafor", "email": "sam.okafor@example.com", "role": "editor", "granted_at": "2026-03-10T09:00:00.000Z", "granted_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ## List an AI team's AI Employees [#list-an-ai-teams-ai-employees] The AI Employees defined on the team's machine, by name. Never wakes the machine. On an AI team that turned on Protected files, a key that lacks `files:protected.read` (or whose person lacks it) gets 403 protected_path: their names are protected files. An AI team id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [AiEmployee](#aiemployee) objects. The AI Employees. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/ai_employees \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/ai_employees', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/ai_employees", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "ai_employee", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Market analyst" } ], "has_more": false, "skill_count": 12 } ``` ## Remove a member's access to an AI team [#remove-a-members-access-to-an-ai-team] An AI team id. A member's user id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Removed. An RFC 9457 problem. ```bash curl -X DELETE https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members/user_82yssFqK4JG6pUfKfe95V3 \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members/user_82yssFqK4JG6pUfKfe95V3', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(res.status); ``` ```python import os import uuid import requests res = requests.delete( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/members/user_82yssFqK4JG6pUfKfe95V3", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.status_code) ``` Removed. ## Set who sees a team's sessions [#set-who-sees-a-teams-sessions] `all`: everyone on the team. `own`: each session's owner (and org owners and admins). An AI team id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. One of `all`, `own`. **Returns** a [SessionVisibility](#sessionvisibility) object. The team's session visibility. An RFC 9457 problem. ```bash curl -X PUT https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/session_visibility \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"visibility":"all"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/session_visibility', { method: 'PUT', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ visibility: 'all' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.put( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/session_visibility", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"visibility": "all"}, ) print(res.json()) ``` ```json title="Response 200" { "object": "session_visibility", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "visibility": "all" } ``` ## Objects [#objects] ### Team [#team] ```json title="The Team object" { "object": "team", "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Research", "description": "Market and competitor research.", "color": "#0E7C57", "icon": "flask-conical", "engine_mode": "claude", "engines": ["claude"], "session_count": 5, "running_session_count": 2, "ai_employee_count": 3, "skill_count": 12, "storage_bytes_used": 734003200, "template": null, "created_at": "2026-03-04T11:32:18.000Z", "created_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ### TeamMember [#teammember] Present for an admin's key only. One of `owner`, `editor`, `viewer`. ```json title="The TeamMember object" { "object": "team_member", "user": "user_82yssFqK4JG6pUfKfe95V3", "name": "Sam Okafor", "email": "sam.okafor@example.com", "role": "editor", "granted_at": "2026-03-10T09:00:00.000Z", "granted_by": { "id": "user_yFfQdB3rxA41x3cTD5fx2Q", "name": "Maya Chen" } } ``` ### AiEmployee [#aiemployee] ```json title="The AiEmployee object" { "object": "ai_employee", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "name": "Market analyst" } ``` ### SessionVisibility [#sessionvisibility] ```json title="The SessionVisibility object" { "object": "session_visibility", "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "visibility": "all" } ``` --- # Templates URL: /docs/api/reference/templates The AI team templates your organization owns. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} ## List templates [#list-templates] How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [Template](#template) objects. A page of templates. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/templates \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/templates', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/templates", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "template", "id": "tpl_UdI5hI7JqIj0RY89wGmAGU", "name": "Research desk", "description": "A research team with a market analyst and a weekly brief.", "version": "1.2.0", "engine": "claude", "origin": "snapshot", "revision": 3, "created_at": "2026-08-30T17:02:45.000Z" } ], "has_more": false } ``` ## Get a template [#get-a-template] A template id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Template](#template) object. The template. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/templates/tpl_UdI5hI7JqIj0RY89wGmAGU \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/templates/tpl_UdI5hI7JqIj0RY89wGmAGU', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/templates/tpl_UdI5hI7JqIj0RY89wGmAGU", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "template", "id": "tpl_UdI5hI7JqIj0RY89wGmAGU", "name": "Research desk", "description": "A research team with a market analyst and a weekly brief.", "version": "1.2.0", "engine": "claude", "origin": "snapshot", "revision": 3, "created_at": "2026-08-30T17:02:45.000Z" } ``` ## Objects [#objects] ### Template [#template] ```json title="The Template object" { "object": "template", "id": "tpl_UdI5hI7JqIj0RY89wGmAGU", "name": "Research desk", "description": "A research team with a market analyst and a weekly brief.", "version": "1.2.0", "engine": "claude", "origin": "snapshot", "revision": 3, "created_at": "2026-08-30T17:02:45.000Z" } ``` --- # Variables URL: /docs/api/reference/variables Plain configuration values, organization-wide and per AI team. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} ## List an AI team's variables [#list-an-ai-teams-variables] An AI team id. How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [Variable](#variable) objects. A page of variables. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "variable", "id": "var_FfWaUwQBPtssmkpHrTLrC7", "name": "DEFAULT_BRANCH", "value": "main", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:15:00.000Z", "updated_at": null } ], "has_more": false } ``` ## Create an AI team's variable [#create-an-ai-teams-variable] An AI team id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Variable](#variable) object. The variable. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"name":"STRIPE_API_KEY","value":"your-stripe-key"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'STRIPE_API_KEY', value: 'your-stripe-key' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"name": "STRIPE_API_KEY", "value": "your-stripe-key"}, ) print(res.json()) ``` ```json title="Response 201" { "object": "variable", "id": "var_FfWaUwQBPtssmkpHrTLrC7", "name": "DEFAULT_BRANCH", "value": "main", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:15:00.000Z", "updated_at": null } ``` ## Get an AI team's variable [#get-an-ai-teams-variable] An AI team id. A variable id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Variable](#variable) object. The variable. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7 \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "variable", "id": "var_FfWaUwQBPtssmkpHrTLrC7", "name": "DEFAULT_BRANCH", "value": "main", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:15:00.000Z", "updated_at": null } ``` ## Change an AI team's variable [#change-an-ai-teams-variable] An AI team id. A variable id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Variable](#variable) object. The variable. An RFC 9457 problem. ```bash curl -X PATCH https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7 \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"value":"your-new-token"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ value: 'your-new-token' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.patch( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"value": "your-new-token"}, ) print(res.json()) ``` ```json title="Response 200" { "object": "variable", "id": "var_FfWaUwQBPtssmkpHrTLrC7", "name": "DEFAULT_BRANCH", "value": "main", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:15:00.000Z", "updated_at": null } ``` ## Delete an AI team's variable [#delete-an-ai-teams-variable] An AI team id. A variable id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Done. An RFC 9457 problem. ```bash curl -X DELETE https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7 \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(res.status); ``` ```python import os import uuid import requests res = requests.delete( "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.status_code) ``` Done. ## List organization variables [#list-organization-variables] How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [Variable](#variable) objects. A page of variables. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/variables \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/variables', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/variables", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "variable", "id": "var_FfWaUwQBPtssmkpHrTLrC7", "name": "DEFAULT_BRANCH", "value": "main", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:15:00.000Z", "updated_at": null } ], "has_more": false } ``` ## Create an org variable [#create-an-org-variable] A key restricted to some AI teams creates only `selected` variables, for teams inside its restriction (an org-wide one is 403 team_restricted, another team 404). Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. One of `org`, `selected`. With `scope: selected` only. **Returns** a [Variable](#variable) object. The variable. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/variables \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"name":"GITHUB_TOKEN","value":"your-github-token"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/variables', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'GITHUB_TOKEN', value: 'your-github-token' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/variables", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"name": "GITHUB_TOKEN", "value": "your-github-token"}, ) print(res.json()) ``` ```json title="Response 201" { "object": "variable", "id": "var_FfWaUwQBPtssmkpHrTLrC7", "name": "DEFAULT_BRANCH", "value": "main", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:15:00.000Z", "updated_at": null } ``` ## Get an organization variable [#get-an-organization-variable] A variable id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Variable](#variable) object. The variable. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/variables/var_FfWaUwQBPtssmkpHrTLrC7 \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/variables/var_FfWaUwQBPtssmkpHrTLrC7', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/variables/var_FfWaUwQBPtssmkpHrTLrC7", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "variable", "id": "var_FfWaUwQBPtssmkpHrTLrC7", "name": "DEFAULT_BRANCH", "value": "main", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:15:00.000Z", "updated_at": null } ``` ## Change an org variable's value [#change-an-org-variables-value] A variable id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Variable](#variable) object. The variable. An RFC 9457 problem. ```bash curl -X PATCH https://api-hq.aiworkforceone.com/v1/variables/var_FfWaUwQBPtssmkpHrTLrC7 \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"value":"your-new-token"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/variables/var_FfWaUwQBPtssmkpHrTLrC7', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ value: 'your-new-token' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.patch( "https://api-hq.aiworkforceone.com/v1/variables/var_FfWaUwQBPtssmkpHrTLrC7", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"value": "your-new-token"}, ) print(res.json()) ``` ```json title="Response 200" { "object": "variable", "id": "var_FfWaUwQBPtssmkpHrTLrC7", "name": "DEFAULT_BRANCH", "value": "main", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:15:00.000Z", "updated_at": null } ``` ## Delete an org variable [#delete-an-org-variable] A variable id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Done. An RFC 9457 problem. ```bash curl -X DELETE https://api-hq.aiworkforceone.com/v1/variables/var_FfWaUwQBPtssmkpHrTLrC7 \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/variables/var_FfWaUwQBPtssmkpHrTLrC7', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(res.status); ``` ```python import os import uuid import requests res = requests.delete( "https://api-hq.aiworkforceone.com/v1/variables/var_FfWaUwQBPtssmkpHrTLrC7", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.status_code) ``` Done. ## Objects [#objects] ### Variable [#variable] One of `org`, `team`. ```json title="The Variable object" { "object": "variable", "id": "var_FfWaUwQBPtssmkpHrTLrC7", "name": "DEFAULT_BRANCH", "value": "main", "scope": "org", "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"], "created_at": "2026-09-02T10:15:00.000Z", "updated_at": null } ``` --- # Webhooks URL: /docs/api/reference/webhooks Signed HTTPS callbacks for your organization's events, their delivery log, retries and replays, and the events list. Verify every delivery with a Standard Webhooks library. {/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */} ## List webhook endpoints [#list-webhook-endpoints] Newest first. A secret is never returned; `secret_prefixes` names the ones that sign. How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). Only endpoints in this state. One of `enabled`, `disabled`, `auto_disabled`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [WebhookEndpoint](#webhookendpoint) objects. A page of webhook endpoints. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/webhook_endpoints \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/webhook_endpoints", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "webhook_endpoint", "id": "we_CTJtkIwMC3hOmcKEGLjbN8", "url": "https://hooks.example.com/hq", "description": "Ops alerts", "enabled_events": ["operation.failed", "session.*"], "team_ids": null, "include_message_text": false, "api_version": "2026-11-01", "status": "enabled", "disabled_reason": null, "failing_since": null, "last_success_at": "2026-10-14T16:05:34.000Z", "secret_prefixes": ["whsec_MfKQ"], "created_at": "2026-10-02T12:00:00.000Z", "updated_at": "2026-10-02T12:00:00.000Z" } ], "has_more": false } ``` ## Create a webhook endpoint [#create-a-webhook-endpoint] The URL must be `https`, on port 443 or 8443, with a host name that resolves only to public addresses (`422 host_not_allowed` otherwise, also when the name does not resolve). The response carries the signing `secret` ONCE: store it now. Every owner and admin of the organization is emailed. A trial organization cannot create endpoints. A retry with the same `Idempotency-Key` answers `201` with the same endpoint, without `secret` and with `secret_omitted: true` (the secret is never stored for a replay). If the first answer was lost, roll the secret (`POST …/rotate_secret`). A key restricted to some AI teams cannot do this (403 team_restricted). Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Send the message text in event bodies. Turning it on needs `sessions:chat.read` in the key's scopes AND held for every AI team by the key's member (a service key: its role); `403 permission_denied` otherwise. **Returns** a [WebhookEndpointWithSecret](#webhookendpointwithsecret) object. The endpoint, with its signing secret (shown once). An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_endpoints \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "url": "https://hooks.example.com/hq", "enabled_events": ["operation.failed", "session.*"] }' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ url: 'https://hooks.example.com/hq', enabled_events: ['operation.failed', 'session.*'], }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/webhook_endpoints", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={ "url": "https://hooks.example.com/hq", "enabled_events": ["operation.failed", "session.*"], }, ) print(res.json()) ``` ```json title="Response 201" { "object": "webhook_endpoint", "id": "we_CTJtkIwMC3hOmcKEGLjbN8", "url": "https://hooks.example.com/hq", "description": "Ops alerts", "enabled_events": ["operation.failed", "session.*"], "team_ids": null, "include_message_text": false, "api_version": "2026-11-01", "status": "enabled", "disabled_reason": null, "failing_since": null, "last_success_at": "2026-10-14T16:05:34.000Z", "secret_prefixes": ["whsec_MfKQ"], "created_at": "2026-10-02T12:00:00.000Z", "updated_at": "2026-10-02T12:00:00.000Z", "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSwXc4tB1vN", "secret_omitted": false } ``` ## Get a webhook endpoint [#get-a-webhook-endpoint] A webhook endpoint id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [WebhookEndpoint](#webhookendpoint) object. The endpoint. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8 \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "webhook_endpoint", "id": "we_CTJtkIwMC3hOmcKEGLjbN8", "url": "https://hooks.example.com/hq", "description": "Ops alerts", "enabled_events": ["operation.failed", "session.*"], "team_ids": null, "include_message_text": false, "api_version": "2026-11-01", "status": "enabled", "disabled_reason": null, "failing_since": null, "last_success_at": "2026-10-14T16:05:34.000Z", "secret_prefixes": ["whsec_MfKQ"], "created_at": "2026-10-02T12:00:00.000Z", "updated_at": "2026-10-02T12:00:00.000Z" } ``` ## Update a webhook endpoint [#update-a-webhook-endpoint] Change the URL, the subscriptions, the team filter or the description, or turn the endpoint off (`status: disabled`) and back on (`status: enabled`, which ends a failure run). A new URL is checked like a new endpoint, and the admins are emailed. A key restricted to some AI teams cannot do this (403 team_restricted). A webhook endpoint id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Send the message text in event bodies. Turning it on needs `sessions:chat.read` in the key's scopes AND held for every AI team by the key's member (a service key: its role); `403 permission_denied` otherwise. One of `enabled`, `disabled`. **Returns** a [WebhookEndpoint](#webhookendpoint) object. The endpoint. An RFC 9457 problem. ```bash curl -X PATCH https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8 \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "enabled_events": ["operation.failed", "session.*", "schedule.*"] }' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ enabled_events: ['operation.failed', 'session.*', 'schedule.*'] }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.patch( "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"enabled_events": ["operation.failed", "session.*", "schedule.*"]}, ) print(res.json()) ``` ```json title="Response 200" { "object": "webhook_endpoint", "id": "we_CTJtkIwMC3hOmcKEGLjbN8", "url": "https://hooks.example.com/hq", "description": "Ops alerts", "enabled_events": ["operation.failed", "session.*"], "team_ids": null, "include_message_text": false, "api_version": "2026-11-01", "status": "enabled", "disabled_reason": null, "failing_since": null, "last_success_at": "2026-10-14T16:05:34.000Z", "secret_prefixes": ["whsec_MfKQ"], "created_at": "2026-10-02T12:00:00.000Z", "updated_at": "2026-10-02T12:00:00.000Z" } ``` ## Delete a webhook endpoint [#delete-a-webhook-endpoint] Its secrets and its delivery log go with it. A key restricted to some AI teams cannot do this (403 team_restricted). A webhook endpoint id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Deleted. An RFC 9457 problem. ```bash curl -X DELETE https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8 \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.delete( "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.json()) ``` ```json title="Response 200" { "object": "webhook_endpoint", "id": "we_CTJtkIwMC3hOmcKEGLjbN8", "deleted": true } ``` ## Roll the signing secret [#roll-the-signing-secret] A new secret, shown ONCE. The old one keeps signing for `previous_secret_expires_in` seconds (default 86400, at most 604800; 0 stops it now), so deliveries carry two `v1,` signatures until it expires. A key restricted to some AI teams cannot do this (403 team_restricted). A webhook endpoint id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. The endpoint, with its new signing secret (shown once). An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/rotate_secret \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"previous_secret_expires_in":86400}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/rotate_secret', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ previous_secret_expires_in: 86400 }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/rotate_secret", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"previous_secret_expires_in": 86400}, ) print(res.json()) ``` ```json title="Response 200" { "object": "webhook_endpoint", "id": "we_CTJtkIwMC3hOmcKEGLjbN8", "url": "https://hooks.example.com/hq", "description": "Ops alerts", "enabled_events": ["operation.failed", "session.*"], "team_ids": null, "include_message_text": false, "api_version": "2026-11-01", "status": "enabled", "disabled_reason": null, "failing_since": null, "last_success_at": "2026-10-14T16:05:34.000Z", "secret_prefixes": ["whsec_MfKQ"], "created_at": "2026-10-02T12:00:00.000Z", "updated_at": "2026-10-02T12:00:00.000Z", "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSwXc4tB1vN", "secret_omitted": false, "previous_secret_expires_in": 86400 } ``` ## Send a test event [#send-a-test-event] Sends `webhook.test` to this endpoint only. The delivery shows in its log. A key restricted to some AI teams cannot do this (403 team_restricted). A webhook endpoint id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [WebhookDelivery](#webhookdelivery) object. The queued delivery. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/test \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/test', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/test", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.json()) ``` ```json title="Response 202" { "object": "webhook_delivery", "id": "whd_HK1MFIerlfCsPIS4tzvsJI", "endpoint_id": "we_CTJtkIwMC3hOmcKEGLjbN8", "event": { "id": "evt_9OvoJuvytSGhqe71vQ9tqx", "type": "session.turn.completed" }, "status": "succeeded", "attempt_count": 1, "next_attempt_at": null, "last_attempt_at": "2026-10-14T16:05:34.000Z", "last_response_status": 200, "last_error_code": null, "last_latency_ms": 184, "replay_of": null, "succeeded_at": "2026-10-14T16:05:34.000Z", "created_at": "2026-10-14T16:05:33.000Z" } ``` ## Replay events to an endpoint [#replay-events-to-an-endpoint] Re-sends the events of a window (at most 30 days back) as new deliveries with their original `webhook-id`. Returns an operation; one replay per endpoint at a time. A key restricted to some AI teams cannot do this (403 team_restricted). A webhook endpoint id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. Default now. Event types or namespaces (`session.*`). Default the endpoint's subscriptions. **Returns** a [Operation](#operation) object. The operation that tracks the replay. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/replay \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"since":"2026-10-13T00:00:00.000Z"}' ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/replay', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json', }, body: JSON.stringify({ since: '2026-10-13T00:00:00.000Z' }), }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/replay", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, json={"since": "2026-10-13T00:00:00.000Z"}, ) print(res.json()) ``` ```json title="Response 202" { "object": "operation", "id": "op_pgDHKopuDeR6aX2GPYNtx5", "kind": "webhook_endpoint.replay", "status": "running", "target": { "type": "webhook_endpoint", "id": "we_CTJtkIwMC3hOmcKEGLjbN8" }, "requested": { "since": "2026-10-13T00:00:00.000Z" }, "error": null, "created_by": { "kind": "service_key", "key": "key_ff7QejQ24AGmu5tv2IXIdw", "label": "CI deploy bot" }, "created_at": "2026-10-14T16:10:00.000Z", "updated_at": "2026-10-14T16:10:00.000Z", "completed_at": null } ``` ## List an endpoint's deliveries [#list-an-endpoints-deliveries] The delivery log, newest first, for 30 days. A webhook endpoint id. How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). Only deliveries in this state. One of `pending`, `sending`, `succeeded`, `failed`, `dead`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [WebhookDelivery](#webhookdelivery) objects. A page of deliveries. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/deliveries \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/deliveries', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/deliveries", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "object": "webhook_delivery", "id": "whd_HK1MFIerlfCsPIS4tzvsJI", "endpoint_id": "we_CTJtkIwMC3hOmcKEGLjbN8", "event": { "id": "evt_9OvoJuvytSGhqe71vQ9tqx", "type": "session.turn.completed" }, "status": "succeeded", "attempt_count": 1, "next_attempt_at": null, "last_attempt_at": "2026-10-14T16:05:34.000Z", "last_response_status": 200, "last_error_code": null, "last_latency_ms": 184, "replay_of": null, "succeeded_at": "2026-10-14T16:05:34.000Z", "created_at": "2026-10-14T16:05:33.000Z" } ], "has_more": false } ``` ## Get a delivery [#get-a-delivery] With every attempt and up to 4 KiB of the receiver's last response. A webhook endpoint id. A webhook delivery id. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [WebhookDeliveryDetail](#webhookdeliverydetail) object. The delivery. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/deliveries/whd_HK1MFIerlfCsPIS4tzvsJI \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/deliveries/whd_HK1MFIerlfCsPIS4tzvsJI', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/deliveries/whd_HK1MFIerlfCsPIS4tzvsJI", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "webhook_delivery", "id": "whd_HK1MFIerlfCsPIS4tzvsJI", "endpoint_id": "we_CTJtkIwMC3hOmcKEGLjbN8", "event": { "id": "evt_9OvoJuvytSGhqe71vQ9tqx", "type": "session.turn.completed" }, "status": "succeeded", "attempt_count": 1, "next_attempt_at": null, "last_attempt_at": "2026-10-14T16:05:34.000Z", "last_response_status": 200, "last_error_code": null, "last_latency_ms": 184, "replay_of": null, "succeeded_at": "2026-10-14T16:05:34.000Z", "created_at": "2026-10-14T16:05:33.000Z", "last_response_snippet": "{\"ok\":true}", "attempts": [ { "at": "2026-10-14T16:05:34.000Z", "status": 200, "latency_ms": 184, "error_code": null } ] } ``` ## Retry a delivery [#retry-a-delivery] A new delivery of the same event (the same `webhook-id`), due now. A key restricted to some AI teams cannot do this (403 team_restricted). A webhook delivery id. Makes a retry safe: the same key and body within 24 hours returns the first response again (`Idempotent-Replayed: true`); the same key with another body is 422. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [WebhookDelivery](#webhookdelivery) object. The new delivery. An RFC 9457 problem. ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_deliveries/whd_HK1MFIerlfCsPIS4tzvsJI/retry \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" \ -H "Idempotency-Key: $(uuidgen)" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_deliveries/whd_HK1MFIerlfCsPIS4tzvsJI/retry', { method: 'POST', headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', 'Idempotency-Key': crypto.randomUUID(), }, }); console.log(await res.json()); ``` ```python import os import uuid import requests res = requests.post( "https://api-hq.aiworkforceone.com/v1/webhook_deliveries/whd_HK1MFIerlfCsPIS4tzvsJI/retry", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", "Idempotency-Key": str(uuid.uuid4()), }, ) print(res.json()) ``` ```json title="Response 202" { "object": "webhook_delivery", "id": "whd_HK1MFIerlfCsPIS4tzvsJI", "endpoint_id": "we_CTJtkIwMC3hOmcKEGLjbN8", "event": { "id": "evt_9OvoJuvytSGhqe71vQ9tqx", "type": "session.turn.completed" }, "status": "succeeded", "attempt_count": 1, "next_attempt_at": null, "last_attempt_at": "2026-10-14T16:05:34.000Z", "last_response_status": 200, "last_error_code": null, "last_latency_ms": 184, "replay_of": null, "succeeded_at": "2026-10-14T16:05:34.000Z", "created_at": "2026-10-14T16:05:33.000Z" } ``` ## List events [#list-events] The organization's events of the last 30 days, newest first. An event is recorded only while an endpoint subscribes to its type. How many objects to return, 1 to 100. Default 20. Return objects older than this id (the next page). Return objects newer than this id (the previous page). An event type, or a namespace such as `session.*`. A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a list of [Event](#event) objects. A page of events. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/events \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/events', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/events", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "object": "list", "data": [ { "id": "evt_9OvoJuvytSGhqe71vQ9tqx", "object": "event", "type": "session.turn.completed", "api_version": "2026-11-01", "created_at": "2026-10-14T16:05:33.000Z", "org_id": "org_3SvwLF4ulih8bHz5KtmNOO", "team_id": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "resource": { "type": "session", "id": "sess_0a843Y2wTmED2k3FJPP56X" }, "data": { "session_id": "sess_0a843Y2wTmED2k3FJPP56X" } } ], "has_more": false } ``` ## Get an event [#get-an-event] An event id (the `webhook-id` of its deliveries). A dated API version. Defaults to the version the key was created with. Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with `400 invalid_request` on any other credential. A slug that is not one of your agency's current clients is `404 not_found`. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (`limit_scope: agency_client`), separate from the client's own keys. **Returns** a [Event](#event) object. The event. An RFC 9457 problem. ```bash curl https://api-hq.aiworkforceone.com/v1/events/evt_9OvoJuvytSGhqe71vQ9tqx \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "HQ-Version: 2026-11-01" ``` ```js const res = await fetch('https://api-hq.aiworkforceone.com/v1/events/evt_9OvoJuvytSGhqe71vQ9tqx', { headers: { Authorization: `Bearer ${process.env['HQ_API_KEY']}`, 'HQ-Version': '2026-11-01', }, }); console.log(await res.json()); ``` ```python import os import requests res = requests.get( "https://api-hq.aiworkforceone.com/v1/events/evt_9OvoJuvytSGhqe71vQ9tqx", headers={ "Authorization": f"Bearer {os.environ['HQ_API_KEY']}", "HQ-Version": "2026-11-01", }, ) print(res.json()) ``` ```json title="Response 200" { "id": "evt_9OvoJuvytSGhqe71vQ9tqx", "object": "event", "type": "session.turn.completed", "api_version": "2026-11-01", "created_at": "2026-10-14T16:05:33.000Z", "org_id": "org_3SvwLF4ulih8bHz5KtmNOO", "team_id": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "resource": { "type": "session", "id": "sess_0a843Y2wTmED2k3FJPP56X" }, "data": { "session_id": "sess_0a843Y2wTmED2k3FJPP56X" } } ``` ## Objects [#objects] ### WebhookEndpoint [#webhookendpoint] A URL that receives your organization's events, signed (Standard Webhooks v1). Event types and namespaces (`session.*`) this endpoint receives. Only events of these AI teams (organization events always pass). Null is every team. A key restricted to some AI teams sees only its own teams here, and does not see an endpoint limited to other teams at all. Event bodies carry the message text. The version event bodies are rendered at, pinned at creation. One of `enabled`, `disabled`, `auto_disabled`. One of `manual`, `gone_410`, `continuous_failure`, `null`. The display prefixes of the secrets that sign right now (two during a rotation). ```json title="The WebhookEndpoint object" { "object": "webhook_endpoint", "id": "we_CTJtkIwMC3hOmcKEGLjbN8", "url": "https://hooks.example.com/hq", "description": "Ops alerts", "enabled_events": ["operation.failed", "session.*"], "team_ids": null, "include_message_text": false, "api_version": "2026-11-01", "status": "enabled", "disabled_reason": null, "failing_since": null, "last_success_at": "2026-10-14T16:05:34.000Z", "secret_prefixes": ["whsec_MfKQ"], "created_at": "2026-10-02T12:00:00.000Z", "updated_at": "2026-10-02T12:00:00.000Z" } ``` ### WebhookEndpointWithSecret [#webhookendpointwithsecret] ```json title="The WebhookEndpointWithSecret object" { "object": "webhook_endpoint", "id": "we_CTJtkIwMC3hOmcKEGLjbN8", "url": "https://hooks.example.com/hq", "description": "Ops alerts", "enabled_events": ["operation.failed", "session.*"], "team_ids": null, "include_message_text": false, "api_version": "2026-11-01", "status": "enabled", "disabled_reason": null, "failing_since": null, "last_success_at": "2026-10-14T16:05:34.000Z", "secret_prefixes": ["whsec_MfKQ"], "created_at": "2026-10-02T12:00:00.000Z", "updated_at": "2026-10-02T12:00:00.000Z", "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSwXc4tB1vN", "secret_omitted": false } ``` ### WebhookDelivery [#webhookdelivery] One event sent (or to be sent) to one endpoint, with its retries. One of `pending`, `sending`, `succeeded`, `failed`, `dead`. ```json title="The WebhookDelivery object" { "object": "webhook_delivery", "id": "whd_HK1MFIerlfCsPIS4tzvsJI", "endpoint_id": "we_CTJtkIwMC3hOmcKEGLjbN8", "event": { "id": "evt_9OvoJuvytSGhqe71vQ9tqx", "type": "session.turn.completed" }, "status": "succeeded", "attempt_count": 1, "next_attempt_at": null, "last_attempt_at": "2026-10-14T16:05:34.000Z", "last_response_status": 200, "last_error_code": null, "last_latency_ms": 184, "replay_of": null, "succeeded_at": "2026-10-14T16:05:34.000Z", "created_at": "2026-10-14T16:05:33.000Z" } ``` ### Operation [#operation] A change the reconcilers carry out. It settles as succeeded or failed. Open-ended: computer.start, computer.stop, computer.update, computer.resize, webhook_endpoint.replay. running, succeeded or failed. ```json title="The Operation object" { "object": "operation", "id": "op_pgDHKopuDeR6aX2GPYNtx5", "kind": "computer.resize", "status": "running", "target": { "type": "team", "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd" }, "requested": { "tier": "boost" }, "error": null, "created_by": { "kind": "service_key", "key": "key_ff7QejQ24AGmu5tv2IXIdw", "label": "CI deploy bot" }, "created_at": "2026-10-14T16:10:00.000Z", "updated_at": "2026-10-14T16:10:04.000Z", "completed_at": null } ``` ### WebhookDeliveryDetail [#webhookdeliverydetail] ```json title="The WebhookDeliveryDetail object" { "object": "webhook_delivery", "id": "whd_HK1MFIerlfCsPIS4tzvsJI", "endpoint_id": "we_CTJtkIwMC3hOmcKEGLjbN8", "event": { "id": "evt_9OvoJuvytSGhqe71vQ9tqx", "type": "session.turn.completed" }, "status": "succeeded", "attempt_count": 1, "next_attempt_at": null, "last_attempt_at": "2026-10-14T16:05:34.000Z", "last_response_status": 200, "last_error_code": null, "last_latency_ms": 184, "replay_of": null, "succeeded_at": "2026-10-14T16:05:34.000Z", "created_at": "2026-10-14T16:05:33.000Z", "last_response_snippet": "{\"ok\":true}", "attempts": [ { "at": "2026-10-14T16:05:34.000Z", "status": 200, "latency_ms": 184, "error_code": null } ] } ``` ### Event [#event] One event, on a session's stream, in a webhook delivery's body, and in the events list. Stable across reconnects. Deduplicate on it. ```json title="The Event object" { "id": "evt_9OvoJuvytSGhqe71vQ9tqx", "object": "event", "type": "session.turn.completed", "api_version": "2026-11-01", "created_at": "2026-10-14T16:05:33.000Z", "org_id": "org_3SvwLF4ulih8bHz5KtmNOO", "team_id": "team_3kQ9vX2mR8tLpZ4wYc1aBd", "resource": { "type": "session", "id": "sess_0a843Y2wTmED2k3FJPP56X" }, "data": { "session_id": "sess_0a843Y2wTmED2k3FJPP56X" } } ``` --- # Python SDK URL: /docs/api/sdks/python The HQ API for Python, with retries, idempotency, a resumable event stream and webhook verification built in. The package is not on PyPI yet; this page shows how it will work. Until it is, call the API as in the [quickstart](/docs/api/quickstart/). `aiworkforceone-hq` runs on Python 3.9+ and uses the standard library only. ```bash pip install aiworkforceone-hq ``` ## Authenticate [#authenticate] ```python from aiworkforceone_hq import HQ hq = HQ() # reads HQ_API_KEY; or HQ(api_key="hq_live_…") ``` `api_key` takes an [API key](/docs/api/authentication/) or an [OAuth app](/docs/api/oauth/)'s access token. ## Send a prompt and stream the reply [#send-a-prompt-and-stream-the-reply] ```python s = hq.sessions.create("team_3kQ9…", engine="claude", run_with="team_key") hq.sessions.messages.create(s.id, content=[{"type": "text", "text": "Summarise open PRs in /data/repo"}]) for ev in hq.sessions.stream(s.id): if ev.type == "session.message.completed": print(ev.data) if ev.type == "session.turn.completed": break ``` Objects are dicts you can also read by attribute: `s.id` or `s["id"]`. ## What it does for you [#what-it-does-for-you] **Retries.** A `429`, a `5xx` or a dropped connection is retried with backoff (`max_retries`, default 2), honouring `Retry-After`. A `421` is retried once at once. Any other `4xx` raises at once. **Idempotency.** Every write carries an `Idempotency-Key`, the same one across its own retries. Pass `idempotency_key=` to use yours. **Errors.** A refusal raises `HQError` with the stable [`code`](/docs/api/errors/), `status`, `detail` and `request_id`: ```python from aiworkforceone_hq import HQError try: hq.sessions.create("team_3kQ9…", run_with="team_key") except HQError as err: if err.code != "permission_denied": raise print(err.permission) ``` **Streaming.** `sessions.stream(id)` yields each [event](/docs/api/streaming/) once, resumes with `Last-Event-ID` across `stream.rotate` and dropped connections, and yields `stream.reset` when you should re-list the session's items. **Operations.** `operations.wait(op)` polls an [operation](/docs/api/operations/) until it settles: ```python op = hq.computer.resize("team_3kQ9…", tier="boost") if op.get("object") == "operation": hq.operations.wait(op) ``` **Pagination.** `teams.list()` and `sessions.list()` iterate every page. **Webhooks.** Verify a delivery with the raw body: ```python event = HQ.webhooks.verify(request.body, request.headers, os.environ["HQ_WEBHOOK_SECRET"]) ``` **Everything else.** `hq.call("operationId", {"path_param": "…"}, query=..., body=...)` reaches any endpoint in the [reference](/docs/api/reference/). --- # TypeScript SDK URL: /docs/api/sdks/typescript The HQ API for TypeScript and JavaScript, with retries, idempotency, a resumable event stream and webhook verification built in. The package is not on npm yet; this page shows how it will work. Until it is, call the API with `fetch` as in the [quickstart](/docs/api/quickstart/). `@aiworkforceoneofficial/hq-sdk` runs on Node 20+, Deno, Bun and workers, with no runtime dependencies. ```bash npm install @aiworkforceoneofficial/hq-sdk ``` ## Authenticate [#authenticate] ```ts import { HQ } from '@aiworkforceoneofficial/hq-sdk'; const hq = new HQ({ apiKey: process.env.HQ_API_KEY }); ``` `apiKey` takes an [API key](/docs/api/authentication/) or an [OAuth app](/docs/api/oauth/)'s access token. Without it, the SDK reads `HQ_API_KEY`. Each client pins the `HQ-Version` the SDK was built for; pass `apiVersion` to pin another. ## Send a prompt and stream the reply [#send-a-prompt-and-stream-the-reply] ```ts const session = await hq.sessions.create('team_3kQ9…', { engine: 'claude', run_with: 'team_key' }); await hq.sessions.messages.create(session.id!, { content: [{ type: 'text', text: 'Summarise open PRs in /data/repo' }], }); for await (const ev of hq.sessions.stream(session.id!)) { if (ev.type === 'session.message.completed') console.log(ev.data); if (ev.type === 'session.turn.completed') break; } ``` ## What it does for you [#what-it-does-for-you] **Retries.** A `429`, a `5xx` or a dropped connection is retried with backoff (`maxRetries`, default 2\), honouring `Retry-After`. A `421` is retried once at once. Any other `4xx` is thrown at once. **Idempotency.** Every write carries an `Idempotency-Key`, the same one across its own retries, so a retry never sends a prompt twice or resizes a machine twice. Pass `{ idempotencyKey }` to use yours. **Errors.** A refusal throws an `HQError` with the stable [`code`](/docs/api/errors/), the `status`, the `detail` and the `requestId`: ```ts import { HQError } from '@aiworkforceoneofficial/hq-sdk'; try { await hq.sessions.create('team_3kQ9…', { run_with: 'team_key' }); } catch (err) { if (err instanceof HQError && err.code === 'permission_denied') console.log(err.permission); else throw err; } ``` **Streaming.** `sessions.stream(id)` yields each [event](/docs/api/streaming/) once, resumes with `Last-Event-ID` across `stream.rotate` and dropped connections, and yields `stream.reset` when you should re-list the session's items. Pass `{ signal }` to stop it. **Operations.** A Cloud Computer change answers an [operation](/docs/api/operations/); `operations.wait(op)` polls it until it settles, honouring `Retry-After`: ```ts const op = await hq.computer.resize('team_3kQ9…', { tier: 'boost' }); if (op.object === 'operation') await hq.operations.wait(op); ``` **Pagination.** `teams.list()` and `sessions.list()` are async iterators over every page. **Webhooks.** Verify a delivery with the raw body: ```ts const event = await HQ.webhooks.verify(rawBody, req.headers, process.env.HQ_WEBHOOK_SECRET!); ``` **Everything else.** `hq.call('operationId', { path_param: '…' }, { query, body })` reaches any endpoint in the [reference](/docs/api/reference/), and every schema is exported as a type. --- # Sessions and prompts URL: /docs/api/sessions-and-prompts Start a session, send it a prompt, follow the delivery, answer its questions. ## Start a session [#start-a-session] ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_…/sessions \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"name":"Nightly triage","engine":"claude","run_with":"team_key"}' ``` `201` with the session and its `Location`. `run_with` chooses whose Claude account it runs on: * `team_key`: the AI team's own key. Needs `sessions:run_with_team_key`. * `personal`: the person a **user key** acts as signs in with their own account. A service key has no person, so it cannot create one (`422 personal_login_not_available`). `start`, `stop`, `restart`, rename (`PATCH`) and `DELETE` work like the buttons in HQ. ## Send a prompt [#send-a-prompt] ```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":"Summarise the open pull requests"}]}' ``` `202` with a **message**: the prompt's delivery, never its text. HQ types it into the session when the session is ready, waking a sleeping machine first. Follow it with `GET /v1/sessions/{session_id}/messages/{message_id}`, or on the [event stream](/docs/api/streaming/) as `session.message.status_changed`. | `status` | Meaning | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `accepted`, `queued` | Waiting. `waiting_for` says what for: `wake`, `ready` or `moment`. | | `typing`, `submitted` | Being typed, then sent. | | `delivered` | It is in the session. `delivered_item` is its item id. | | `blocked_by_moment` | The session is asking something first. Answer it, and the prompt goes in. This includes a message from another Claude session that is waiting to be delivered or denied: someone answers it in the session's terminal in HQ. There is no item or action for it in the API yet. | | `unconfirmed` | It may have been typed, but HQ could not confirm it within 5 minutes. Read the items before sending it again. | | `failed` | `code` says why (below). | Common `code` values on a `failed` prompt: | `code` | Meaning | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `login_required` | The session is signed out of Claude. Its owner signs in from the session in HQ, then send again. HQ says so as soon as it knows, without waiting out the 5 minutes. | | `not_running` | The session is stopped. Start it first. | | `wake_timeout` | The Cloud Computer did not wake within 5 minutes. | | `reconnecting` | HQ could not reach the running session within 5 minutes. Send again. | | `forbidden` | The key may no longer type into this session. | A prompt is typed **at most once**. HQ never retypes one on its own, so a retry of the same request with the same `Idempotency-Key` answers with the same message. The text is typed as written, up to 16 KB, exactly as if it were sent from the chat in HQ. ## Answer a question [#answer-a-question] When the session asks something (a permission, a plan to approve, a multiple-choice question), the stream sends `session.input_required` with its `instance_id`, `digest` and options. When `answerable_via_api` is true, answer with the choice you want: ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_…/actions \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"instance_id":"…","digest":"…","choice_id":"…"}' ``` `digest` names the exact question you saw: if the session has moved on, the answer is refused rather than landing on a different question. Other kinds of prompt stay in HQ. `POST /v1/sessions/{session_id}/interrupt` stops what the session is doing, like pressing Esc. ## Who may type into a session [#who-may-type-into-a-session] | Session | Who may send prompts and answers | | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | Signed in with a person's own Claude account (`personal`) | **Only a user key of that person.** Never another member, an admin, the owner or a service key: it is their account. | | On the AI team's key (`team_key`) | Any key with `sessions:type` and `sessions:run_with_team_key` on that team. | | Codex | Only a user key of the person signed in. | Anyone else gets `403 session_not_owned` or `403 permission_denied`. Reading a session (`items`, the stream) follows `sessions:chat.read` and the team's session visibility. ## Read what happened [#read-what-happened] `GET /v1/sessions/{session_id}/items` pages through the conversation (`after` / `before` cursors). A tool call or a thinking block carries a `detail_ref`; pass it to `GET /v1/sessions/{session_id}/items/{item_id}/detail?ref=…` for the full, masked detail. --- # Streaming a session URL: /docs/api/streaming Follow a session live with server-sent events, and resume after a disconnect. `GET /v1/sessions/{session_id}/events` is a [server-sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html) stream of what happens in a session: its messages, tool calls, questions and state. Opening it never wakes the machine. ```bash curl -N https://api-hq.aiworkforceone.com/v1/sessions/sess_…/events \ -H "Authorization: Bearer $HQ_API_KEY" ``` ``` id: c1.… event: session.message.completed data: {"id":"evt_…","object":"event","type":"session.message.completed","api_version":"2026-11-01","created_at":"…","org_id":"org_…","team_id":"team_…","resource":{"type":"session","id":"sess_…"},"data":{…}} ``` Every event's `data` is an event object: `id` (the same for the same event on every stream, so you can drop a duplicate; a prompt that returns to a status, for example `typing` again after `queued`, is a new event with a new `id`), `type`, `api_version`, `created_at`, the organization, team and session it belongs to, and `data`. ## Events [#events] | `type` | When | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `session.message.completed` | A user or assistant message, with its text. | | `session.tool_use.started`, `.completed`, `.failed` | A tool call, with a summary and a `detail_ref`. | | `session.thinking.completed` | A thinking block (its content through the item detail). | | `session.notice` | A system notice in the conversation: `kind` and `text`. A message from another Claude session (a teammate or helper session) is a notice with `kind: "peer_message"` and a short `text` such as `Message from another session (release-check): Tests passed`, without the message itself. Routine status messages that arrive together are one notice, such as `3 status updates from another session (release-check)`. A message Claude holds until the person decides is a notice with `kind: "peer_held"`; the session's `session.input_required` (`kind: "peer_hold"`, `answerable_via_api: false`, no message text, and the fixed title `A message from another session is waiting`, never the name the sender gives itself) says it is waiting for a person in HQ. A background job the session started that finished is a notice with `kind: "background_job"` and one line of `text`, such as `Background job finished: Run the tests (exit code 0)`, or `Helper finished: Check the notes` for a helper Claude ran in the background. | | `session.status` | The session's state changed: `ready`, `busy`, `asleep` and so on. | | `session.turn.completed` | The session finished answering (`busy` became `ready`). | | `session.input_required` | The session is asking something. See [Sessions and prompts](/docs/api/sessions-and-prompts/). | | `session.message.status_changed` | A prompt you sent moved on (`delivered`, `unconfirmed`, …). | | `stream.rotate` | Reconnect now (the server is restarting, or the stream is 50 minutes old). | | `stream.reset` | You fell behind or the conversation was reset: read `/items` again, then reconnect. With `reason: "unauthorized"`, the key may no longer follow this session (it was revoked, its person lost access, the team's visibility changed): do not reconnect with it. | A comment line (`: ping`) every 15 seconds keeps the connection open through proxies. ## Resume after a disconnect [#resume-after-a-disconnect] The last event of each batch carries an SSE `id`. Reconnect with it in `Last-Event-ID` (EventSource does this for you), or as `?after=`, and you get what you missed, then the live stream: ```bash curl -N https://api-hq.aiworkforceone.com/v1/sessions/sess_…/events \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "Last-Event-ID: c1.…" ``` On `stream.rotate`, reconnect the same way, after the `retry` delay the stream announced (1 second). ## Limits [#limits] * Up to 4 open streams per session, and a per-plan number per organization ([Rate limits](/docs/api/rate-limits/)). One more is refused with `429 too_many_streams`. * A stream needs `sessions:chat.read` on the session's team, and follows the team's session visibility. It is checked again every minute, and at once when access changes in HQ. --- # Versioning URL: /docs/api/versioning How dated HQ-Version headers keep your integration stable. The API has a major version in the URL (`/v1`) and a **dated version** in the `HQ-Version` header, for example `2026-11-01`. ## How a version is chosen [#how-a-version-is-chosen] * A key is **pinned** to the newest version when it is created. * A request can ask for another known version by sending `HQ-Version: 2026-11-01`. * An unknown date answers `400 invalid_request`, with the current version in its `HQ-Version` header. * Every response says which version served it, in its own `HQ-Version` header. ## What changes without a new version [#what-changes-without-a-new-version] These are additive and never break a careful client: * a new endpoint; * a new optional field on an object; * a new optional query parameter; * a new value in a field we document as open-ended (for example a session `status`). Write your code to ignore fields it does not know and to handle values it has not seen. ## What needs a new version [#what-needs-a-new-version] Anything else: removing or renaming a field, changing a type, making a parameter required, changing what an endpoint does. Those ship under a new dated version, listed in the [changelog](/docs/api/changelog/), and your pinned keys keep the old behaviour until you move them. ## The major version [#the-major-version] `/v1` is supported for at least 24 months after a `/v2` exists. See the [deprecation policy](/docs/api/deprecation-policy/). --- # Webhooks URL: /docs/api/webhooks Get a signed HTTPS request when something happens in HQ, verify it, and recover from failures. A webhook endpoint is a URL of yours that HQ calls when an event happens in your organization: a reply to your prompt finished, an operation settled, a secret changed. Every request is signed, so your receiver can prove it came from HQ. ## 1. Add an endpoint [#1-add-an-endpoint] In HQ, open **Settings, Developers, Webhooks** and choose **Add endpoint**, or call the API with a key that holds `webhooks:manage`: ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_endpoints \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://hooks.example.com/hq", "enabled_events": ["session.*", "operation.failed"] }' ``` ```json { "object": "webhook_endpoint", "id": "we_…", "url": "https://hooks.example.com/hq", "enabled_events": ["operation.failed", "session.*"], "status": "enabled", "secret_prefixes": ["whsec_MfKQ"], "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw…" } ``` * **The `secret` is shown once.** Store it in your secret manager. HQ cannot show it again; if you lose it, roll it. A retry with the same `Idempotency-Key` answers the same endpoint without `secret`, with `secret_omitted: true`. * The URL must use `https`, port 443 or 8443, and a host name that resolves only to public addresses (otherwise, or when the name does not resolve, `422 host_not_allowed`). HQ checks it again before every delivery. * Subscribe to exact types (`session.turn.completed`) or a whole namespace (`session.*`). * `team_ids` limits the endpoint to some AI teams. Organization events (API keys, webhooks) still arrive. A key restricted to some AI teams cannot manage endpoints (`403 team_restricted`); reading, it sees only its own teams in `team_ids` and only the deliveries and events about its teams. * `include_message_text: true` sends the message text in event bodies. Turning it on needs a key with `sessions:chat.read`, made by someone who holds it for every AI team (an owner or admin). * Every owner and admin of your organization is emailed when an endpoint is added or its URL changes. * An organization on a trial cannot add endpoints. Each plan allows a number of endpoints. ## 2. Verify every delivery [#2-verify-every-delivery] Each delivery is a `POST` of one event with three headers, following [Standard Webhooks](https://www.standardwebhooks.com/): | Header | Value | | ------------------- | ------------------------------------------------------------------------------------- | | `webhook-id` | The event id (`evt_…`). It stays the same across retries and replays. | | `webhook-timestamp` | When this attempt was sent, in Unix seconds. | | `webhook-signature` | `v1,`, or two of them separated by a space while a secret is being rolled. | The signature is a base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{raw body}`, keyed by the base64 part of your `whsec_` secret. Use a Standard Webhooks library rather than writing the check yourself: ```ts import { Webhook } from 'standardwebhooks'; const wh = new Webhook(process.env.HQ_WEBHOOK_SECRET!); app.post('/hq', express.raw({ type: 'application/json' }), (req, res) => { let event; try { // Throws on a bad signature or a timestamp more than 5 minutes away. event = wh.verify(req.body.toString('utf8'), req.headers); } catch { return res.status(400).end(); } res.status(204).end(); // answer quickly, then do the work handle(event); }); ``` ```python from standardwebhooks.webhooks import Webhook wh = Webhook(os.environ["HQ_WEBHOOK_SECRET"]) event = wh.verify(request.get_data(as_text=True), request.headers) ``` * Verify the **raw** body, before any JSON parsing or reformatting. * Refuse a timestamp more than 5 minutes from your clock. * Every request also carries `HQ-Event-Type`, `HQ-Delivery-Id` and `User-Agent: AIWorkforceOne-Webhooks/1`. ## 3. The event [#3-the-event] The body is the same envelope `GET /v1/events/{event_id}` returns: ```json { "id": "evt_…", "object": "event", "type": "session.turn.completed", "api_version": "2026-11-01", "created_at": "2026-11-03T08:01:12.000Z", "org_id": "org_…", "team_id": "team_…", "resource": { "type": "session", "id": "sess_…" }, "data": { "session_id": "sess_…", "message_id": "msg_…", "last_item_id": "item_…" } } ``` Payloads are thin: ids, names and statuses, never a secret value or transcript text. Read the details you need with the API. | Type | When | | ---------------------------------------------------- | ------------------------------------------------------------------------------- | | `session.turn.completed` | The reply to a prompt you sent with `POST /v1/sessions/{id}/messages` finished. | | `session.message.status_changed` | That prompt moved (`typing`, `delivered`, `unconfirmed`, `failed`, …). | | `operation.completed`, `operation.failed` | A Cloud Computer operation or a webhook replay settled. | | `secret.created`, `secret.updated`, `secret.deleted` | A secret changed. The name and scope only. | | `api_key.created`, `api_key.revoked` | An API key was created or revoked. | | `webhook_endpoint.disabled` | One of your endpoints was switched off. | | `webhook.test` | You pressed Test, or called `POST /v1/webhook_endpoints/{id}/test`. | **Delivery is at least once, and order is not guaranteed.** Deduplicate on `webhook-id`, and use `created_at` to ignore an update older than one you already have. ## 4. Retries and failures [#4-retries-and-failures] Answer with any `2xx` within 15 seconds. Anything else is retried, about 3 days in all: * immediately, then after 5 seconds, 5 minutes, 30 minutes, 2, 5, 10, 14, 20 and 24 hours (each with some jitter); * a `Retry-After` on a `429` or `503` is honoured, up to 1 hour; * a redirect is never followed, and counts as a failure; * after the tenth attempt the delivery gives up (`dead`). You can retry it from the log. If an endpoint answers **`410 Gone`**, it is switched off at once. If every delivery fails for a day, your owners and admins get an email; after **5 days** of failures the endpoint is switched off, they are emailed again, and your other endpoints receive `webhook_endpoint.disabled`. Turning an endpoint back on is up to you (`PATCH /v1/webhook_endpoints/{id}` with `"status": "enabled"`, or **Turn on** in HQ). Then replay what it missed. ## 5. The delivery log, retries and replays [#5-the-delivery-log-retries-and-replays] ```bash # what happened curl https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_…/deliveries \ -H "Authorization: Bearer $HQ_API_KEY" # send one again (same webhook-id) curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_deliveries/whd_…/retry \ -H "Authorization: Bearer $HQ_API_KEY" # send everything from a window again (at most 30 days back); returns an operation curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_…/replay \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "since": "2026-11-02T00:00:00Z", "types": ["session.*"] }' ``` The log keeps 30 days: every attempt's status code, time and error, and up to 4 KiB of what your receiver answered last. Events are kept 30 days too, and `GET /v1/events` lists them. An event is recorded only while an endpoint subscribes to its type. ## 6. Roll the secret [#6-roll-the-secret] ```bash curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_…/rotate_secret \ -H "Authorization: Bearer $HQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "previous_secret_expires_in": 86400 }' ``` The new `secret` is shown once. For `previous_secret_expires_in` seconds (up to 7 days; `0` ends it now) every delivery carries both signatures, so you can update your receiver without missing one. ## Sending addresses [#sending-addresses] Deliveries come from Google Cloud addresses that can change, so there is no fixed list to allowlist yet: the signature is what proves a request is from HQ. Ask us if you need fixed addresses. --- # Billing and plans URL: /docs/billing See your plan and usage, change plan, add AI Teams, Boosts and storage, update your card, get invoices and cancel. Owners and admins manage billing. Open **Billing** in the sidebar. **Plan & add-ons** shows your plan, when it renews and what you use. **Usage** and **Storage** show the details. **Manage in Stripe** opens your payment method and invoices. ## Plans [#plans] Plans differ in how many AI Teams and people you can have, how many schedules, how much storage and how long the audit log is kept: | Plan | AI Teams | People | Schedules | Storage | Audit log | | ------------ | -------- | --------- | --------- | ------- | --------- | | Solo | 1 | Just you | 5 | 20 GB | 7 days | | Starter | 2 | Up to 2 | 10 | 40 GB | 7 days | | Growth | 3 | Up to 5 | Unlimited | 120 GB | 30 days | | Professional | 5 | Unlimited | Unlimited | 300 GB | 90 days | Professional also includes one [Boost](/docs/ai-teams/cloud-computers/) and custom [roles](/docs/people/roles/). Billing shows the current prices; annual billing gives you 2 months free. ## Your trial [#your-trial] Every plan starts with a 14-day free trial, with 1 AI Team for 1 person. Your plan's full limits start when your paid plan does. During the trial you can't change plan or buy add-ons: select **Start paid plan now** to end the trial early and charge your card for the plan. ## Change plan [#change-plan] Under **Change plan**, select the plan you want. An upgrade is charged today for the rest of the billing period. A downgrade takes effect now, with no refund. Switch between monthly and annual billing the same way. Your organization has to fit the plan you move down to. For example, to move from Professional to Growth you need 5 people or fewer: remove people under **People** first. On Growth you can then buy seats to add people again. When you move up to Professional, any seats you bought on Growth are removed from your bill, because Professional has no limit on people. The unused part of those seats is credited on the same invoice as the upgrade. ## Add-ons [#add-ons] Add capacity without changing plan: * **Additional AI Team:** each one adds 60 GB of storage and 5 concurrent sessions. * **Boost, Boost Pro and Boost Max:** a bigger Cloud Computer for one team. See [Cloud Computer sizes and Boost](/docs/ai-teams/cloud-computers/). * **Storage** and, on Growth, **seats**. Professional includes unlimited people, so it has no seats to buy. Additions are charged today, prorated to the day. Removals credit your next invoice. ## Payment method and invoices [#payment-method-and-invoices] Select **Manage in Stripe** to change your card and download invoices. ## Cancel [#cancel] Select **Cancel subscription** and confirm. Cancelling a trial ends it right away. Cancelling a paid plan keeps your organization running to the end of the billing period. In both cases your organization's data is then erased, so ask for a [data export](/docs/security/data-export/) first if you want a copy. Owners and admins see billing, change the plan and buy add-ons. Only owners change the payment method and cancel. ## Related [#related] --- # Changelog URL: /docs/changelog What is new, improved and fixed in AI Workforce One HQ, the hq CLI and the VS Code extension, newest first. What changed in HQ, the `hq` CLI and the AI Workforce One HQ extension for VS Code, newest first. Dates are in US Eastern time. * **VS Code extension:** every version's notes are on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items/aiworkforceone.awo-hq/changelog) and on [Open VSX](https://open-vsx.org/extension/aiworkforceone/awo-hq/changes). To update, see [Install the extension](/docs/vscode/install/). * **hq CLI:** each release is listed below on the day it came out. To update, see [Install the CLI](/docs/cli/install/). * **HQ API:** changes to the API are listed in the [API changelog](/docs/api/changelog/). ## October 29, 2026 [#october-29-2026] ### Fixed [#fixed] * The browser view no longer pauses after 30 minutes while your AI Employee is using the browser. If it did pause, it now comes back by itself as soon as your AI Employee uses the browser again, without reloading the page. ## October 25, 2026 [#october-25-2026] ### Fixed [#fixed-1] * A Cloud Computer that stayed on for more than about a week could stop opening new sessions and the Files panel, showing "Couldn't start the Cloud Computer" while its running sessions kept working. Its clock now stays correct for as long as it runs. A Cloud Computer picks this up the next time it restarts. ## October 24, 2026 [#october-24-2026] ### Fixed [#fixed-2] * A scheduled run no longer restarts a session that has its terminal open. The run is skipped, you are notified, and the terminal and the work in it are left as they are. * When a job uses up a Cloud Computer's memory, that job is now stopped instead of the Cloud Computer's own services. * Opening a session just as its Cloud Computer was going to sleep no longer leaves the terminal disconnected for a minute or more after the Cloud Computer is back. The session reconnects within seconds of waking. * **hq CLI 0.3.2 and VS Code extension 0.4.2:** waking a Cloud Computer of 80 GB and up from `hq up`, `hq attach`, `hq forward` or VS Code no longer gives up after 3 minutes. They now wait up to 4 minutes, as long as these sizes can take to wake. They also stop with HQ's message, instead of retrying, when a connection already has as many sessions open as HQ allows. * Saving a team as a template and connecting your ChatGPT account no longer stop after 2 minutes while a Cloud Computer of 80 GB and up is still waking. They wait up to 4 minutes and carry on by themselves once it is back. * Saving a team as a template and connecting your ChatGPT account also wait long enough for a large Cloud Computer set up for your organization by contract, and for one moved to a smaller size that has not restarted yet and still runs at its larger size. * Chat now lists the tools Claude loaded when you open a "Loaded tools" card. ## October 23, 2026 [#october-23-2026] ### New [#new] * Larger Cloud Computers, up to 128 GB of memory or 128 processor cores, are now available on request. Contact support and we can turn them on for your organization. ### Improved [#improved] * When your Cloud Computer is on the largest size and runs short of memory or processor, HQ now tells you that bigger sizes are available and links to support. * Every Cloud Computer size runs more sessions at once: 5 on Standard, 12 on Boost, 24 on Boost Pro and 40 on Boost Max, and 40 to 68 on the larger sizes. * When a team's Cloud Computer is too busy for another session (memory nearly full, or the processor working at full capacity), HQ now says so in plain words and suggests stopping a session or moving the team to a bigger size, instead of slowing every session down. ### Fixed [#fixed-3] * Run now on a schedule whose Cloud Computer was asleep now wakes the Cloud Computer and runs the prompt, instead of failing after five and a half minutes. * A scheduled run into a brand-new session, or the first run after `/clear`, is no longer reported as not delivered when Claude did reply. * A scheduled run no longer stops when Claude asks "Resume this conversation?" on a session that has been idle for a while. HQ now resumes the same conversation and the run continues, and anything you had typed but not sent stays where it was. * Waking a large Cloud Computer (80 GB and up) no longer stops at 2 minutes with a Retry button. The session page keeps waiting up to 4 minutes and connects by itself when the Cloud Computer is back, and anything you typed while it woke is sent then. ## October 22, 2026 [#october-22-2026] ### Improved [#improved-1] * Schedule run details now say clearly when the target session was deleted, when a run is waiting for the input box, and when a run failed. * Reassigning a session can now move its schedules to the new owner, and a schedule stopped by a reassign can be moved with one click. * On a phone, the Profile and People tabs now scroll to show the tab you are on. * Session pages and the terminal open faster on a first visit in Chrome, Edge and other Chromium browsers. * The app loads faster on a first visit, especially on slower connections. * Chat now shows which tools Claude loaded instead of a generic tool card. ### Fixed [#fixed-4] * On a narrow screen, the Browser View address bar now shortens a long site name from its start, and shortens `http://` and a port number before the site name, so the end of the name stays visible, and a site that is not secure is marked. * You can now invite someone again after their earlier invitation expired. * When your Cloud Computer's processor stays fully busy for more than about ten minutes, or it runs short of memory, HQ now suggests a bigger size as intended. Before, the suggestion often did not appear. * Scheduled runs now continue a long, idle conversation automatically instead of stopping at Claude's resume question. * When Claude asks whether to resume a long, idle conversation, Chat now shows the question with a **Resume** button for the person who types in the session. To start a new conversation instead, use the terminal. * Only the person a schedule runs as can now change its prompt or the session it runs in, also on a schedule that starts a new session each run. * Reloading a session page while Claude is working no longer leaves the terminal blank with "Couldn't restore the previous screen". The screen comes back with any secret hidden, in plain text until Claude redraws it. * The browser view now stays open when you reload the page, and it keeps reconnecting by itself while HQ is being updated instead of closing. * Sign-in tokens printed in a Codex session's terminal are now hidden reliably, even when they arrive in pieces. * Upgrading your plan, buying add-ons and starting a paid plan early on a higher plan now work with a card your bank asks you to confirm. HQ opens Stripe's secure payment page for the confirmation instead of saying the card was declined, and nothing changes until the payment goes through. * A team secret is now also hidden in the terminal when Claude wraps a long value onto the next line, including when you reload or reopen the session. * Secrets are now also hidden in colored terminal output (for example from grep, bat or jq) and when a long sign-in token wraps over several lines on a narrow screen. * API keys and sign-in tokens are now also hidden when they wrap onto several lines in the terminal. * A saved secret is now also hidden in the terminal when coloured output (for example from grep) highlights part of it. * A secret you change or delete now stays hidden in older session history and transcripts, however many times it changed. Deleting a secret always works. * A downloaded session history now keeps hiding a secret that was changed many times while the session was running. * A paused or closed account now shows the same clear notice on every page, and a closed account is no longer told its data was already erased. * On a closed account, People → Roles and a member's People page now show the account notice instead of a loading error. * Reactivating your account with a card that needs your bank's confirmation (3D Secure) now takes you to a secure Stripe page to confirm, instead of saying the card was declined. * New Cloud Computers no longer show an "Update available" notice for Claude Code right after they start. * Long feedback typed into a plan or question card is no longer cut short. * An AI Team role no longer lists permissions only an organization role can hold, such as deleting AI Teams, so **All** no longer stops the role from saving. * The role editor's "selected" count now counts only the permissions it shows. * The action filter in the audit log and the Roles screens no longer list actions and permissions for features your organization does not have. * Removing someone's access to a shared session now stops their view within 30 seconds. * A session whose start was interrupted no longer stays on Starting; it now shows as failed with a retry. * A Cloud Computer no longer goes to sleep while a program on it is still busy using the processor. * Stopping and quickly starting a team no longer leaves its earlier sessions looking like they are still running. * On a tablet, reloading a session with Browser View open no longer shows a garbled terminal for a few seconds. * The Claude sign-in panel now closes by itself after you sign in, in every permission mode. ## October 21, 2026 [#october-21-2026] ### Improved [#improved-2] * The details of a scheduled run now read in plain words. They say what happened and what you can do about it, for example when a message is waiting for approval or the session is not signed in. ### Fixed [#fixed-5] * Restarting a session on a paused team no longer stops it. * A message from another session that Claude is holding now gets **Deliver** and **Deny** in Chat on every device, also when it is long or contains quotes or brackets. Before, Chat showed only the live screen for those. Chat shows the part of the message Claude previews, says how much of it that is, and **Deliver** sends the whole message. * In Chat, **Open Terminal**, **Show details**, **Try again** and **Dismiss** are now easy to tap on a phone and a tablet. * After `/exit`, the kept screen no longer shows Claude's command menu or a "claude --resume" line that can't be used in HQ. * When you turn down a plan, Chat now says "You didn't approve the plan" and marks the plan "not approved", instead of "Claude was interrupted" and "it did not work". * When you stop Claude or say no to a permission, Chat now says you stopped it and marks the step "stopped by you", instead of "Claude was interrupted" and "it did not work". * On a tablet, **Restart** and the close button in a session's list of notices are now easy to tap, as on a phone. * If a Cloud Computer can't load its latest settings when it starts, Docker now stays off unless HQ last allowed it, and the Docker card says why. Sessions keep working, and **Restart Cloud Computer** tries again. See [Docker](/docs/cli/docker/). * When you turn down a plan with feedback in **Tell Claude what to change**, Chat now marks the plan "not approved" instead of "it did not work". * On a tablet, the **Send** button in Chat and the notice buttons at the top of the page are now easy to tap. * When you stop Claude from writing or changing a file, Chat now says "Did not write" or "Did not change" that file, instead of saying it was written. ## October 20, 2026 [#october-20-2026] ### Improved [#improved-3] * Cloud Computers now come with ffmpeg and unzip preinstalled, so video and archive tools work after every restart. * When the AI Employee ends a session itself, for example after `/exit`, the terminal keeps its last output on screen with **Start** ready, instead of switching to the stopped screen. * A long build in a terminal session now keeps the Cloud Computer awake while it is using the processor, even when it prints nothing for a while. See [When a Cloud Computer sleeps](/docs/ai-teams/sleep/). * A schedule prompt can no longer contain hidden control characters (tabs and line breaks are fine), so a scheduled run always sends exactly the text you see. * You can now tell Claude what to change about a plan right in Chat. Under **Approve plan**, type your changes in **Tell Claude what to change** and press **Send**. Claude keeps planning with your feedback and shows you a new plan. * Scheduled runs show Success only when Claude actually received the prompt and started on it. Otherwise the run says what happened instead, for example that Claude did not take the prompt, the session was unavailable, a message was waiting for approval, or the usage limit was reached. ### Fixed [#fixed-6] * Chat and schedules no longer refuse to send after Claude replies with a table. * Answering a question with your own text in Chat no longer sends an earlier answer by mistake, and typing a new answer over an old one now replaces it completely. * When the session's terminal is narrow, as on a phone, you can now answer a question in Chat with your own longer text. Before, Chat could not read the question once your answer wrapped. * On a phone or a tablet, a message from another session that Claude is holding now shows in Chat with its **Deliver** and **Deny** buttons, like on a computer. Before, Chat showed only the live screen there. On a computer the buttons also appear sooner. * In Chat, a "Thinking…" line with nothing to open no longer stays behind once Claude's reply has moved on, so finished turns no longer pile up "Switch to Terminal to see the reasoning" lines. * When Claude reaches a usage limit, Chat shows the reset time in your own time zone instead of the Cloud Computer's (UTC). * When a Claude request fails (a usage limit, an expired login, a busy service), Chat now shows it as a highlighted notice in the conversation instead of a faint line. * On phones, the Create session button on the new session page can be reached again. ## October 19, 2026 [#october-19-2026] ### New [#new-1] * The HQ API is here. Your own code, scripts and CI jobs can now read and drive your organization at `https://api-hq.aiworkforceone.com/v1`: your AI teams, their sessions, schedules and Cloud Computers, and more, with signed webhooks when things happen. API keys are on every plan. During a trial the API can only read and you can hold one key; choose a plan to make changes. Create a key in **Profile**, **API keys**, or (owners and admins) a service key for your organization in **Settings**, **Developers**. Start with the [API overview](/docs/api/) and the [quickstart](/docs/api/quickstart/). * OAuth apps: let your own product act for people in HQ, in the organization they pick, after they approve it. Registering an app needs the Growth plan or higher. See [OAuth apps](/docs/api/oauth/). * When one of your Claude sessions holds a message from another session (their permission modes differ), Chat says a message is waiting and shows it with **Deliver** and **Deny** buttons. The message is shown whole, as plain text. A message Chat cannot show whole and unchanged (a long one, or one with a session address in it) is answered in the terminal instead, where you can read all of it. Nothing is delivered until you choose, and a message nobody answers expires after a few minutes (the sender is told it was declined). ### Improved [#improved-4] * AI Employees now know you can watch their browser in HQ. When the browser is on for a team, a new session tells your AI Employee that you can follow along in **Open the browser**, to say what it is doing, to ask you to do any sign-in step yourself, and never to ask for a password or a code in the chat. See [Browser View](/docs/sessions/browser-view/). * AI Employees now know where to install tools on a Cloud Computer so they are still there after a restart, an update or a wake from sleep, and that the machine has no `sudo` or `apt`. This applies to new sessions. * In Chat, a note from another Claude session names it by its name only, never by its internal address, and opening a note no longer repeats its first line when the line already fits. Several "Thinking…" lines in a row now show as one line that opens to all of it, and a helper's card says what it was asked in plain words. * When Claude asks to fetch a web page, Chat shows the address and **Allow** / **Don't allow** buttons instead of the terminal screen. * When Claude has a plan ready, Chat shows an **Approve plan** button. Approving keeps Claude asking before each edit; it never turns on auto mode. To change the plan, answer it in the terminal. * When Claude cannot answer in Chat, it now says why and what to do: Claude is busy, you reached a usage limit (and when it resets), your Claude login expired, the conversation is too long, or the connection dropped. A job Claude ran in the background now shows a short line in Chat when it finishes. ### Fixed [#fixed-7] * Tools installed in the wrong folder on a Cloud Computer now fail right away with a clear message instead of disappearing at the next restart. Install your own tools in your home folder, which is kept: see [Storage](/docs/ai-teams/storage/#what-is-kept-when-the-cloud-computer-restarts). * Claude's questions and permission prompts show as buttons in Chat again. * Messages from your other Claude sessions now show as a short note in Chat instead of raw text. * Stopping a turn, from Chat or the API, no longer declines a message from another session that Claude is holding for you. While one waits, Stop does nothing and you answer the message first. * In Chat, your message now always shows above Claude's reply to it. Some replies showed above the message they answered. * HQ now answers a malformed request with a clear error instead of a server error. * On iPhone and iPad, the Files panel keeps keyboard focus inside it while open. * On phones and tablets, screen readers again read out notices and status updates during a session, also while the Files panel is open. * On small phones, the schedule frequency choices (Once, Daily, Weekdays and so on) are no longer cut off: a choice that does not fit moves to a second row. * On an iPad held upright, the note next to **Change plan** on the Billing page now wraps instead of running off the card. * When control of the browser returns to your AI Employee after 30 minutes, the browser view now says so, instead of only "Control returned to the AI Employee." The same goes for the other reasons control ends, such as 5 minutes without activity. * On a team that keeps each member's work separate, the browser of a session on your own Claude login no longer says other members of the team can reach it. That browser runs in your own part of the Cloud Computer. * Saved sign-ins: **Last used** now changes only when a sign-in is actually used in a browser session. * A schedule no longer types into a session that is waiting for you to deliver or deny a message from another Claude session. The run now shows as **Not run** with the reason, and you're notified once until the message is answered. Before, the scheduled prompt was lost and the waiting message was declined. Chat and the API hold your message the same way, and Chat says where to answer. See [Schedules](/docs/schedules/#when-a-session-is-waiting-on-a-message). ## October 18, 2026 [#october-18-2026] ### New [#new-2] * Take control of your AI Employee's browser: select **Take control** under the live view to click, type and scroll in the page yourself, then **Hand back** and your AI Employee carries on. Only the session's owner can take control of a session on their own Claude login. See [Browser View](/docs/sessions/browser-view/). * **Needs you:** when your AI Employee needs you to sign in, enter a code, solve a CAPTCHA or confirm something in the browser, it asks at the top of the session and waits. Select **Open the browser**, do the step and hand it back, so your password never goes through the chat. * When a page in the browser asks for a file, you can choose files from your session's files and attach them, while you have control. Secret files and keys are never offered. * Saved browser sign-ins: sign in to a site once and your AI Employee's browser stays signed in across sessions and restarts. Sign-ins are encrypted and kept per person and per team, and you can sign out of one site or clear everything in the team's **Settings**. ### Fixed [#fixed-8] * Stopping a Cloud Computer with Docker turned on is faster: stopping it, letting it sleep or deleting its team no longer waits about a minute and a half for Docker to shut down. Your containers are still given time to stop cleanly. * On a phone, when a session stops unexpectedly while you have it open, **Start** now shows at the top of the page, so you can start it again without opening the status menu. * Screen readers no longer reach the closed file list on phones and tablets. ## October 17, 2026 [#october-17-2026] ### Improved [#improved-5] * The sidebar now says how many sessions are running in a plain sentence, kept apart from your storage. * HQ works better on phones and tablets: forms no longer zoom in on iPhone, the Secrets and Variables tables fit small screens, and buttons are easier to tap. * On phones and tablets the terminal now scrolls with momentum, like the rest of your phone. * The top of a session is now one slim bar on every screen. It shows the session's name, its team and one status you can select for **Restart**, **Stop session** and the Cloud Computer's memory and processor. On a phone, **Chat** and **Terminal** are one tap apart and everything else is under **More**, so the conversation gets more of the screen. The message box and the terminal keys are slimmer on a phone too. On a tablet, the session now fills the whole screen and the file list opens from **More**. * A session that ran out of memory now says **Out of memory** at the top, also after you reload the page. ### Fixed [#fixed-9] * When a session's AI Employee crashes while you have it open, its terminal and its last output now stay on screen, with the session marked as stopped unexpectedly and **Start** ready, instead of the screen being cleared. * A session whose agent stops during start now says it could not start, instead of asking you to update the Cloud Computer. * When a session that is not signed in to Claude crashes, the message saying it stopped unexpectedly now shows instead of staying hidden behind the Claude sign-in panel. Press **Start** and the sign-in panel comes back. * On phones, opening the keyboard in a session no longer hides the screen, and the message box and **Send** stay in view, in both Chat and the terminal. * On a touch screen with no trackpad or mouse attached, pressing Return in the Chat message box now adds a new line. Tap **Send** to send, or press Cmd+Enter (Ctrl+Enter) on a keyboard. * On iPhone, tapping the terminal in a session no longer zooms the page in. * When a message can't be sent yet because Claude is asking something on screen, Chat now says so just above the message box and keeps your message, so you can answer first. * On phones, the stopped and crashed session panels now fit the screen, and a stopped session shows **Start** without a greyed out **Stop** beside it. * On iPad in portrait, an empty file panel no longer takes space below the session. * The session's name now stays readable at the top of the page on phones and iPad. * On small phones, **Jump to latest** no longer covers the Claude sign-in steps. * The dashboard greeting now says "No sessions running" with a grey dot when nothing is running, matching the sidebar, instead of "0 sessions running" beside the green running dot. * On slower phones, flicking repeatedly through the terminal speeds up again. ## October 16, 2026 [#october-16-2026] ### Improved [#improved-6] * Professional now includes unlimited team members. There are no seats to buy on Professional, and if you move up to Professional with seats from Growth, they are removed from your bill. See [Billing and plans](/docs/billing/). * HQ now notices when Docker on an AI Team stops responding, or can no longer start containers, and offers a restart. See [Docker in a team](/docs/cli/docker/). * The **Data export** page now explains exactly what is kept when an organization is erased: each person's own sign-in account, and a recovery copy for 30 days. * The audit log now shows when a session ended on its own, for example when its AI Employee finished and exited, so a stopped session is never left unexplained. * If your role doesn't allow connecting from a computer on any AI Team, `hq attach` and the VS Code extension now tell you so right away, instead of connecting and then dropping the connection. ### Fixed [#fixed-10] * Switching a session between Claude and the terminal no longer stops it if the switch can't happen right away, for example while the AI Team's Cloud Computer is still finishing an update. The session keeps running as it was, and you can switch again once the update is done. * Changing someone's role now also ends any remote terminal they already had open (`hq attach` or the VS Code extension) if the new role no longer allows connecting from a computer. If it no longer allows it on any AI Team, their computer is unlinked from the organization and needs to be linked again once the role gives the access back. * When a role change takes away connecting from a computer, the VS Code extension now stops receiving file updates right away, instead of up to 30 seconds later. When a remote connection ends because its access was removed, the audit log now says so (reason "access lost"). * Turning off a permission in a custom role that another permission still needs now tells you which one needs it, instead of saving without the change. * New AI Teams created at the same moment in a new account could fail to start; they now start reliably. * Your organization's storage figure now lines up across the sidebar, **Billing**, and each AI Team's page and settings. Until your AI Teams' storage has been measured, they all say "Not measured yet" instead of showing 0 B. * A session whose AI Employee exits on its own now shows as stopped right away, on its page, in the **Sessions** list and in the sidebar's count of running sessions, and no longer takes up a running session slot until someone opens it again. If the AI Employee crashes instead, or is shut down because it ran out of memory, the session now shows as an error right away, so you can see it needs attention and start it again. The message shown when a session stops unexpectedly no longer says it restarts by itself: it tells you to start the session again. * A Boost bought while the Cloud Computer was updating now applies as soon as the update finishes. * After a Cloud Computer update or restart, the activity log now shows each session it brought back once, instead of twice a second apart. * Paging through the audit log and schedule run history, in HQ and in the public API, no longer skips entries recorded at the same moment. * In the public API, a date filter (`created[gte]`, `created[lte]`) with an invalid date now returns a clear `400` error instead of a server error. * When a running session's AI Employee crashes or runs out of memory, its page now says the session stopped unexpectedly (or ran out of memory) and offers **Start**, instead of saying the Cloud Computer couldn't start. * On a trial, the Boost dialog now says up front that a Boost starts with your paid plan, with a link to start it, instead of promising the Boost and then refusing it. * The order summary on **Billing** and in the Boost dialog no longer lists a $0 seats line on Professional, which includes unlimited team members. * On **Billing**, an invoice for a plan or add-on change is now labeled by the change, for example "Plan change to Professional" or "Add-on change", instead of by its first line item. ## October 15, 2026 [#october-15-2026] ### New [#new-3] * **HQ API reference.** The reference for the HQ API is now public: every endpoint with its parameters, example requests in cURL, JavaScript and Python, and example responses, plus guides for authentication, versioning, errors and SDKs. See the [API reference](/docs/api/reference/). * **Guides for HQ.** Step-by-step guides with screenshots for everything you do in HQ: a 5-minute quickstart, AI Teams and Boost, sessions, Preview, Browser View, schedules, secrets, people, billing and security. Start with [What is HQ](/docs/get-started/). The docs are now grouped under **Guides**, **Developers** and **Changelog**, and every page can be opened in Claude or ChatGPT. * **Help in HQ.** A Help menu and Learn more links take you to the right guide from the main pages. Open **Help** at the bottom of the sidebar for the docs, what's new and support. * **Custom roles.** Create roles with exactly the permissions people need, for the whole organization or for one AI Team. Start from a template or a system role, preview HQ the way a role sees it, and check why someone can or can't do something. On Professional and Enterprise plans, once a trial has converted. See [Roles and permissions](/docs/people/roles/). ### Improved [#improved-7] * Roles moved from Settings to People: open **People**, then the **Roles** tab. A person's role on **People** links to that role. Old links still work. * **hq CLI 0.3.1:** if you can no longer type in a session while `hq attach` is open, it keeps showing the session instead of exiting on your next key. What you type is not sent, and it tells you that you can only watch. * **hq CLI 0.3.1 and VS Code extension 0.4.1:** when your access to a session ends, they say "Your access to this session ended." instead of "Session not found". ### Fixed [#fixed-11] * Removing someone from an AI Team now ends their access to that team's sessions right away, including the sessions they started themselves. * Changing a stopped AI Team's Cloud Computer size now applies in one start, a sleeping team keeps its sessions while it changes size, and Restart now to apply always tells you what it did. See [Cloud Computer sizes and Boost](/docs/ai-teams/cloud-computers/). * HQ now respects each AI Team's session visibility setting everywhere. On a team set to **People see only their own sessions**, the dashboard, the team's session list, the session counts on AI Team cards and each session's own page show only the sessions you can see on the **Sessions** page. * Team owners can now open every session their team's session list shows them, as [Who can see sessions](/docs/ai-teams/settings/) describes. ## October 14, 2026 [#october-14-2026] ### New [#new-4] * **Start, stop and restart sessions from your terminal.** hq CLI 0.3.0 adds `hq sessions`, `hq start`, `hq stop` and `hq restart`, with the same rules as HQ: the session owner or a team owner can run a session. `hq stop` and `hq restart` ask first while Claude or Codex is answering. See [Sessions](/docs/cli/sessions/). * **Start, Stop and Restart in VS Code.** Extension 0.4.0 adds them to each session in the Teams view, shown only on sessions you may run. * **Disk warnings.** When an AI Team's disk is 85%, 90% or 95% full, the session header and the AI Team's card say so, measured against how far the disk can still grow, with what you can do to make room. * The Audit log shows when a session was started, stopped or restarted from the `hq` CLI, and from which computer. * **Sign out** on the organization chooser, for people who belong to more than one organization. ### Improved [#improved-8] * Waking an AI Team says how long it usually takes for its size: 15 to 30 seconds up to 16 GB, and 30 to 45 seconds from 32 GB. In HQ, the CLI and VS Code. * **Turn off browser** takes effect right away, also in sessions that are already running, and the browser stays off after the AI Team Cloud Computer sleeps, until you enable it again. * A session that is still starting shows as starting in the CLI and VS Code, instead of looking like it is already running. * The CLI says how long to wait after too many starts in a minute, for example "Too many requests. Try again in 34 seconds." * VS Code says "AI Team Cloud Computer" where it said "team machine", and an update or size change says it usually takes about 5 to 6 minutes instead of counting down. ### Fixed [#fixed-12] * The file explorer waits while a session is starting instead of reading a Cloud Computer that is still booting, stops checking after you stop the session, and no longer tries to load files while the AI Team Cloud Computer is off. ## October 13, 2026 [#october-13-2026] ### New [#new-5] * **Pooled storage.** Your organization's storage becomes one pool that its AI Teams share: a team's disk grows from the pool as it fills, and owners and admins can set a cap or a reserve for each AI Team. It is reaching organizations over the coming weeks. See [Storage for AI Teams](/docs/ai-teams/storage/). ### Improved [#improved-9] * `/tmp` and the files of the browser your AI Employees use, including downloads, now live on the AI Team's disk instead of in a small amount of memory, so large temporary files and downloads have room. Each AI Team Cloud Computer picks this up at its next update. * Opening a session on a sleeping AI Team waits up to 2 minutes for it to wake and connects by itself, and wakes are noticed sooner. * A revealed secret value is shown in full, with **Copy**, on organization and team secrets. * Start and Stop on a session show only to people who may use them. * If you belong to more than one organization and sign in from a share link, you return to the link after choosing an organization. ### Fixed [#fixed-13] * Selected text in the file editor is visible and readable. * Coming back to a browser tab with a live terminal no longer clears and redraws it. * A key typed after clicking into a session's history goes back to the live view and stays there. * A terminal could resize back and forth and show Claude Code's output twice. It no longer does. * Audit log CSV exports are safe to open in spreadsheet apps. ## October 12, 2026 [#october-12-2026] ### Fixed [#fixed-14] * Opening a template share link directly in a new tab works the first time. ## October 11, 2026 [#october-11-2026] ### New [#new-6] * **Turn off browser.** After the browser is enabled for an AI Team, **Turn off browser** removes it again. * **Open** on every row under **Other ports** in the Preview port picker. * Before an AI Team is created from a shared template, HQ lists the hooks, connectors and commands the template can run on the team's Cloud Computer, and you confirm each one. * Deleting an AI Team says what happens to its files: they are kept for 30 days in case you change your mind, then erased. Owners get an email when a deleted team's files are erased. ### Improved [#improved-10] * Session notices sit in the header controls, so the terminal no longer changes size when one appears. * HQ waits for Claude to finish printing before it resizes the terminal, so a resize no longer garbles the output. * AI Team actions show one clear pending state while they run. * On phones, **Restart** is under **More**, and the session header fits small screens. * When every session slot is busy, a scheduled run waits up to 10 minutes for a free one. A run more than 15 minutes late is skipped and the schedule moves on to its next time. * An HQ tab left open with nobody using it no longer wakes a sleeping AI Team. * A plain loading screen shows while an AI Team Cloud Computer wakes or reconnects. ### Fixed [#fixed-15] * Only an owner can remove another owner from an organization. * Deleting an AI Team with schedule run history works again. * A paid Boost is always applied, and assigning a spare Boost you already own works directly. * An upgrade is reported as done only once the size really changed, and the time left never goes up. * What you type while an AI Team Cloud Computer wakes is no longer lost. * A schedule created paused shows no next run, and an overdue run shows "due now". * Browser View shows the page once it settles, and comes back after the Cloud Computer wakes. * Text people type, such as names, always appears as plain text in HQ emails. ## October 10, 2026 [#october-10-2026] ### Improved [#improved-11] * **hq CLI 0.2.1:** `hq login --no-browser` prints the sign-in link and code instead of opening a browser (automatic on Linux without a display). After signing in, `hq` lists what to run next. `hq attach` no longer prints "connection lost" once an hour, redraws at your size when the session is also open elsewhere, and says when the session stops. ## October 9, 2026 [#october-9-2026] ### New [#new-7] * Deleting an AI Team releases its purchased Boost automatically. ### Improved [#improved-12] * Progress shows from the moment you confirm an AI Team Cloud Computer upgrade. * An AI Team whose Claude session is signed out can now sleep when idle. * The Claude Code update notice clears as soon as the restarted session is running. ### Fixed [#fixed-16] * Claude's own sign-in callback no longer shows up as an app in Preview. * Members no longer see an empty Organization heading in the sidebar. * Coming back to a tab reconnects, wakes the Cloud Computer and keeps what you typed. ## October 8, 2026 [#october-8-2026] ### New [#new-8] * **Session history.** Scroll back to the start of a session, shown exactly as it looked live. * The session header shows processor use next to memory, with a warning when the Cloud Computer is overloaded and a way to upgrade it. * Your profile has tabs for **Security** and for your personal secrets. ### Improved [#improved-13] * HQ calls the team's computer the "AI Team Cloud Computer", and agents "AI Employees". * A processor or memory warning ends as soon as it is no longer true. ## October 7, 2026 [#october-7-2026] ### New [#new-9] * **My secrets and variables.** Set personal secrets and variables, or import a `.env` file. They apply only to sessions you own that sign in with your own account, and take the place of a team or organization value with the same name. * The Preview port picker groups many listening ports so they are easy to find. ### Fixed [#fixed-17] * A secret's earlier value stays masked after the secret is changed or removed. * Session history keeps your place while it loads and keeps every line after a resize. * Signing in to Claude for the first time from the Chat tab is calmer and clearer. ## October 6, 2026 [#october-6-2026] ### Improved [#improved-14] * The file explorer loads one folder at a time, so large AI Teams open quickly. * Team owners can run their own team: rename it, update and restart its Cloud Computer, and manage who has access. Deleting sessions is for organization owners and admins. ### Fixed [#fixed-18] * People who are not admins no longer see email addresses in the reassign and share lists. ## October 5, 2026 [#october-5-2026] ### Improved [#improved-15] * A stopped session says it is stopped and shows **Start**. Opening it never starts it by itself. * A session open in two windows no longer garbles: the window you are using sets the size and the others match it. * **VS Code extension 0.2.3:** the hourly reconnect is invisible, with no keystroke lost. ## October 2, 2026 [#october-2-2026] ### New [#new-10] * **VS Code extension 0.2.1:** more than one HQ account on the same computer, one per window. * **VS Code extension 0.2.2:** paste or drop images into session terminals. * Syntax highlighting in the file editor for more than 40 languages. * An AI Team's **Variables** tab shows the organization variables the team receives. * Secrets and variables show one table per tab with a level filter, and each AI Team can import a `.env` file. ### Improved [#improved-16] * Docker storage on an AI Team Cloud Computer grows by itself as the team's disk grows. * An HQ tab counts as someone being there only while you are using it, so an idle AI Team can sleep. * AI Teams with idle MCP servers, such as Playwright, can now sleep. ## October 1, 2026 [#october-1-2026] ### New [#new-11] * **Restart Cloud Computer.** Owners and admins can restart an AI Team Cloud Computer at any time, and running sessions come back afterwards. * Preview finds ports from what is actually listening, names the Docker container behind each one, and lists services that are not websites, such as Postgres or Redis, under **Other ports**. * Changing an AI Team Cloud Computer's size brings your sessions back afterwards. * A first-run Claude sign-in card in the Chat tab. * Search in the organization picker when you belong to more than 6 organizations. ### Improved [#improved-17] * The session header names the AI Team and links to it. * The memory indicator shows the Cloud Computer's real memory. * An organization that requires two-factor authentication requires it everywhere in HQ until the second step is done, and first-time members get a setup page. ### Fixed [#fixed-19] * Session header controls work again on phones. * Dialog fields keep your cursor when the page refreshes in the background. --- # Attach to a session URL: /docs/cli/attach hq attach joins an HQ session in this terminal, streaming its output live. Only the session owner can type; everyone else watches. The person who started a session is the only one who can type in it. Everyone else who attaches watches it live, view only. To work yourself, start your own session in HQ. ## How it works [#how-it-works] Open the team in HQ: its session list shows each session's name. You can attach by that name or by the first characters of the session id. Run `hq attach `. Add `--team ` when the same name exists in more than one team. Press `Ctrl-]`. The session keeps running; you can attach again any time. ```bash # attach to a session by the start of its id hq attach 7c21e0b4 # show what you type instantly, before the round trip confirms it hq attach 7c21e0b4 --local-echo ``` ```powershell # attach to a session by the start of its id hq attach 7c21e0b4 # show what you type instantly, before the round trip confirms it hq attach 7c21e0b4 --local-echo ``` When it connects, `hq` tells you whose session it is and whether you can type: ```text Attached to "fix login bug" (Dana) · you can type · Ctrl-] to detach ``` ## Local echo [#local-echo] On a slow connection, `--local-echo` draws your keystrokes the moment you press them, instead of after the round trip to the AI Team Cloud Computer. It only applies when you can type and your terminal is a real terminal. | Setting | Behavior | | ------------------------------------- | ------------------------------------------------------------ | | `--local-echo` or `--local-echo=auto` | Echo locally only while the round trip is slower than 60 ms. | | `--local-echo=always` | Echo locally at any speed. | | `--local-echo=off` | Never. This is the default. | Set `HQ_LOCAL_ECHO=auto` in your shell profile to make it your default; the flag wins over it. Your organization has to allow local echo; when it does not, `hq` says so once and attaches without it. ## When the AI Team Cloud Computer is sleeping [#when-the-ai-team-cloud-computer-is-sleeping] Attaching usually wakes it, and `hq` prints progress while it starts: usually 15-30 seconds for a wake (30-45 seconds on Boost Max, 120-180 seconds on the sizes from 80 GB), about a minute when it has to start fresh, and it gives up after 3 minutes (4 minutes on the sizes from 80 GB). If you see `Press any key to continue.`, the Cloud Computer was not woken for you; the next key you press wakes it. HQ's connections are renewed about once an hour: `hq` moves to a fresh connection before that happens, with nothing printed and no keystroke lost. If the connection drops anyway, `hq` reconnects on its own, up to 8 times in a row. It prints `hq: connection lost, reconnecting...` only when reconnecting takes more than a few seconds or the connection drops again. ## The same session in two places [#the-same-session-in-two-places] A session has one terminal size on the AI Team Cloud Computer, and the place you are typing in sets it. When the same session is also open in HQ in your browser or in VS Code, and you type in `hq`, the session takes your terminal's size. When you switch to the other place, the session takes its size, and `hq` redraws its screen at your terminal's size so nothing overlaps. Lines the session draws after that are laid out for the other place until you type in `hq` again. If you resize your terminal while Claude Code is writing an answer, the session takes the new size when it stops writing text, and never more than 30 seconds later. That keeps the part of the answer that has already scrolled up from being drawn twice in the session's history. Your terminal resizes at once, so until the session catches up a few lines can be laid out for the old width. At a prompt the first size change applies at once. Codex sessions always change size at once. ## Related [#related] Reach a port on the AI Team Cloud Computer locally. Fixes for common attach and login errors. --- # Docker in a team URL: /docs/cli/docker Run docker, docker compose and local stacks like Supabase inside a team's sessions, and reach them with Preview or hq forward. ## Turn it on [#turn-it-on] Docker is off for every team until two things are true: 1. Support has turned Docker on for your organization. Contact support to ask; it is available to organizations on a paid plan. 2. An organization owner or admin turns it on for the team, in the team's **Settings**, under **Docker**. Turning it on asks you to confirm your password or authenticator code. The change takes effect the next time the AI Team Cloud Computer starts. Press **Restart now to apply** on the Docker card, or **Restart Cloud Computer** in the team's **AI Team Cloud Computer** settings, to apply it straight away. Running sessions pause while the Cloud Computer restarts and come back where they were. Members of the team can see whether Docker is on, but only an organization owner or admin can change it. ## Use it [#use-it] Every terminal in the team's sessions can run Docker, and so can Claude and Codex: ```bash docker run --rm hello-world docker compose up -d ``` * Keep files you mount into containers inside the team folder. Other folders are not visible to Docker. * Docker's storage starts small, as part of the team's storage, and grows when the team's Cloud Computer restarts. See [Storage](#storage). * Containers stop when the Cloud Computer restarts or updates. Images and volumes are kept. * An AI Team Cloud Computer that goes idle keeps its containers paused and resumes them intact. Running containers do not keep a Cloud Computer awake. ## Supabase [#supabase] Run the Supabase command line tool with `npx`, which needs nothing installed: ```bash npx supabase init npx supabase start ``` The services start cold, and `npx supabase start` can stop at a health check before they are ready. Run `npx supabase start --ignore-health-check`: they come up within about a minute. If it keeps stopping at a health check, set `enabled = false` under `[analytics]` in `supabase/config.toml`. The first `supabase start` pulls several large images. If it says `no space left on device`, see [Storage](#storage). ## Storage [#storage] Docker can use up to 90 % of the team's storage from the start, and that limit grows with the team's storage while the Cloud Computer runs. Docker's files count toward the team's storage only by what they really take: deleting images or volumes, or running `docker system prune`, gives the space back right away. When the team's storage gets nearly full, it grows on its own, up to the plan's limit. At the limit, Docker commands may say `no space left on device`, and if the storage stays nearly full Docker stops, so git and sessions keep working. Free some space or add storage, then restart the Cloud Computer: 1. An organization owner or admin presses **Restart Cloud Computer** on the team's **Docker** card, or in the **AI Team Cloud Computer** section of the team's **Settings**. Running sessions pause while the Cloud Computer restarts and come back where they were. 2. Run the command again. When Docker could not start because it ran out of storage, the Docker card says "Docker ran out of storage. Restart the Cloud Computer to give Docker more room." and its button reads **Restart now to apply**. It does the same restart. You can also free space with `docker system prune`. ## Open a container's app or API [#open-a-containers-app-or-api] **Preview**, in the session header, finds the ports your containers publish on its own, a few seconds after they start, and names each one after its container and image, for example `hello-web (nginx) · 4000`. Nothing has to be printed in the terminal. Open Supabase Studio (port 54323\) or the API (port 54321) from there. A port that does not answer like a web page, such as a database, is listed under **Other ports** instead. It doesn't count toward the number on the **Open preview** button, which counts only named apps. Press **Open** on its row to try it in your browser anyway. To use a port from a tool on this computer, forward it: ```bash hq forward 54321 hq forward 54323 ``` Then open `http://localhost:54323` for Studio. See [Port forwarding](/docs/cli/port-forwarding/) for the options. Ports 2375 and 2376 are the Docker API and can't be previewed or forwarded. ## Files a container created [#files-a-container-created] A container that runs as root can create files in the team folder that your sessions cannot change or delete. To take them back, run this in the folder that holds them: ```bash docker run --rm -v "$PWD":/w alpine chown -R 1000:1000 /w ``` ## If Docker isn't responding [#if-docker-isnt-responding] HQ keeps checking Docker on the team's Cloud Computer. If Docker stops answering for about a minute, the team's **Docker** card says **Docker isn't responding**. Sessions keep working, but `docker` commands fail or hang. An organization owner or admin presses **Restart Cloud Computer** on the Docker card to bring Docker back. Sessions pause while the Cloud Computer restarts and come back where they were. Your images, volumes and files are kept; running containers stop and need to be started again. HQ never restarts the Cloud Computer by itself. If Docker starts answering again on its own, the card goes back to **Docker is on**. If it keeps happening after a restart, contact support. Sometimes Docker keeps answering but can't start any container: `docker run` or `docker compose up` fail with "function not implemented". The card then says **Docker needs a restart**. Only a restart of the Cloud Computer fixes this, so press **Restart Cloud Computer** (an organization owner or admin). Don't restart Docker from a terminal: it doesn't help and can make it worse. ## If Docker didn't start [#if-docker-didnt-start] If a Cloud Computer can't load its latest settings when it starts, Docker only starts when HQ last allowed it. Otherwise the Docker card says **Docker did not start** with "Docker stayed off because the Cloud Computer couldn't load its latest settings when it started." Sessions keep working. An organization owner or admin presses **Restart Cloud Computer** to try again. ## Good to know [#good-to-know] * Containers you run with extra privileges can read or change this Cloud Computer's unencrypted network traffic, and can disconnect it until it restarts. Only run images you trust. * On most teams, everyone shares one Docker: any member, and any session's AI Employee, can see and use the team's containers, images and volumes. * On a team that keeps each member's work separate: Docker keeps each member's containers separate, but on one Cloud Computer they are separated by Linux namespaces, not by separate user ids. Each member has their own Docker, with their own containers, images and volumes. A teammate's `docker ps` doesn't show yours. Keep files you mount into containers inside the team folder: your home folder is not visible to Docker. Right after the Cloud Computer starts, each member's Docker takes about a minute to be ready. Sessions you start in that minute work without Docker, and the session says "This session started without Docker. Restart it to get Docker." Once Docker is ready, press **Restart** on that notice. If you have other sessions open, stop them first: a session gets Docker only once none of yours is still running without it. --- # CLI overview URL: /docs/cli hq connects this computer to your AI Team Cloud Computers. Sign in once, then follow sessions in your terminal and forward ports. `hq` is the command-line companion to HQ. Your AI Team Cloud Computers keep running in HQ; `hq` lets this computer reach them without copying keys or passwords around. ## What hq does [#what-hq-does] * **Sign in** with `hq login`. You approve this computer in HQ in your browser, and the login renews itself on this device. * **Attach** to an HQ session with `hq attach`. You follow it live in your own terminal; the person who started it is the only one who types. * **Forward a port** with `hq forward`, so a dev server on the AI Team Cloud Computer answers on `localhost` here. * **Start, stop and restart sessions** with `hq start`, `hq stop` and `hq restart`, and list them with `hq sessions`. The same rules as in HQ: the session owner or a team owner operates it. * **Wake a team** with `hq up`, so a sleeping Cloud Computer is ready before you attach. To work on a team's files in your editor, use the [AI Workforce One HQ extension](/docs/vscode/) for VS Code, Cursor, Windsurf or VSCodium. ## Before you start [#before-you-start] * **Node.js 20 or newer** on this computer. * **An HQ account** in at least one organization. * **Developer access on** for your organization. An organization owner turns it on in HQ, under Settings, Security, Developer access. * **Access to the team.** Attaching needs viewer, editor or owner access to the team. Port forwarding needs editor or owner access and an active plan. `hq status` shows what each team allows you. ## Quick start [#quick-start] ```bash npm i -g @aiworkforceoneofficial/hq --ignore-scripts ``` Run `hq login` and approve this computer in the browser window it opens. Run `hq status`. Each team has an `hq-…` name you use in every other command. Attach to a session with `hq attach`, or forward a port with `hq forward`. ## Next [#next] Requirements, updating, and removing hq. The device approval, and where the login is kept. Every command, flag and exit code. --- # Install URL: /docs/cli/install Install hq with npm. It needs Node.js 20 or newer, has no dependencies, and runs no install scripts. ## Install with npm [#install-with-npm] ```bash npm i -g @aiworkforceoneofficial/hq --ignore-scripts ``` ```powershell npm i -g @aiworkforceoneofficial/hq --ignore-scripts ``` The package has no dependencies and no install scripts. The flag makes npm guarantee that nothing runs during the install, for this package and anything else in the same command. Check that it worked: ```bash hq --version hq --help ``` `hq --version` prints the version, `0.3.2` at the time of writing, and `hq --help` lists the commands. See the [CLI reference](/docs/cli/reference/) for each one. ## Requirements [#requirements] * **Node.js 20 or newer**, with npm. Run `node --version` to check. * **macOS, Linux or Windows.** ## Update [#update] Run the same install command again. ```bash npm i -g @aiworkforceoneofficial/hq --ignore-scripts ``` ## Uninstall [#uninstall] Sign out first, so HQ revokes this computer's access, then remove the package. ```bash hq logout npm uninstall -g @aiworkforceoneofficial/hq ``` `hq` keeps its state in `~/.hq`. Delete it too if you want no trace left. ## Next [#next] Approve this computer in HQ. Follow an HQ session in your terminal. Fixes for install and path problems. --- # Port forwarding URL: /docs/cli/port-forwarding hq forward makes a port on the AI Team Cloud Computer reachable on this computer, for a dev server, an API or a database. ## Forward a port [#forward-a-port] In an HQ session, start whatever listens on the port, for example a dev server on port 3000. It must use a port from 1024 to 65535. ```bash hq forward 3000 ``` ```text Forwarding http://localhost:3000 -> Backend :3000 (Ctrl-C to stop) ``` Open `http://localhost:3000` in your browser, or point any tool at it. Press `Ctrl-C` in the terminal to stop forwarding. ## Options [#options] ```bash # use a different port on this computer hq forward 5173 --local 8080 # pick the team when more than one lets you forward hq forward 3000 --team hq-3f9a1c2e ``` * `--team` is optional when exactly one of your teams lets you forward ports. * The local port listens on `127.0.0.1` only, so other computers on your network cannot reach it. * A sleeping AI Team Cloud Computer is woken when the forward starts. * Every connection your browser or tool opens gets its own tunnel through HQ; the forward stays open until you stop it or your access ends. * HQ refuses some ports: the Docker API (2375 and 2376), the Node debugger (9229 and 9230), and ports the AI Team Cloud Computer uses itself. * On the AI Team Cloud Computer, a forward reaches whatever listens on that port, including another member's dev server. ## Forwarding or Preview? [#forwarding-or-preview] Preview, in the HQ web app, opens a port in your browser from HQ with nothing to install. It finds the ports your AI Team Cloud Computer is serving on its own, including Docker containers and servers that never print a URL. Use `hq forward` when a tool on this computer needs the port itself on `localhost`: a database or API client, local tests, or your own browser profile and extensions. In VS Code, the extension forwards ports too: see [Ports](/docs/vscode/ports/). ## Related [#related] Start a server from your terminal, in an HQ session. Every flag and exit code of `hq forward`. Ports, teams and refused forwards. --- # CLI reference URL: /docs/cli/reference Every hq command, its flags, an example and its exit codes. {/* Generated from cli/src/command-manifest.ts by `npm run gen:cli-docs`. Do not edit by hand. */} This page is generated from the same command list `hq --help` prints, so the two always agree. Wherever a command takes ``, use the `hq-…` name from `hq status` or the team name. ## Global flags [#global-flags] | Flag | Description | | ----------- | ------------------------------------------------------------- | | `--help` | Print the command list and exit. `-h` and `hq help` work too. | | `--version` | Print the CLI version and exit. `hq version` works too. | ## Exit code 2 [#exit-code-2] Every command exits `2` when it is missing a required argument (`hq` prints `hq: missing arguments for "…". Run hq --help.`), and `hq` exits `2` for an unknown command or when run with no command at all. The tables below list each command's other codes. ## Environment variables [#environment-variables] | Variable | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------- | | `HQ_HOST` | The HQ address every command uses, overriding the one saved at `hq login`. Must be https. | | `HQ_HOME` | Where the CLI keeps its state, device key and fallback login. Default `~/.hq`. | | `HQ_LOCAL_ECHO` | `auto`, `always` or `off` for `hq attach`. The `--local-echo` flag wins over it. | | `HQ_NO_BROWSER` | Set to `1` and `hq login` prints the sign-in link instead of opening a browser, like `--no-browser`. | | `HQ_KEYCHAIN` | Set to `file` to store the login in `~/.hq/credentials.json` (readable only by you) instead of the system keychain. | ## hq login [#hq-login] Sign this computer in with a one-time code you approve in HQ in your browser. The login is stored in the system keychain, or in `~/.hq/credentials.json` where there is none. ```bash hq login [--host ] [--no-browser] ``` **Flags** | Flag | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--host ` | The HQ address to sign in to. Defaults to `https://hq.aiworkforceone.com`, or to `HQ_HOST` when set. Only localhost may use plain `http`. | | `--no-browser` | Print the sign-in link instead of opening a browser. `hq` also skips the browser when `HQ_NO_BROWSER=1` is set, on Linux with neither `DISPLAY` nor `WAYLAND_DISPLAY`, and when its output is not a terminal. | **Examples** ```bash # Sign in to HQ. Your browser opens the approval page. hq login # Sign in to a specific HQ address. hq login --host https://hq.aiworkforceone.com # Sign in from a server or a remote shell: open the printed link on any device. hq login --no-browser ``` **Exit codes** | Code | Meaning | | ---- | ---------------------------------------------------------------------------------- | | `0` | Signed in. | | `1` | The login was denied in the browser, the code expired, or HQ could not be reached. | ## hq status [#hq-status] Show who is signed in and every team you can reach, with its `hq-…` name, whether its AI Team Cloud Computer is running, and what you may do there. ```bash hq status ``` **Examples** ```bash # List your teams and their hq-… names. hq status ``` **Exit codes** | Code | Meaning | | ---- | ------------------------------------------ | | `0` | Printed. | | `1` | Not signed in, or HQ could not be reached. | ## hq up [#hq-up] Wake a sleeping AI Team Cloud Computer and wait until it is ready (usually 15-30 seconds, 30-45 seconds on Boost Max, 120-180 seconds on the sizes from 80 GB). It waits up to 3 minutes, and up to 4 minutes on the sizes from 80 GB. ```bash hq up [--org ] ``` **Flags** | Flag | Description | | -------------- | ----------------------------------------------------------------- | | `--org ` | Only look in this organization, when you belong to more than one. | **Examples** ```bash # Wake the team with this hq-… name. hq up hq-3f9a1c2e ``` **Exit codes** | Code | Meaning | | ---- | ---------------------------------------------------------------------------------------------------------------------- | | `0` | The AI Team Cloud Computer is running. | | `1` | No such team, remote access is off, or the Cloud Computer did not wake in time (3 minutes, 4 on the sizes from 80 GB). | | `2` | No team named. | ## hq attach [#hq-attach] Join an HQ session in this terminal and follow it live. Only the session owner can type; everyone else watches. Press `Ctrl-]` to detach; the session keeps running. ```bash hq attach [--team ] [--local-echo[=auto|always|off]] [--org ] ``` **Flags** | Flag | Description | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--team ` | Only look for the session in this team (its `hq-…` name or its name). Use it when the same session name exists in two teams. | | `--local-echo[=auto\|always\|off]` | Draw what you type immediately instead of after the round trip. Bare `--local-echo` means `auto`. Wins over `HQ_LOCAL_ECHO`; off when neither is set. Your organization must allow it. | | `--org ` | Only look in this organization, when you belong to more than one. | **Examples** ```bash # Attach by the first characters of the session id. hq attach 7c21e0b4 # Attach by session name in one team, with local echo. hq attach "fix login bug" --team hq-3f9a1c2e --local-echo ``` **Exit codes** | Code | Meaning | | ---- | ----------------------------------------------------------------------------------------- | | `0` | Detached with `Ctrl-]`, or the session ended. | | `1` | No session matched (or more than one did), HQ could not be reached, or your access ended. | | `2` | No session named, or `--local-echo` was not auto, always or off. | ## hq sessions [#hq-sessions] List the sessions in your teams: the first characters of each id, its name, its team, whether it is running, who owns it, and whether you may start, stop and restart it. View-only sessions are listed too. ```bash hq sessions [--team ] [--json] [--org ] ``` **Flags** | Flag | Description | | -------------- | ----------------------------------------------------------------------------------------------------------- | | `--team ` | Only list the sessions of this team (its `hq-…` name or its name). | | `--json` | Print the result as one JSON document on stdout. Refusals are still plain text on stderr, with exit code 1. | | `--org ` | Only look in this organization, when you belong to more than one. | **Examples** ```bash # List the sessions in all your teams. hq sessions # List one team as JSON, for a script. hq sessions --team hq-3f9a1c2e --json ``` **Exit codes** | Code | Meaning | | ---- | ----------------------------------------------------------------- | | `0` | Printed (a team whose list could not be read is named on stderr). | | `1` | Not signed in, or HQ could not be reached. | ## hq start [#hq-start] Start a stopped session, by the first characters of its id or its name. A sleeping AI Team Cloud Computer wakes for it, as when you press Start in HQ. Only the session owner or a team owner can start it. ```bash hq start [--team ] [--json] [--org ] ``` **Flags** | Flag | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `--team ` | Only look for the session in this team (its `hq-…` name or its name). Use it when the same session name exists in two teams. | | `--json` | Print the result as one JSON document on stdout. Refusals are still plain text on stderr, with exit code 1. | | `--org ` | Only look in this organization, when you belong to more than one. | **Examples** ```bash # Start a session by the first characters of its id. hq start 7c21e0b4 # Start a session by name in one team. hq start "fix login bug" --team hq-3f9a1c2e ``` **Exit codes** | Code | Meaning | | ---- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | HQ is starting the session, or it was already starting or running. | | `1` | No session matched (or more than one did), you may not operate it, the team has no free session slot, or HQ refused or could not be reached. | | `2` | No session named. | ## hq stop [#hq-stop] Stop a running session. If Claude or Codex is answering in it right now, `hq` asks first; in a script, pass `--yes`. Only the session owner or a team owner can stop it. ```bash hq stop [--yes] [--team ] [--json] [--org ] ``` **Flags** | Flag | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `--yes` | Do not ask before interrupting a session that is answering. Without it, and without a terminal to ask at, `hq` refuses. | | `--team ` | Only look for the session in this team (its `hq-…` name or its name). Use it when the same session name exists in two teams. | | `--json` | Print the result as one JSON document on stdout. Refusals are still plain text on stderr, with exit code 1. | | `--org ` | Only look in this organization, when you belong to more than one. | **Examples** ```bash # Stop a session. hq stop 7c21e0b4 # Stop it without asking, even while it is answering. hq stop "fix login bug" --yes ``` **Exit codes** | Code | Meaning | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `0` | Stopped, or it was already stopped. | | `1` | No session matched (or more than one did), you may not operate it, you answered no, it is answering and there is no terminal to ask (pass `--yes`), or HQ refused or could not be reached. | | `2` | No session named. | ## hq restart [#hq-restart] Stop a session and start it again, resuming its conversation. Like `hq stop`, it asks first while the session is answering. Only the session owner or a team owner can restart it. ```bash hq restart [--yes] [--team ] [--json] [--org ] ``` **Flags** | Flag | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `--yes` | Do not ask before interrupting a session that is answering. Without it, and without a terminal to ask at, `hq` refuses. | | `--team ` | Only look for the session in this team (its `hq-…` name or its name). Use it when the same session name exists in two teams. | | `--json` | Print the result as one JSON document on stdout. Refusals are still plain text on stderr, with exit code 1. | | `--org ` | Only look in this organization, when you belong to more than one. | **Examples** ```bash # Restart a session. hq restart 7c21e0b4 ``` **Exit codes** | Code | Meaning | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `0` | HQ is restarting the session. | | `1` | No session matched (or more than one did), you may not operate it, you answered no, it is answering and there is no terminal to ask (pass `--yes`), or HQ refused or could not be reached. | | `2` | No session named. | ## hq forward [#hq-forward] Make a port on the AI Team Cloud Computer reachable at `http://localhost:` on this computer, until you press `Ctrl-C`. ```bash hq forward [--local ] [--team ] [--org ] ``` **Flags** | Flag | Description | | ---------------- | ------------------------------------------------------------------------------------------------------ | | `--local ` | The port on this computer. Defaults to the same number as the team port. It listens on 127.0.0.1 only. | | `--team ` | Which team to forward from. Optional when exactly one of your teams lets you forward ports. | | `--org ` | Only look in this organization, when you belong to more than one. | **Examples** ```bash # Reach port 3000 on the AI Team Cloud Computer at localhost:3000. hq forward 3000 # Reach port 5173 of one team at localhost:8080. hq forward 5173 --local 8080 --team hq-3f9a1c2e ``` **Exit codes** | Code | Meaning | | ---- | ---------------------------------------------------------------------------------------- | | `0` | Stopped with `Ctrl-C`. | | `1` | No team lets you forward, the local port is taken, or the forward ended on the HQ side. | | `2` | The team port is missing or not a number from 1024 to 65535, or `--local` is not a port. | ## hq logout [#hq-logout] Revoke this computer's access on HQ (in every organization) and remove the stored login. ```bash hq logout ``` **Examples** ```bash # Sign out and revoke this computer. hq logout ``` **Exit codes** | Code | Meaning | | ---- | --------------------------------------------------------------------------------------------------------------- | | `0` | Signed out. If HQ could not be reached, the login is still removed from this computer and a warning is printed. | --- # Start and stop sessions URL: /docs/cli/sessions hq sessions lists the sessions in your teams; hq start, hq stop and hq restart run them from your terminal, with the same rules as HQ. Only the session owner or a team owner can start, stop or restart a session, exactly as in HQ. Everyone else sees it in the list as view only. ## List your sessions [#list-your-sessions] `hq sessions` lists the sessions of every team you can reach: the first characters of the id, the name, the team, whether it is running, who owns it (`you` for your own), and whether you may operate it. ```text 3 sessions in 2 teams 7c21e0b4 fix login bug Backend team running you can operate 1a2b3c4d nightly Backend team stopped Ana view only 9f9f9f9f landing page Website stopped you can operate ``` Add `--team ` to list one team, by its `hq-…` name or its name. If one team's list cannot be read, `hq` names it (`hq: could not list the sessions of team "…".`) and still prints the others. ## Start, stop and restart [#start-stop-and-restart] Name a session by the first characters of its id or by its exact name, the same way as [`hq attach`](/docs/cli/attach/). Add `--team ` when the same name exists in two teams. The `rawName` a script read from `--json` works as a name too (see [Use it from a script](#use-it-from-a-script)). ```bash # start a stopped session hq start 9f9f9f9f # stop a session hq stop "fix login bug" # stop and start it again, resuming its conversation hq restart 7c21e0b4 ``` * **Start** wakes a sleeping AI Team Cloud Computer for the session, and starts one that is off, as pressing Start in HQ does. `hq` says so first, for example `hq: team "…" is sleeping. Starting the session wakes it.` It returns once HQ has accepted the start. Follow the session with `hq attach`. * **Stop** and **Restart** ask first when Claude or Codex is answering in the session right now: ```text Claude is answering in "fix login bug" right now. Stop it anyway? [y/N] ``` Anything but `y` keeps it running. In a script, or anywhere without a terminal to ask at, `hq` refuses instead and tells you to pass `--yes`. A session that is already running (for `hq start`) or already stopped (for `hq stop`) is not an error: `hq` says so and exits `0`. A session HQ is still starting says "is already starting", with the `hq attach` command to follow it: `hq` only says running once HQ lists the session as running. Every start, stop and restart is recorded in your organization's Audit log in HQ as coming from the HQ CLI, for example "Stopped a session fix login bug in Backend team from the HQ CLI on Jean's MacBook." The computer's name shows to people who can manage remote access; everyone else who can read the Audit log sees a short device id instead, such as "on device 3f2a9c1b". ## When hq says no [#when-hq-says-no] | What you see | Why | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Only the session owner or a team owner can do this. | You can watch this session but not operate it. The same sentence HQ shows. | | `hq: no session "…" you can see. Run hq sessions to list them.` | No session you can see has that name or id. | | Team "…" is running as many sessions as it can (…). Stop one of its sessions first, or give the team more room in HQ. | The team is at its session limit. | | This AI Team's Cloud Computer is busy right now, so another session could not start. Stop a session you no longer need, or move the team to a bigger size, then try again. | The team has a free slot, but its Cloud Computer is too busy (memory at 80% or more, or the processor at full capacity). | | Team "…" is paused. An owner can resume it in HQ. | The team is paused. | | This organization's plan is not active, so its sessions cannot be started or stopped. An owner can fix billing in HQ. | The plan needs attention. | | Too many requests. Try again in 34 seconds. | More than 30 starts and restarts in a minute, or a team woken too often (6 times in 10 minutes). `hq` says how long HQ asked you to wait. Stopping is never limited. | | HQ refused this request because it was not signed by this computer. That is a bug in this app, not an expired login, so signing in again will not help. Update the app and try again. | Your login is fine, but this copy of `hq` sent a change without its device signature. Update `hq`. If it keeps happening, tell us. | ## Use it from a script [#use-it-from-a-script] Add `--json` to any of the four commands to get one JSON document on stdout. Refusals stay plain text on stderr, with exit code `1`. ```bash # the ids of the sessions you may operate in one team hq sessions --team hq-3f9a1c2e --json | jq -r '.[] | select(.canOperate) | .id' # stop without asking, and read the result hq stop 7c21e0b4 --yes --json ``` Each listed session has `id`, `name`, `rawName`, `team` (`id`, `alias`, `name`, `org`), `state` (`running`, `idle`, `starting` or `stopped`; `starting` while HQ is still starting it, which can still fail), `owner`, `ownerIsMe`, `canOperate`, `canType`, `midTurn` and `engine`. A start, stop or restart prints `id`, `name`, `rawName`, `team`, `action`, `result` (`started`, `stopped`, `restarted`, `already_starting`, `already_running` or `already_stopped`) and `status`. `name` is the name as `hq` displays it: any control character (an escape sequence, a line break) is replaced with a space so it cannot change your terminal, and any bidirectional text control (such as U+202E, which would show the name reversed) is removed. The `hq sessions` table shows the same cleaned names. `rawName` is the exact name HQ holds. In the JSON, every control character in it is written as a `\uXXXX` escape, so the line `hq` prints is still safe to show. A JSON parser gives your script the exact value; print `name`, not `rawName`, to a terminal (`jq -r .rawName` would write those characters out as they are). `hq start`, `hq stop` and `hq restart` match either one. `midTurn` comes from the AI Team Cloud Computer itself, which reports whether its agent is busy. It is about the whole Cloud Computer, so while one session is answering, every running session on that team reads `true`. Every flag and exit code is in the [CLI reference](/docs/cli/reference/). --- # Sign in URL: /docs/cli/sign-in hq login signs this computer in with a one-time code that you type into HQ in your browser. No password or key ever passes through the terminal. ## Sign in [#sign-in] It asks HQ for a one-time code, prints it, and opens the approval page in your browser. ```text Opening https://hq.aiworkforceone.com/device?code=BCDF-GHJK If your browser did not open, go to https://hq.aiworkforceone.com/device and enter: BCDF-GHJK This computer: my-laptop (hq 0.3.2, macOS arm64) Waiting for approval (code expires in 10 min, Ctrl-C to cancel)... ``` Sign in to HQ if you are not already, then type the code from your terminal. The page never fills it in for you, so a link someone else sent you cannot approve their computer. Check that the computer name and system match yours, pick the organizations it may reach, and confirm with your password or your two-factor code. `hq` notices the approval within a few seconds: ```text Logged in as you@example.com · access renews automatically on this device Orgs: Acme (acme) Next: hq status see your teams and their hq-… names hq forward --team reach a port on an AI Team Cloud Computer hq attach --team join an HQ session in this terminal Or use the AI Workforce One HQ extension for VS Code. ``` Run `hq login` again for a new one. Denying the request in the browser ends the login at once. ## Sign in without a browser [#sign-in-without-a-browser] On a server, in a container or over a remote shell, run `hq login --no-browser`. `hq` prints the sign-in page and the code instead of opening a browser. Open the page on any device where you are signed in to HQ and type the code; the terminal finishes the login as usual: ```text Go to https://hq.aiworkforceone.com/device in a browser and enter: BCDF-GHJK ``` Setting `HQ_NO_BROWSER=1` does the same for every `hq login`. `hq` also skips the browser on its own where none can show: on Linux with neither `DISPLAY` nor `WAYLAND_DISPLAY` set, and when its output is not a terminal (a pipe or a script). ## Where the login is kept [#where-the-login-is-kept] * **macOS:** your login keychain. * **Linux:** the Secret Service (for example GNOME Keyring) when `secret-tool` is installed and a keyring is running. * **Windows, or Linux without a Secret Service:** `~/.hq/credentials.json`, readable only by you. `hq` tells you when it uses this file. Set `HQ_KEYCHAIN=file` to choose it yourself. The keychain protects the login with your user account, not per app: any program running as you can read it. What makes a copied login useless elsewhere is the device key `hq login` creates in `~/.hq/keys/`: HQ checks its signature on every request, and each access token lasts 15 minutes. ## Check who is signed in [#check-who-is-signed-in] ```bash hq status ``` It prints your email and every team you can reach, with its `hq-…` name. ## Sign in to another HQ address [#sign-in-to-another-hq-address] `hq` uses, in this order: the `--host` you pass to `hq login`, then `HQ_HOST` if it is set, then the address you last signed in to, and `https://hq.aiworkforceone.com` the first time. Every other command uses the saved address (or `HQ_HOST`). The address must use `https://`. ```bash hq login --host https://hq.aiworkforceone.com ``` ## Sign out [#sign-out] ```bash hq logout ``` HQ revokes this computer in every organization, and `hq` removes the stored login. ## If it fails [#if-it-fails] | Message | What to do | | ---------------------------------------------------- | -------------------------------------------------------------- | | `hq: the login was denied in the browser.` | Someone chose Deny. Run `hq login` again. | | `hq: this login code expired. Run hq login again.` | The 10 minutes ran out. Start over. | | `hq: remote access is not available on this HQ yet.` | This HQ address does not offer CLI sign-in. Check the address. | More in [Troubleshooting](/docs/cli/troubleshooting/). --- # Troubleshooting URL: /docs/cli/troubleshooting The messages hq prints, what each one means, and the fix. Every `hq` message starts with `hq:`, and `…` below stands for a team, session or organization name. ## Signing in [#signing-in] | Message | What to do | | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `hq: you are not logged in on this computer. Run hq login.` | This computer has no stored login, or you ran `hq logout`. Run `hq login`. | | `hq: your HQ login on this computer expired or was revoked. Run hq login.` | HQ no longer accepts this computer. Run `hq login`. | | `hq: your HQ login on this computer needs renewing. Run hq login.` | Run `hq login`. | | `hq: this connection was refused. Your login may have expired: run hq login.` | Same fix: run `hq login`. | | `hq: the AI Team Cloud Computer refused this computer's key. Run hq login again.` | Run `hq login`. | | `hq: the login was denied in the browser.` | Someone chose Deny on the approval page. Run `hq login` again. | | `hq: this login code expired. Run hq login again.` | The 10 minutes ran out. Start over. | | `hq: "…" must use https:// (only localhost may use http).` | Give `--host` or `HQ_HOST` an `https://` address. | | `hq: "…" is not an HQ address like https://hq.aiworkforceone.com` | Check the address: scheme, host and optional port, nothing else. | | `hq: the system keychain is not answering (no Secret Service running), so your login is stored in … (readable only by you).` | Not an error. The file is `~/.hq/credentials.json`, or `credentials.json` in the folder `HQ_HOME` names when you set it. Start your desktop keyring and sign in again if you prefer the keychain. | | `hq: no system keychain tool found, so your login is stored in … (readable only by you).` | Not an error. The file is `~/.hq/credentials.json`, or `credentials.json` in the folder `HQ_HOME` names when you set it. On Linux, install `secret-tool` (libsecret) and sign in again if you prefer the keychain. | ## Teams and access [#teams-and-access] | Message | What to do | | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `hq: no team "…" on this login. Run hq status to see your teams.` | Use the `hq-…` name or the exact team name from `hq status`. A team you were just added to shows up after you run it. | | `hq: "…" matches more than one team. Use the hq-… name from hq status.` | Two teams share the name; the `hq-…` name is unique. | | `hq: team "…" was not found. Run hq status to refresh your teams.` | The team was removed or renamed. Run `hq status` to see your teams. | | `hq: you do not have remote access to team "…".` | You need editor or owner access for forwarding (viewer is enough to attach). Ask an owner. | | `hq: remote access to this team is not allowed for you right now.` | Same cause, reported at connection time. | | `hq: remote access is not available for … yet.` | Developer access is off for that organization. An owner turns it on in HQ, under Settings, Security, Developer access. | | `hq: remote access is not available on this HQ.` | This HQ address does not offer remote access. Check the address. | | `hq: connections to AI Team Cloud Computers are not switched on for this HQ yet. Ask an owner or admin.` | Remote connections are off on this HQ. Ask an owner or admin. | ## Connecting to an AI Team Cloud Computer [#connecting-to-an-ai-team-cloud-computer] | Message | What to do | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `hq: waking team "…", this usually takes 15-30 seconds...` (30-45 seconds on Boost Max) or `hq: starting team "…" fresh (about 60 s)...` | Progress, not an error. Wait. | | `hq: team "…" did not wake within … minutes. Check it in HQ and try again.` (3 minutes, 4 on the sizes from 80 GB) | Open the team in HQ to see its state, then try again. | | `hq: team "…" has no running Cloud Computer. Open the team in HQ and start a session to start it.` | The Cloud Computer is off, not sleeping. `hq up` only wakes a sleeping Cloud Computer; starting a session in HQ starts it. | | `hq: the AI Team Cloud Computer is not available right now.` | Try again in a moment, or open the team in HQ. | | `hq: the AI Team Cloud Computer went to sleep.` | It idled out. Run `hq up ` and connect again. | | `hq: team "…" runs an older Cloud Computer image without remote access.` | A team owner (or an organization owner or admin) updates the Cloud Computer: the team's Settings → Update Cloud Computer. | | `hq: this AI Team Cloud Computer needs an update before it accepts this connection. An owner or admin can update it in HQ.` | Same fix. | | `hq: team "…" cannot forward ports yet: its AI Team Cloud Computer started before Developer access was turned on. Restart the AI Team Cloud Computer, then try again.` | Developer access was turned on while the Cloud Computer was running. An owner or admin presses **Restart Cloud Computer** in the **Cloud Computer** section of the team's Settings in HQ. Sessions pause and come back where they were. This usually takes about 5 to 6 minutes. | | `hq: too many connection attempts right now. Wait a minute and try again.` | Wait a minute. | | `hq: too many open connections to team "…". Close one and try again.` | Close an editor window or terminal you no longer need. | | `hq: HQ is restarting. Try again in a moment.` | HQ is deploying. Try again in a few seconds. | | `hq: the AI Team Cloud Computer did not answer in time. Try again in a moment.` | Try again; if it repeats, check the team in HQ. | | `hq: your access to this team ended (revoked, expired, or remote access was turned off).` | Your access changed while you were connected. Run `hq status` to see what you can reach now. | | `hq: this connection was closed from HQ.` | Someone closed it in HQ. Connect again if you still need it. | | `hq: connections end after 12 hours. Connect again to continue.` | Reconnect. | | `hq: the AI Team Cloud Computer could not be reached (HTTP …).` or `hq: the connection closed (…).` | Try again. If it repeats, send the message to support. | **A reconnect did not wake the team.** When `hq` reaches a sleeping team for what looks like a background reconnect, HQ does not wake it, and `hq` says to run `hq up`. Run `hq up ` or open the team in HQ, then reconnect. ## Attach [#attach] | Message | What to do | | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `hq: no session "…" you can open. Sessions are listed in HQ on the team page.` | Check the name or id on the team page in HQ. You need viewer access or more on that team. | | `hq: "…" matches … sessions. Use more of the id:` | `hq` lists the matches with the first 8 characters of each id. Attach with one of them. | | `hq: could not reach HQ.` | Check your network, then attach again. | | `hq: could not reach HQ (…).` | The same, with the network error. Check your network and try again. | | `hq: connection lost, reconnecting...` | Progress: `hq` retries on its own, up to 8 times in a row. | | `hq: the connection to HQ was lost.` | The retries ran out. Check your network and attach again. | | `hq: your access to this session ended.` | Your access changed so you can no longer watch the session (for example, your role on the team no longer lets you view sessions), or the session was closed. `hq` exits. | | `hq: View only: your role doesn't let you type here.` | Your access changed while you were attached, or you are watching. What you type is not sent, and `hq` keeps streaming. The line repeats at most every few seconds while you type. To type again after your access is restored, press `Ctrl-]` and attach again. | | `hq: the session stopped.` | The session was stopped in HQ or by a schedule. Start it again in HQ, then attach. | | `hq: the session exited with an error.` | The session's process ended with an error. Open it in HQ to see why. | | `hq: local echo is not available on this HQ yet.` | Your organization or this HQ does not allow local echo. `hq` attaches without it. | | `hq: --local-echo takes auto, always or off.` | Use one of those three values. | **Nothing happens after attaching.** A sleeping Cloud Computer is starting: `hq` prints progress, and `hq: Taking longer than usual, still working.` when it takes longer than 30 seconds (45 seconds on Boost Max). If you see `Press any key to continue.`, press a key to wake it. **You cannot type.** You are watching someone else's session: the first line said `view only`. Only the person who started a session types in it. In your own session, your role on the team may not allow typing; an owner or admin can change it. **`Ctrl-]` does not detach.** On keyboards where `]` needs another modifier, try `Ctrl-5`, which sends the same key code in most terminals. ## Port forwarding [#port-forwarding] | Message | What to do | | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `hq: the team port must be a number from 1024 to 65535.` | Forward the port your server listens on, in that range. | | `hq: --local must be a port number.` | Give `--local` a number. | | `hq: no team lets you forward ports. Run hq status to see your teams.` | Forwarding needs editor or owner access and remote access on. | | `hq: more than one team can forward ports. Name one with --team .` | Add `--team hq-…`. | | `listen EADDRINUSE: address already in use 127.0.0.1:…` | Something on this computer already uses that port. Pick another with `--local `. | | `hq: the forward ended (…).` | HQ stopped answering the forward's heartbeat. Start it again. | | `hq: stream failed (…)` | One connection through the forward failed; the forward keeps running. Retry the request. | ## Signing out [#signing-out] | Message | What to do | | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `hq: could not reach HQ to revoke this device (…). Signed out locally.` | The login is gone from this computer, but HQ may still list it. Remove it in HQ, under Account, Devices. | | `hq: HQ did not confirm that this computer’s access ended. Remove it in HQ, under Account, Devices.` | Do that in HQ. | ## Commands [#commands] | Message | What to do | | ----------------------------------------------- | ----------------------------------------------------------------- | | `hq: unknown command "…". Run hq --help.` | Check the spelling against [the reference](/docs/cli/reference/). | | `hq: missing arguments for "…". Run hq --help.` | The command needs a team, session or port. | ## Still stuck? [#still-stuck] Email [support@aiworkforceone.com](mailto:support@aiworkforceone.com) with the output of `hq --version` and the exact message. Never include the contents of `~/.hq`. --- # Developers URL: /docs/developers Use HQ from your terminal with the hq CLI, from your editor with the VS Code extension, and from your own code with the HQ API. Everything you do in HQ, you can also do from your own tools. Install `hq`, sign in, attach your terminal to a session, start and stop sessions and forward ports. Open a team's files, join its session terminals and forward its ports from VS Code, Cursor, Windsurf or VSCodium. Manage AI Teams, sessions, schedules, secrets and more from your own code, with SDKs for TypeScript and Python. ## Get an API key in 2 minutes [#get-an-api-key-in-2-minutes] In HQ, open **Profile**, then **API keys**, and select **Create key**. Name it, tick the scopes it needs and create it. The key is shown once: copy it into your secret manager or an environment variable. ```bash curl https://api-hq.aiworkforceone.com/v1/me \ -H "Authorization: Bearer $HQ_API_KEY" ``` Next, follow the [API quickstart](/docs/api/quickstart/) to start a session and send it a prompt, or read about [authentication](/docs/api/authentication/) and service keys. ## Machine-readable docs [#machine-readable-docs] Every page has a Markdown copy: use **Copy page**, or **Open in** to ask Claude or ChatGPT about it. [llms.txt](/docs/llms.txt) lists every page, and [llms-full.txt](/docs/llms-full.txt) has all of them in one file. --- # What is HQ URL: /docs/get-started HQ is where you run AI Teams. Each AI Team has its own Cloud Computer, where AI Employees such as Claude Code work in sessions, on a schedule, while you are away. AI Workforce One HQ runs AI coding agents for you in the cloud. You sign in with your own Claude or ChatGPT account, and the work keeps going when your laptop is closed. ## How HQ is organized [#how-hq-is-organized] * **Organization.** Your company in HQ. It has a plan, people and a billing account. You can belong to more than one organization. * **AI Team.** A team of AI Employees with its own **AI Team Cloud Computer**: a private computer in the cloud with its own files, secrets and schedules. A team uses one engine, Claude Code or Codex. * **Session.** One conversation with an AI Employee, in a terminal or in the chat view. A session keeps running until you stop it. * **Schedule.** Work that starts by itself, for example every Monday at 9:00. * **Secrets and variables.** Keys, tokens and settings your sessions can use. Secrets are encrypted and masked in output. * **People.** Everyone in your organization has a role that decides what they can see and do. ## What you can do in HQ [#what-you-can-do-in-hq] Create an account, add your first AI Team and start a session in about 5 minutes. Create a team, size its Cloud Computer and manage its storage. Work with an AI Employee in a terminal or a chat, open files and preview your app. Have your AI Employees start work on their own, on the days and times you choose. Invite your team and decide what each person can see and do. Use HQ from your terminal, from VS Code or from your own code. ## HQ on your phone [#hq-on-your-phone] HQ works in the browser on your phone. Check on a session, approve a step or start a schedule from anywhere. ## Related [#related] --- # Quickstart URL: /docs/get-started/quickstart Create your account, add your first AI Team and start your first session in about 5 minutes. This guide takes you from a new account to a working session. You need an email address and a Claude account (Pro or Max) or a ChatGPT account. Go to [hq.aiworkforceone.com](https://hq.aiworkforceone.com) and select **Create account**. Enter your name, email and a password, then open the link in the email we send you to confirm your address. Pick a plan, name your organization and select **Continue to checkout**. Every plan starts with a 14-day free trial. During the trial you have 1 AI Team for 1 person; the plan's full limits start when your paid plan does. See [Billing and plans](/docs/billing/). Open **AI Teams** in the sidebar and select **Add AI Team**. Choose **From scratch**, give the team a name, pick the engine (Claude Code or Codex) and select **Create AI Team**. Select **New Session**, choose the AI Team, give the session a name and pick how much Claude may do on its own. Select **Create session**, then **Start with my Claude login** and sign in to Claude inside the terminal. The first start also starts the team's Cloud Computer, which can take a minute. Type what you want done, like you would to a colleague. The session keeps running when you close the tab. Come back to it from **Sessions** or the dashboard. The person who creates the organization is its owner and can do every step. Creating AI Teams is for owners and admins. ## Next steps [#next-steps] The terminal, the chat view and what each permission mode allows. Give your sessions the keys and tokens they need, encrypted. Have an AI Employee start on its own every weekday. Add people and choose what they can do. --- # Sign in and switch organizations URL: /docs/get-started/sign-in Sign in to HQ, switch between the organizations you belong to, create another organization and sign out. You sign in to HQ with your email and password. If you belong to more than one organization, you choose which one to work in, and you can switch at any time. ## Sign in [#sign-in] Go to [hq.aiworkforceone.com](https://hq.aiworkforceone.com). **Sign in** is selected. Select **Continue**. If you forgot your password, select **Forgot?** and we email you a link to set a new one. If you turned on two-factor authentication, or your organization requires it, enter the code from your authenticator app. See [Two-factor authentication](/docs/security/two-factor/). ## Switch organizations [#switch-organizations] Your organization's name and plan are at the top of the sidebar. Select it to see every organization you belong to, then select the one you want. HQ opens its dashboard. With more than 6 organizations, the menu has a search field. ## Create another organization [#create-another-organization] Select the organization name at the top of the sidebar, then **Create organization**. You pick a plan and a name, the same way as for your first one. Each organization has its own plan, people and billing. ## Sign out [#sign-out] Select **Sign out** at the bottom of the sidebar. HQ signs you out on this browser. Sessions keep running: signing out never stops your AI Employees. ## Related [#related] --- # AI Workforce One HQ Docs URL: /docs/ Guides for HQ, and reference for the hq CLI, the VS Code extension and the HQ API. Run AI Teams on their own Cloud Computers, from HQ, your terminal, your editor or your code. Guides for HQ, and reference for the `hq` CLI, the AI Workforce One HQ extension for VS Code and the HQ API. ## Guides [#guides] * [What is HQ](/docs/get-started/) and the [quickstart](/docs/get-started/quickstart/): create an account, add your first AI Team and start a session in about 5 minutes. * [AI teams](/docs/ai-teams/): create a team, size its Cloud Computer and give it a Boost. * [Sessions](/docs/sessions/): the terminal and the chat view, files, Preview, Browser View and history. * [Schedules](/docs/schedules/): have your AI Employees start work on their own. * [Secrets and variables](/docs/secrets/): organization, team and personal. * [People and access](/docs/people/): invite people and give them access to AI Teams. * [Billing and plans](/docs/billing/): plans, add-ons, invoices and cancelling. * [Two-factor authentication](/docs/security/two-factor/) and the [audit log](/docs/security/audit-log/). - [Storage for AI Teams](/docs/ai-teams/storage/): how your organization's storage is shared by its AI Teams, how a team's disk grows, and how owners and admins set a cap or a reserve. - [Roles and permissions](/docs/people/roles/): decide what each person can see and do in your organization and on each AI Team. - [Support access](/docs/security/support-access/): what HQ Support can see when it helps you, and how to let it read session transcripts and files for a few hours. - [Data export](/docs/security/data-export/): get a copy of your organization's data, including the files on your AI Teams' Cloud Computers, and confirm an erasure request. ## Developers [#developers] * [CLI overview](/docs/cli/): install `hq`, sign in, attach a terminal to a session and forward ports from an AI Team Cloud Computer. * [VS Code overview](/docs/vscode/): install the extension, sign in, open a team's files, join its session terminals and forward its ports, from VS Code, Cursor, Windsurf or VSCodium. - [HQ API](/docs/api/): manage AI Teams, sessions, schedules and secrets from your own code. - [Changelog](/docs/changelog/): what is new, improved and fixed in HQ, the CLI and the VS Code extension. --- # People and access URL: /docs/people Invite people to your organization, choose their role, and decide which AI Teams each person can see and change. Owners and admins manage people. **People** has two tabs. **Members** lists everyone in your organization with their role, whether they have two-factor authentication, and when they joined. **Roles** lists the roles they can have: see [Roles and permissions](/docs/people/roles/). On **Members**, under the list, **AI Team access** shows what each person can do on each team, and **Pending invites** lists invitations not yet accepted. ## Invite someone [#invite-someone] Select **People** in the sidebar, then **Invite people**. Choose **Member** or **Admin**. Add a job title if you like: it shows under their name on People and the Org Chart, and they can change it later. Select **Send invite**. They get an email with a link to join. Until they accept, the invite is under **Pending invites**, where you can **Resend** or **Revoke** it. Ownership can't be given with an invite: only the current owner can make someone an owner. ## Give access to AI Teams [#give-access-to-ai-teams] A **Member** sees only the AI Teams they are added to. In **AI Team access**, select a cell to cycle that person's access to that team: * **Owner:** full control of the team, its secrets and its access. * **Editor:** read and write. Starts sessions, changes files and schedules. * **Viewer:** read only. Watches sessions and reads files. * **No access.** Organization owners and admins are team owners on every team, shown as "via org owner". ## Change a role or remove someone [#change-a-role-or-remove-someone] Open the menu at the end of a person's row to change their organization role or remove them. Removing someone from an AI Team ends their access to that team's sessions at once. ## Require two-factor authentication [#require-two-factor-authentication] Turn on **Require two-factor authentication** at the top of People, and everyone must set up an authenticator app before they can use the organization. See [Two-factor authentication](/docs/security/two-factor/). Owners and admins invite and remove people, and admins may invite other admins. Only owners change roles, remove other owners and require two-factor authentication. ## Related [#related] --- # Roles and permissions URL: /docs/people/roles Decide what each person can see and do in your organization and on each AI Team, with system roles on every plan and custom roles on Professional and Enterprise. Every person in your organization has a role. A role is a set of permissions, such as "See billing", "Start sessions" or "Reveal team secret values". HQ checks the permission on every request, so a person can only do what their role allows. ## Where roles live [#where-roles-live] Roles are a tab of **People**: **Members** lists the people in your organization, and **Roles** lists the system and custom roles. You see the **Roles** tab if your role lets you see roles. Roles used to be under **Settings**; old links to them still work. ## System roles [#system-roles] Six roles come with every organization. They can't be changed. | Role | Applies to | What it allows | | ---------- | ------------ | ------------------------------------------- | | Owner | Organization | Everything, including billing and ownership | | Admin | Organization | Everything except ownership and roles | | Member | Organization | Sees the AI Teams they are added to | | Team owner | AI Team | Runs the AI Team, its secrets and access | | Editor | AI Team | Works in sessions, files and schedules | | Viewer | AI Team | Watches sessions and reads files | An organization owner or admin is a team owner on every AI Team. To see exactly what a system role allows, open **People**, then the **Roles** tab, and select the role. On **People**, a person's role also links to that role's page. ## Custom roles [#custom-roles] On Professional and Enterprise, an organization owner can create custom roles. Professional includes 25 custom roles; Enterprise has no limit. Custom roles are not available during a trial. A custom role applies either to the **organization** or to an **AI Team**: * An organization role is assigned on **People**. Team permissions in an organization role apply on every AI Team, including teams created later. * An AI Team role is assigned per team, in the **AI Team access** grid on **People**. To create one: 1. Open **People**, then the **Roles** tab, and select **New role**. 2. Start from a template (Billing manager, Auditor, Schedule operator, Contractor, Team lead or People admin), copy a system role, or start blank. 3. Name the role and choose the permissions it needs. Turning on a permission also turns on the permissions it depends on. 4. Select **Create role**. Permissions marked **Sensitive** give access to billing, people, secret values or the audit log. When you add one to a role that people already have, HQ asks you to confirm first. If your organization requires two-factor authentication for admins, people with an organization role wider than Member need it too. ## Preview a role [#preview-a-role] To see HQ the way someone with a role sees it, open the role on the **Roles** tab of **People**, and select **Preview**. HQ opens the dashboard as that role: pages, AI Teams and buttons appear the way the role gets them. A banner at the top says which role you are previewing. A preview is read-only. Nothing can be changed while it runs, even the things the role is allowed to change; **What this role can change** in the banner lists those. The data you see is still yours, and you only see AI Teams you can already see yourself. Select **Exit preview** to go back to the role. A preview also ends when you switch organization, sign out or reload the page. Every preview is recorded in the audit log as "Previewed a role". ## Check someone's access [#check-someones-access] To find out whether a person can do something, open **People**, then the **Roles** tab, and select **Open checker** under **Check someone's access**. Choose the person, the permission and, for a team permission, the AI Team, then select **Check access**. HQ answers **Allowed** or **Not allowed** and names the role or rule that decided it. You need permission to see roles and people to use it. ## New permissions [#new-permissions] When HQ adds a permission, existing custom roles don't get it automatically. A role in the list shows how many permissions are new since it was last edited. Open the role and select **Show new permissions** to see only those, marked **New**, and turn on the ones the role should have. ## Rules no role can change [#rules-no-role-can-change] Some things only one person can ever do, whatever their role: * Only the owner of a session can type into it, change its permissions or share it, and only while they still have access to its AI team. An owner who can't see the team's sessions, through their role or because they were removed from the team, can't watch or type in their own sessions there. * Personal secrets and variables belong to their owner. * Only an owner can cancel the subscription, change the payment method or manage owners. * You can only give permissions you have. A role you can't give is shown disabled with the reason. * Only an owner can give role management (**Create and edit roles** and **Change roles**). Someone who manages roles through a custom role, like a People admin, sees both locked with "Only an owner can give role management". * Nobody can change their own role. These rules appear in the role editor as locked rows. ## Changing and archiving a role [#changing-and-archiving-a-role] Editing a role changes it for everyone who has it. If two people edit the same role at once, the second save is refused with "Someone else changed this role", and you can reload to see their change. To retire a role, select **Archive**. If people still have it, choose the role they move to. An invitation into an archived role can no longer be accepted: the person invited is told the role no longer exists and to ask for a new invitation. When a change takes something away from people who have the role, it applies to their open sessions too. Someone who can still watch a session but can no longer type sees "You can no longer type in this session. You can still watch it." Someone who can no longer see the session sees that they don't have access to it. If the role no longer lets them **Connect from a computer** on an AI Team, any `hq attach` or VS Code terminal they have open on that team is closed. If they lose it on every AI Team, their computer is also unlinked from the organization: when the role gives it back, they link the computer again (sign in with `hq login` or the VS Code extension). A permission that another one needs can't be turned off on its own. For example, **Read files remotely** needs **Connect from a computer**: turn off both, or keep both. Removing someone from an AI team, or leaving it yourself, ends their access to that team's sessions at once, including the sessions they own there. Those sessions show that their owner left the team, and nobody can type in them until a team owner or an organization owner or admin reassigns them. Organization owners and admins reach every team, so removing their team access changes nothing. ## If your plan changes [#if-your-plan-changes] If your organization moves to a plan without custom roles, existing custom roles keep working exactly as they did for the people who have them. You can't create new ones, add permissions or assign them, but you can remove permissions, move people to a system role and archive a role. Moving back to Professional or Enterprise unlocks them again. --- # Schedules URL: /docs/schedules Have an AI Employee start work on its own, at the days and times you choose, whether you are online or not. Editors and team owners create schedules. A schedule sends a prompt to an AI Employee at the times you pick, in plain language: no cron expressions. Use it for daily reports, weekly reviews or overnight jobs. ## Create a schedule [#create-a-schedule] Select **Schedules** in the sidebar, then **New schedule**. You can also use **Add schedule** on a team in the list. Name the schedule and choose the AI Team. Choose **Daily**, **Weekdays**, **Weekly**, **Monthly** or **Once**, then the days and the time. Select **Add another time** to run more than once a day, up to 12 times. Pick the time zone. The summary on the right shows the next runs. Write the prompt, as if you typed it into the session at run time. Under **Run as**, choose **Use existing session** to keep the history and context between runs, or **Create new each time** for a clean start. Choose what happens if the session is stopped at run time: **Restart it** or **Skip & notify me**. Leave **Enabled** on to start on the next matching time, and select **Create Schedule**. Scheduled sessions should usually use **Autopilot**, so nobody needs to approve each step. See [permission modes](/docs/sessions/terminal-and-chat/#permission-modes). A run types its prompt into the session's AI Employee. If the session has its terminal open at run time, the run is skipped and you are notified, and the terminal is left as it is. Switch the session back to its AI Employee for the next run. ## Run, pause and edit [#run-pause-and-edit] * **Run now** starts a run right away, without changing the schedule. * The switch at the start of each row pauses or resumes a schedule. * Open a schedule to edit it and see its recent runs. ## When every session slot is busy [#when-every-session-slot-is-busy] Each AI Team runs a limited number of sessions at once (5 on a Standard Cloud Computer). If all are busy at run time, the run waits for a free slot. A run that can't start in time is skipped, and you are notified. A run also waits when the team's Cloud Computer is too busy for another session (memory at 80% or more, or the processor working at full capacity); its history then says **Cloud Computer busy**. **Needs attention** in the filters lists schedules whose last run did not go well. ## A prompt that starts with a command character [#a-prompt-that-starts-with-a-command-character] A prompt that starts with `/`, `!` or `#` is one of Claude's own commands, not a task, so HQ does not let you save one. A prompt also cannot contain hidden control characters (tabs and line breaks are fine): a run types the prompt into the session, where such a character would act as a key rather than as text. ## When a session is waiting on a message [#when-a-session-is-waiting-on-a-message] Another Claude session can send a message to your AI Employee's session. When the two sessions use different permission modes, Claude holds the message and asks in the session whether to **Deliver** it or **Deny** it, and waits until someone answers. While it waits, a scheduled run does not type into the session: the run shows as **Not run** and its details say a message is waiting. You're notified once until the message is answered, not on every run. Open the session's terminal, choose **Deliver** or **Deny**, and the next run goes ahead as usual. If the run had already typed its prompt when the message arrived, the details say the prompt is still in the input box. ## When Claude asks to resume a long conversation [#when-claude-asks-to-resume-a-long-conversation] Schedules always continue the session's conversation so Claude keeps its context. Resuming a long conversation uses part of your Claude usage limit. When Claude reopens a long conversation that has been idle for hours (for example after the nightly Cloud Computer update restarted the session), it can ask **Resume this conversation?** A scheduled run answers **Resume** and then types its prompt as usual. To start a new conversation instead, do it yourself in the session's terminal. If Claude asks in a way HQ does not recognize yet, the run types nothing, shows the session as unavailable, and its details say Claude is asking whether to resume: open the session's terminal and answer it once. ## When a session is reassigned [#when-a-session-is-reassigned] A schedule that uses an existing session runs on the Claude login of the person it runs as. When someone reassigns that session to another person, the schedule has to move with it, or it stops running. * **When you reassign a session**, the dialog lists the schedules that run on it, who they run as and when they run next. If you are a team owner or an organization owner or admin, **Move these schedules to** the new owner is ticked: they then run on the new owner's Claude login. If you untick it, or someone else reassigns the session, the schedules stop running until an admin or the new owner moves them. * **A schedule that was not moved** shows **Not running: this session now belongs to** the new owner, on its row and on its page. Select **Move to** the owner to fix it. It moves only to the session's current owner, never to anyone else. * **The new owner is told.** They get an email and a notice on the Schedules page: "N schedules now run on your Claude login", with a link to each. They can pause or edit them, and from then on only they can change a schedule's prompt and the session it runs in. Schedules only move to someone who can manage schedules on the team (an editor or a team owner). If the new owner can only view the team, the dialog says the schedules will stop running, and **Move to** is not offered until they get edit access. A schedule that starts a new session each run runs on the Claude login of the person who created it, and a reassign does not change that. Schedules that run on the team's API key do not run as a person, so a reassign does not affect them either. Only the person a schedule runs as can change its prompt or the session it runs in, including switching between an existing session and a new one each run. Others on the team, organization owners and admins included, can still pause, rename, reschedule or delete it. Editors and team owners create, change and run schedules. Anyone on the team can see them. Your plan sets how many schedules you can have. Moving schedules to someone else takes a team owner or an organization owner or admin; the session's owner can move them onto their own login. ## Related [#related] --- # Secrets and variables URL: /docs/secrets Give your sessions the keys, tokens and settings they need. Secrets are encrypted and masked; variables are plain settings. Owners and admins manage organization secrets. Your sessions receive secrets and variables as environment variables when they start. * **Secrets** are encrypted at rest and masked in the terminal output, for API keys, tokens and passwords. * **Variables** are plain settings, such as `NODE_ENV`, and are visible in output. They come at three levels. When two have the same name, the more specific one wins: | Level | Where you set it | Who it applies to | | ------------ | --------------------------------------------- | ------------------------------------- | | Organization | **Secrets** in the sidebar | All AI Teams, or the teams you select | | AI Team | The team's **Secrets** and **Variables** tabs | That team's sessions | | Personal | Your profile, **Secrets and variables** | Only the sessions you own | Claude itself signs in with **claude login** inside the session. Your Claude account is never stored as a secret. ## Add an organization secret [#add-an-organization-secret] Select **Secrets** in the sidebar, then **Add**. Keep **Secret** selected. Use the name your code expects, such as `SLACK_WEBHOOK_URL`, and paste the value. **All AI Teams**, or **Selected AI Teams** and pick them. Select **Add secret**. A change applies the next time a session starts. To add many at once, select **Import .env** and choose a `.env` file. ## Variables [#variables] Open the **Variables** tab and select **Add**, or choose **Variable** in the same dialog. Variables are visible in output, so never put a secret in one. ## Team secrets [#team-secrets] Open an AI Team and its **Secrets** tab to add secrets only that team gets. Its **Variables** tab also shows the organization variables the team receives. ## See a secret's value [#see-a-secrets-value] Select the eye next to a secret to reveal it, then **Copy**. Revealing a value is recorded in the [audit log](/docs/security/audit-log/) as "Revealed a secret". Organization owners and admins see, add and reveal organization secrets. Team owners manage their team's secrets. Everyone in the organization can see and change organization variables. ## Related [#related] --- # My secrets and variables URL: /docs/secrets/personal Personal secrets and variables apply only to the sessions you own that sign in with your own account. Only you can see them. Use personal secrets for credentials that belong to you, like your own GitHub token. Nobody else in the organization, including admins, can see their names or values. ## Add a personal secret [#add-a-personal-secret] Select your name at the bottom of the sidebar, then the **Secrets and variables** tab. Select **Add**, enter the name and the value, and save. Or select **Import .env**. Personal secrets and variables: * apply only to sessions you own that sign in with your own account; * take the place of a team or organization value with the same name; * apply the next time a session starts; * belong to one organization: switch organization to set them for another. You can keep up to 50 personal secrets per organization. Everyone, for themselves. ## Related [#related] --- # Audit log URL: /docs/security/audit-log A record of who did what in your organization, newest first, that you can filter and export. Owners and admins read it. HQ records every change in your organization: sign-ins, AI Teams created, secrets added or revealed, people invited, sessions started and stopped, plan changes and more. Secret values are never recorded, only their names. ## Find something [#find-something] Select **Audit log** in the sidebar. Choose an action (for example **Invited a person**), a person, or a date. Select **Export CSV**. The file is safe to open in spreadsheet apps. How long entries are kept depends on your plan: 7 days on Solo and Starter, 30 days on Growth and 90 days on Professional. The page says how long yours keeps them. Sessions started from the `hq` CLI or VS Code are recorded too, with the computer they came from. Every time HQ Support looks at your organization, it is recorded here as well. Organization owners and admins read and export the audit log. Nobody can change or delete it. ## Related [#related] --- # Data export URL: /docs/security/data-export Get a copy of everything your organization keeps with AI Workforce One HQ, including the files on your AI Teams' Cloud Computers, and how an erasure request works. An organization owner can get a **copy of the organization's data**: its records, its invoices, the conversation of every session, and the files on each AI Team's Cloud Computer. It is one zip file you download in HQ. ## Ask for an export [#ask-for-an-export] Ask AI Workforce One HQ Support (reply to any HQ email or open a ticket). Support checks that the request comes from an owner of the organization, then the export is built. We answer within 30 days of your request, usually much sooner. If you want the files and conversations from Cloud Computers that are **not running** right now, say so: we then start them to copy them. Otherwise only Cloud Computers that are running are copied, and the others are listed in the export so you know they were left out. A Cloud Computer started for an export shows in your Audit log. ## Download it [#download-it] When the export is ready, every owner gets an email. Then: 1. Go to **Settings**, then **Data export**. Only owners see this section. 2. Press **Download** next to the export. The download link is created when you press the button and works for 15 minutes; press it again for a new one. The export itself can be downloaded for **7 days**, then it is deleted. Each download is recorded in your Audit log. ## What is in it [#what-is-in-it] | In the zip | What it holds | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `organization.json`, `members.json`, `teams.json`, `schedules.json` | your organization, its people and their roles, your AI Teams, your schedules and their prompts | | `variables.json`, `secret-names.json` | your variables, and the **names** of your secrets | | `audit-log.json` | your Audit log, as kept | | `invoices.json`, `invoices/` | your invoices, with their PDFs | | `files/team-01/`, `files/team-02/`, ... | the files on each AI Team's Cloud Computer; `teams.json` says which folder is which team | | `transcripts/team-01/`, ... and `sessions.json` | the conversation of each session, one `.jsonl` file per session; `sessions.json` names each session and its file | | `manifest.json` | what is included, what is not, and why | Some things are never in an export: * **Secret values.** They are encrypted and never leave the vault. Their names are listed. * **Claude and ChatGPT sign-ins** on your Cloud Computers. They belong to the person who signed in. * **Raw terminal output.** Download it from each session's history in HQ. * **Codex conversations.** Codex keeps no conversation file HQ can read; it is in the session's terminal output. Conversations are copied with your secret values hidden, exactly as HQ shows them in a session's chat. Your own files are copied as they are, including files such as `.env` that you put on a Cloud Computer. Dependency folders such as `node_modules` and links are not copied (they are listed). An export holds up to 5 GB and 100,000 files and conversations in all (conversations are copied first); anything beyond that is listed in `manifest.json` with its size, and you can download those files from the team's file browser in HQ. An export larger than 4 GB, or with more than 65,534 files, is saved in the ZIP64 format, which current unzip tools open (we check it with `unzip`, 7-Zip and Python). A very old unzip tool may not. A smaller export is a plain zip file. ## Erasure requests [#erasure-requests] If someone asks HQ Support to **erase** your organization, support records the request and an owner must confirm it: 1. Go to **Settings**, then **Data export**. An open request shows there. 2. Press **Confirm erasure** and type `erase` to confirm. Nothing is erased unless an owner confirms it. Confirming is recorded in your Audit log. **What an erasure removes:** your AI Teams and their Cloud Computers, sessions and transcripts, schedules, secrets and variables, templates, API keys, webhooks, invitations and the organization's members. Templates you shared keep working for the organizations that received them, without your organization's name. **What it keeps:** each person's own sign-in account (people can belong to more than one organization; anyone can ask us to delete their own account), your billing records and invoices, and the audit record that the erasure happened. A recovery copy of your data is kept for 30 days and then deleted. --- # Support access URL: /docs/security/support-access What AI Workforce One HQ Support can see when it helps you, how to let it read session transcripts and files for a few hours, and how to see every time it looked. When you ask for help, AI Workforce One HQ Support may open a **read-only view** of your organization from its staff console. It never signs in as you, never gets a session of its own in HQ, and cannot change anything, type into a session, open a terminal or see a secret value. ## What support can see [#what-support-can-see] Without anything from you, support can see your **account details**: your plan, your AI Teams and their Cloud Computers, your schedules (their names and timing, not their prompts), your people and their roles, your Audit log, and the **names** of your variables and secrets. Never their values. Session **transcripts and files** are different: support can read them only while you allow it. Even then it sees text files only (at most the first 512 KB of each), with your secret values hidden exactly as they are in your own terminal, and reading never wakes a Cloud Computer that is asleep. Support never opens credential files such as `.env`, `.npmrc`, `.netrc`, cloud and Git credentials or private keys, even when you allow access; it can see that they exist, not what is in them. Its access is read-only: it cannot type in a terminal, start or stop anything, or change a file. ## Let support read transcripts and files [#let-support-read-transcripts-and-files] 1. Go to **Settings**, then **Security**, then **Support access**. Only an organization owner sees this card. 2. Choose how long: **4 hours**, **24 hours** or **72 hours**. 3. Press **Allow support access** and confirm with your password or authenticator code. The card shows **Active until** with the time it ends. It ends by itself then. Press **Turn off support access** to end it sooner; a view support already has open ends on its next step. ## See every time support looked [#see-every-time-support-looked] * **Email.** Every owner gets an email the moment support opens a view of your organization. * **Audit log.** Each view adds a row when it starts and when it ends, and each transcript or file support reads under your access adds one more. They are listed as AI Workforce One HQ Support. * **A notice in HQ.** After a view ends, owners and admins see a short notice the next time they open HQ. * **The Support access card** lists the recent views. A view lasts at most an hour, and ends after 15 minutes without activity. --- # Two-factor authentication URL: /docs/security/two-factor Add a code from an authenticator app to your sign-in, and require it for everyone in your organization. Everyone sets up their own; owners require it. Two-factor authentication (2FA) asks for a 6-digit code from an authenticator app, such as 1Password, Google Authenticator or Authy, each time you sign in. Someone who learns your password still can't sign in. ## Turn on 2FA for yourself [#turn-on-2fa-for-yourself] Select your name at the bottom of the sidebar, then the **Security** tab. Scan the QR code with your authenticator app, or type the key it shows. Enter the 6-digit code from the app. Keep them somewhere safe, such as your password manager. Each one signs you in once if you lose your phone. You can create new ones from the same tab. The **Security** tab is also where you change your password. Changing it signs you out on your other devices. **Devices** lists the computers where you use the `hq` CLI or VS Code. ## Require 2FA for your organization [#require-2fa-for-your-organization] In **Settings**, then **Security**: * **Require two-factor authentication:** every member must set up 2FA before they can use the organization. The same switch is at the top of **People**. New members get a setup page the first time they sign in. * **Always require 2FA for admins:** owners and admins can't turn their 2FA off. Everyone sets up their own 2FA. Only organization owners change the organization's security settings. ## Related [#related] --- # Browser View URL: /docs/sessions/browser-view Watch the web browser your AI Employee uses, take control when a page needs a person, answer a Needs you request, attach workspace files to a page and stay signed in to sites. Your AI Employees can use a real web browser on the team's Cloud Computer, for example to test your site, fill in a form or read a dashboard. **Browser View** shows that browser live, next to the terminal. You can watch it, and when a page needs a person (a sign-in, a code, a CAPTCHA) you take control, do that step yourself and hand it back. The browser works in Claude Code sessions. Codex sessions do not have it. ## Turn on the browser for a team [#turn-on-the-browser-for-a-team] Open the AI Team and select **Settings**. On the **Browser for AI Employees** card, select **Enable browser**. It takes a moment. Sessions started after this can use the browser. On a Standard Cloud Computer, the browser can slow the team down: consider a [Boost](/docs/ai-teams/cloud-computers/). If you enabled the browser before **Needs you** existed, the card shows **Add Needs you**. Select it, then start a new session, so your AI Employee can ask you for help in the browser. To remove it, select **Turn off browser**. The browser closes at once, also in running sessions, and its open pages are deleted. Your [saved sign-ins](#stay-signed-in-to-sites) are kept unless you tick **Also delete saved sign-ins**: they wait, unused, until the browser is enabled again. ## Watch the browser [#watch-the-browser] When your AI Employee opens a page, a **Browser** button appears at the top of the session and the view opens beside the terminal on its own. Your typing stays in the terminal. If you close the view, it stays closed until the browser starts again: select **Browser** to open it. * The bar at the top shows the page's address, with the site's name in bold, and its title. The address comes from HQ, not from the page, so a page cannot fake it. An address that starts with `http://` is not a secure connection. * One line under it says where the browser runs and who can see it. Select **Details** for more. * Everyone who can open the session sees the same browser, and the view says how many people are watching. * The view pauses after 30 minutes without activity from you or your AI Employee. It comes back by itself as soon as your AI Employee uses the browser again, or select **Resume**. ## Take control and hand back [#take-control-and-hand-back] **Take control** is under the view. While you have control, the view has a coloured outline and your clicks, typing and scrolling go to the page. The bar under the view shows the time you have left, for example **You have control · 4:52 left**. Type or paste straight into the page (**Ctrl+V**, or **Cmd+V** on a Mac). Your AI Employee waits while you have control: it cannot click or type in the page. Select **Hand back** when you are done. Your AI Employee carries on from where you left the page. Closing the view while you have control hands back too. Good to know: * **Escape** returns your keyboard to the terminal. To send Escape to the page itself, select **Send Escape**. * **Back**, **Forward** and **Reload** work while you have control. To go to another page, select the address, type a web address (for example `example.com`) and press **Enter**. HQ does not reload a page that came from a form you sent, such as an order or a payment, because that would send the form again. It tells you instead. * **Copy selection** copies the text you selected on the page to your own clipboard. * The page's own messages and dropdown lists open as cards over the view. Answer them there. * Type dates with the keyboard. Site popups work. Passkeys, security keys and the browser's own sign-in box do not: choose **Use a password** or **Try another way** on the site. * Control returns to your AI Employee on its own after 5 minutes without activity (HQ warns you first), or after 30 minutes in total. * If you have control in another tab, the view says **You have control in another tab.** Select **Take control here** to move it. * One person has control at a time. While someone else has it, the view says who. ### Passwords and codes [#passwords-and-codes] Type a password or a code into the page only while you have control, and check the address at the top of the view first. Everyone watching sees the page while you type, with password fields shown as dots. If you hand back while a password field still has text in it, HQ stops you, because your AI Employee would be able to read it. Choose **Clear it and hand back**, or **Keep control**. Your AI Employee can read everything you send it. Sign in in the browser, while you have control. ### Sites that refuse the browser [#sites-that-refuse-the-browser] Some sites refuse a sign-in from a browser that runs on a cloud server rather than on your own computer. Google, for example, can answer **Couldn't sign you in. This browser or app may not be secure.** Your AI Employee's browser tells sites it is a standard Chrome on Linux, but it still runs in a data center, and a site may decide not to trust it. HQ cannot change that decision. If a site refuses you: * Sign in with the site's own email and password, if it offers that next to **Sign in with Google**. * Use what the site provides for tools and automation, such as an app password, an access token or an API key. Create it on your own computer and keep it in the team's [secrets](/docs/secrets/), never in the chat. ## When your AI Employee needs you [#when-your-ai-employee-needs-you] When your AI Employee reaches a step only a person should do, such as a sign-in, a verification code, a CAPTCHA, a payment or a confirmation, it asks for you and waits. The top of the session says, for example, **Your AI Employee needs you: sign-in.** If the HQ tab is in the background, you can get a notification: select **Notify me when it needs me** once. The view opens with **Take control** ready for you. HQ never takes control for you. The view also shows what your AI Employee said it needs and the site it is on. If the page changed since it asked, the view says so: check the address before you type anything. Sign in, enter the code, solve the CAPTCHA or confirm, right in the page. Select **Hand back**. Your AI Employee is told and carries on. Select **Dismiss** if you will not do it. Your AI Employee is told and carries on without it. A request waits for 30 minutes; after that your AI Employee is told nobody answered. While it waits, the Cloud Computer stays awake, for at most those 30 minutes. ## Choose a file from the workspace [#choose-a-file-from-the-workspace] Some pages ask for a file: an invoice upload, an identity check, a support form. While you have control, selecting the page's upload button opens **Choose a file from the workspace**, or **Choose files from the workspace** when the page takes several. It lists the files of this session's workspace on the Cloud Computer. The line under the title names the site that asked, for example **For a file field on example.com**. It comes from HQ, not from the page. **Not secure** beside it means the site does not use a secure connection. Open folders, or type in **Search files** to find a file anywhere in the workspace. The bottom of the card lists what you chose and its total size. Select **Attach file** (or **Attach 2 files**, and so on). The page receives the files as if you had picked them on your own computer, and HQ says **Attached 1 file to the page.** What to know before you attach: * **The page can read the files as soon as you attach them.** Only choose files you mean to send to that site. * **Files from your own computer:** upload them to the session's [files](/docs/sessions/files/) first, then choose them here. * **Limits:** up to 64 MB a file, 128 MB together, and 20 files at a time. * **What the page asked for:** if the page only takes some kinds of files, such as PDFs or images, the others are greyed out. Tick **Show all files** to choose one anyway; the page may still refuse it. * **Hidden files:** files whose names start with a dot show only after you tick **Show hidden files**. * **Never offered:** settings and secret files, such as `.env` files, `.git`, `.ssh`, cloud credentials and private keys, are never listed. A file that turns out to hold a key or a sign-in token under another name is refused when you attach it. * **Folders:** a field that asks for a whole folder does not work here. Upload the files to the session's files, then ask your AI Employee to attach them. * If the page moves to another site, or the file changes, before the files are attached, nothing is attached and HQ says why. Select the page's upload button again. On a keyboard, the arrow keys move through the list, Space chooses a file, Enter attaches and Escape closes the card. ## Stay signed in to sites [#stay-signed-in-to-sites] When you sign in to a site in your AI Employee's browser, HQ can keep that sign-in, so the next session, a Restart or a Cloud Computer update does not sign you out. * **What is kept:** only what keeps you signed in to a site you opened: its cookies and the data it stores for the sign-in. Never your passwords, your browsing history or form entries. * **Encrypted, per person and per team:** your sign-ins are yours. They are stored encrypted, listed only to you, and kept apart for each team you are on. * **Who can use them:** your AI Employee, in any of your sessions on this team, including scheduled runs and background tasks, and code it runs. People who can watch your sessions see the pages you are signed in to. * **Team API key sessions** never save sign-ins. * A site you have not used for 90 days is forgotten. ### Turn saved sign-ins on or off [#turn-saved-sign-ins-on-or-off] On most teams saved sign-ins are on for you. The first time you open the browser, a note explains them: select **Got it**, or **Do not save on this team**. If your team shares one Cloud Computer between its members, the team's **Settings** say so under **Your browser sign-ins**, with a warning: while your browser is open, other members of the team and anything they run there can use the sites you are signed in to. Read it, and select **Turn on saved sign-ins** only if that is fine for you. Each person decides for themselves. To stop, select **Turn off saved sign-ins for this team**. Your saved sign-ins for that team are cleared. ### Sign out of a site, or clear everything [#sign-out-of-a-site-or-clear-everything] In the team's **Settings**, **Your browser sign-ins** lists the sites you are signed in to and when each was last used: the last time a page of that site opened in your AI Employee's browser, or a sign-in to it was saved. Starting a session does not count, so a site nobody opens is still forgotten after 90 days. * Select **Sign out** next to a site to make your AI Employee's browser forget it. To end the session at the site itself, sign out there too. * Select **Clear everything** to forget every site on this team. This cannot be undone. After you change your HQ password or two-factor authentication, the **Security** tab of your profile offers **Also sign your AI Employee's browser out of every site**. ## Who can do what [#who-can-do-what] | What | Who | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Watch the browser | Anyone who can open the session | | Take control, answer **Needs you** | On a session that runs on someone's own Claude login: only that person, the session owner. On a session that runs on the team API key: editors and team owners | | Turn the browser on or off | Team owners, for the whole team, including scheduled runs and team API key sessions. When people use their own Claude login, editors can turn it on or off for their own sessions | | See and remove saved sign-ins | Only the person who saved them | Only the session owner can take control of a session on their own Claude login; on a team API key session, editors and team owners can. Anyone who can open a session can watch its browser. Each person manages only their own saved sign-ins. ## On a phone or tablet [#on-a-phone-or-tablet] * On a phone, the view does not open on its own, so it never covers the terminal. Select **Browser** at the top of the session. It opens over the whole screen. * **Take control**, **Hand back** and the time left sit at the bottom of the screen, within reach of your thumb. * While you have control, tap to click, drag one finger to scroll and press and hold to right click. Tap the page to bring up your keyboard. Pinch to zoom does not work in the view. * **Needs you** works the same way: select **Open the browser** at the top of the session. ## Ask your AI Employee to use the browser [#ask-your-ai-employee-to-use-the-browser] When the browser is on for the team, each new session tells your AI Employee that it has a real browser and that you can watch it in Browser View. It is told to say what it is doing as it goes, to ask you to do the steps only a person should do (with **Needs you** where your team has it), and never to ask for a password or a code in the chat. A session that was already running keeps what it was told when its conversation began: to give it this, start a new session. Say what you want done and where, and tell it to ask you for the steps only you can do: ```text Open our staging site at staging.example.com, sign in as the test user and check that the checkout page shows the new prices. If the site asks for a password, a code or a CAPTCHA, ask me with Needs you and wait. Do not ask me for the password in the chat. ``` A shorter request works too, for example: ```text Open our pricing page in the browser, check that every plan's button works and tell me what you see. I'll watch in Browser View. ``` ## Related [#related] --- # Files URL: /docs/sessions/files Browse, open, edit, upload and download the files on an AI Team's Cloud Computer from any session. Viewers read files; editors and team owners change them. The files on an AI Team's Cloud Computer are shared by all of its sessions. Open them from the **Files** panel on the left of a session. ## Browse and open files [#browse-and-open-files] In a session, the **Files** tab lists the working folder. Select the explorer button in the header to show or hide it. On a phone or tablet, open **More** and select **Files**. Folders open one at a time, so large teams load quickly. Select a file to open it in the code editor, with syntax highlighting for more than 40 languages. Select the code editor button in the header to show or hide the editor. Change the file and save. ## Upload, create and download [#upload-create-and-download] Above the file list: * **Upload files** or **Upload folder** copies files from your computer to the Cloud Computer. * **New file** creates an empty file in the current folder. * **Refresh** reads the folder again. To download a file, use **Download** on the file. The explorer needs the team's Cloud Computer to be on. When it is off, start a session to browse files. ## Secrets and variables in a session [#secrets-and-variables-in-a-session] The **Secrets and variables** tab next to **Files** shows which secrets and variables this session gets. Values of secrets stay hidden. See [Secrets and variables](/docs/secrets/). Viewers read and download files. Editors and team owners also upload, create and change them. ## Related [#related] --- # Session history URL: /docs/sessions/history Scroll back to the start of a session, exactly as it looked live, and download its history. Anyone who can see a session can read its history. A session keeps its whole history. Scroll up in the terminal to go back to the very start, shown exactly as it looked live. ## Read the history [#read-the-history] Older output loads as you scroll. Your place is kept while it loads. Select the jump to live output button, or just type: a key goes back to the live view. ## Download the history [#download-the-history] Select the download button in the session header, or on the session's row in **Sessions**. On a phone or tablet, it is under **More**. HQ asks you to confirm first, because the history can include anything that was printed in the terminal. ## Where the history lives [#where-the-history-lives] A session's conversation and history belong to its AI Team. They stay with the team when the session is handed to someone else, and are part of your organization's [data export](/docs/security/data-export/). Anyone who can see a session can scroll back through its history. Viewers, editors and team owners can download it; people a session was only shared with may not see the download button. ## Related [#related] --- # Start and stop sessions URL: /docs/sessions A session is one conversation with an AI Employee on an AI Team's Cloud Computer. Editors and team owners start them; a session runs until someone stops it. A session keeps running when you close the tab or your laptop. You can come back to it from any browser, from the `hq` CLI or from VS Code. ## Start a new session [#start-a-new-session] Use **New Session** at the top of the dashboard, or **New session** on an AI Team's page. The permission mode decides how much Claude does on its own: * **Ask me first.** Claude checks with you before it runs a command or changes a file. * **Auto-edit.** Claude writes and edits files on its own, but asks before it runs commands or anything destructive. * **Autopilot.** Claude works on its own and runs everything without asking. Use it for unattended and scheduled work you trust it to finish. **My Claude login** signs in with your own Claude account. If the team has a team API key, you can choose it instead. Select **Create session**. A new session waits, stopped, until you start it. Select **Start with my Claude login** and sign in to Claude inside the terminal the first time. From then on, the session is yours: you are the only person who can type in it. ## Stop, start and restart [#stop-start-and-restart] * **Stop** ends the session's work. Its history and files stay. * **Start** runs a stopped session again. Opening a stopped session never starts it by itself. * **Restart** stops and starts it, for example to apply a new permission mode. When the AI Employee ends a session itself, for example after you type `/exit`, the session stops and its last output stays on screen, the same way it does when a session stops unexpectedly. **Start** runs it again. Claude's command menu and its "Resume this session with" line are cleared from that screen: in HQ, **Start** is how you continue. At the top of every session, its status says how it is: **Running**, **Starting**, **Stopped**, **Sign in** or **Needs you** when it is waiting for you, and **Crashed** or **Out of memory** when it stopped unexpectedly. Select the status to see what it means, how much memory and processor the Cloud Computer is using, and **Restart** and **Stop session**. On a phone, that is where Restart and Stop are. To rename a session, open **More** and select **Rename session**. ## Find your sessions [#find-your-sessions] **Sessions** in the sidebar lists every session you can see, with its AI Team, status and when it was last active. Filter by **Running**, **Stopped** or **Scheduled**, or search by name. Editors and team owners start sessions. Only a session's owner types in it; others on the team can watch it. Organization owners and admins can operate and delete any session. ## Related [#related] --- # Preview your app URL: /docs/sessions/preview When a session runs a web app on its Cloud Computer, open it in your browser at a private address. Anyone on the team can open a preview; editors can use it. When your AI Employee starts a web app (for example a Vite or Next.js dev server), HQ notices the port it listens on and offers to open it. You see the app as it runs on the Cloud Computer, without setting up anything. ## Open a preview [#open-a-preview] Ask the AI Employee to run it, or run it yourself in the terminal. **Open preview** appears in the session header when an app is running. On a phone or tablet, it is the first entry in **More**. With more than one, it shows how many, and you choose a port. Each port names the app or the Docker container behind it. The preview opens in a new tab at a private address. The first time, HQ asks **Open this preview?** so you know which team and port it is. ## Other ports [#other-ports] Services that are not web pages, such as Postgres or Redis, are listed under **Other ports**. Use the filter to find one by port or name. To reach them from your own computer, forward the port with [VS Code](/docs/vscode/ports/) or the [CLI](/docs/cli/port-forwarding/). ## Who sees a preview [#who-sees-a-preview] A preview needs a signed-in HQ account with access to the AI Team. Secret values that appear in a preview are masked for viewers. Only one person at a time can hold a given port's preview. Viewers, editors and team owners can open previews. Editors and team owners can use them. ## Related [#related] --- # Terminal and chat URL: /docs/sessions/terminal-and-chat Work with an AI Employee in the session's terminal, or read and answer it in the chat view. The session owner types; everyone else on the team can watch. Every session has a terminal, where the AI Employee runs, and a chat view of the same conversation. Use whichever you prefer: they stay in step. ## The terminal [#the-terminal] The terminal is the AI Employee's own screen, exactly as it would look on your computer. Type your request and press Enter. When Claude asks for approval, answer in the terminal. * **Paste** text and images as you would anywhere else. * **Instant local echo** shows what you type right away, before the session echoes it back. An organization owner turns it on in **Settings**; each person can turn it off for themselves. * **Wide or narrow screens:** when a session is open in two windows, the window you are using sets the size and the others match it. * **On a phone,** a key bar above the keyboard has the keys a terminal needs, such as Esc, Tab and the arrows. ## The chat view [#the-chat-view] Switch between **Chat** and **Terminal** at the top of the session; on a phone they are two icons. The chat view shows the conversation as messages: what you asked, what the AI Employee did and its answers, with images. It works for Claude Code and Codex. If the chat view can't show a session, the terminal still works as usual. * **Send a message:** press Enter, or Shift+Enter for a new line. On a touch screen with no trackpad or mouse attached, Return adds a new line and you tap **Send** to send (on a phone, the arrow beside the box). Cmd+Enter (Ctrl+Enter) always sends, also from a keyboard attached to a tablet. * **When Claude is asking something on screen,** your message waits in the box and Chat says so above it. Answer the question first, then send. * **When Claude has a plan ready,** Chat shows it as a card with **Approve plan**. Approving keeps Claude asking before each edit; it never turns on auto mode. To change the plan instead, type what to change in **Tell Claude what to change** and press **Send** (or Enter). Claude keeps planning with your feedback and shows you a new plan. With text already in the message box, **Use my message as the answer** moves it into that field. Approving with auto mode is only in the terminal. * **Messages from your other Claude sessions** (a teammate or helper session that sent this one a message) show as a short note, such as "Message from another session (release-check): Tests passed". Routine status pings next to each other share one note, such as "3 status updates from another session (release-check)". Click or tap a note to read the whole message. * **A message Claude is holding for you:** when another session's permission mode differs from this one's, Claude holds its message until you decide. Chat says a message is waiting and shows it as a card with **Deliver** and **Deny**, on a phone and a tablet too. Read it first: it came from another session, not from you. A long message (or one with quotes or brackets) shows the way Claude previews it, which can leave out part of the text. The card then says how much of the message it shows, and **Deliver** is not highlighted; it always sends the whole message. If nobody answers in a few minutes, the message expires and the sender is told it was declined. A scheduled run never answers it for you. * **When you turn down a plan,** Chat says you didn't approve it, and Claude waits for your next message. * **When you stop Claude or say no to a permission,** Chat says you stopped it and marks that step "stopped by you". ## Permission modes [#permission-modes] The mode buttons in the session header (**Ask me first**, **Auto-edit**, **Autopilot**) change how much the AI Employee does on its own. On a phone, they are under **More**, in **Permission mode**. A change applies when the session restarts. ## Watch someone else's session [#watch-someone-elses-session] Anyone on the team can open a teammate's session and watch it live, unless the team or the session owner limited who can see it. Only the owner can type. To hand a session to someone else, a team owner can reassign it. Schedules that run on the session can move to the new owner in the same step; see [When a session is reassigned](/docs/schedules/#when-a-session-is-reassigned). The session owner types. Viewers, editors and team owners on the team can watch and read the chat view. ## Related [#related] --- # Team files URL: /docs/vscode/files Open a team's folder in the Explorer, edit and save its files on the AI Team Cloud Computer, and search them with HQ's own search. ## Open a team's files [#open-a-teams-files] In the HQ sidebar's **Teams** view, press the folder icon on a team, or right-click it and choose **Open Team Files**. **HQ: Open Team Files** in the Command Palette asks you to pick a team. The team's folder appears in the Explorer, named after the team and its organization, for example `Backend team (Acme)`. Its address starts with `hq://`. Open, edit and save files as usual; every save goes to the AI Team Cloud Computer. With more than one HQ account signed in, the name also shows the account, for example `Backend team (Acme) · owner@client`. Opening a second team adds a second folder to the same window. Remove a folder from the window the usual way (right-click it, **Remove Folder from Workspace**). Changes made on the AI Team Cloud Computer, by an AI Employee or a teammate, show up in the editor within a few seconds. If someone changed a file after you opened it, saving it says "This file changed on the AI Team Cloud Computer. Save again to compare." Save again and the editor offers to compare the two versions or overwrite. ## Folders and accounts [#folders-and-accounts] A folder works as the account that opened it, whichever account the window uses now. Its address carries that account (`hq://a3f9c01b7e2d4@acme/hq-3f9a1c2e/`), so it opens as the same account after a reload, from **Open Recent**, or from a saved workspace. * **The same team from two accounts.** If both of your accounts can reach a team, you can open it from each. They are two folders, each named with its account, each reading and saving as its own account. Save one and the other shows the change like a teammate's. * **A folder whose account is not signed in** shows nothing and says "This folder belongs to [owner@client.com](mailto:owner@client.com), who is not signed in on this computer." with **Sign in as [owner@client.com](mailto:owner@client.com)**. Sign in as that account and the folder fills in, and a file you tried to open shows its contents, without a reload or a refresh. The message goes away once you are signed in. A file that could not open because the team was off opens by itself once the team is running. Only tabs that could not open come back this way (at the end of their group); tabs that were already open, or have unsaved changes, are left exactly as they are. A compare view or an image preview that could not open needs opening again. If you approve as someone else, the folder stays as it is. * **Folders opened before version 0.2.0** have addresses without an account (`hq://acme/hq-3f9a1c2e/`). They keep opening as the account you used then. * Folder names are saved in your `.code-workspace` file, so the short account name is too. ## When a file is read only [#when-a-file-is-read-only] | You see | Why | | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "You can view this team but not change its files." | You have viewer access to the team. | | "Your plan is read-only. Reactivate billing in HQ to save files or start sessions." | Your organization's plan does not allow changes right now. | | "This file came from an AI Workforce One HQ template, so it is read-only." | On a team created from a template, `.claude/` and the template's manifest cannot be changed from any HQ app. | | "This file contains masked secret values. Edit it from an HQ terminal." | The file holds a value from the team's secrets. You see it masked, as in HQ, so it cannot be saved from here. When you open it, the extension says which secret, for example "STRIPE_KEY", if you can use the team's terminals. A teammate's personal secret is masked too, but only its owner sees its name. Read the value from `$STRIPE_KEY` instead of keeping it in the file. When a secret is changed or removed in HQ, open files pick up the change by themselves within about 15 seconds. The old value stays masked for as long as the team exists, so text that still holds it is not shown in clear. | | "This file is too large to open here. Open it in HQ or from a terminal." | Text files up to 8 MB open here (binary files up to 64 MB). Files over 16 MB open read only. | ## When the AI Team Cloud Computer goes to sleep [#when-the-ai-team-cloud-computer-goes-to-sleep] An AI Team Cloud Computer nobody is using goes to sleep after a while, and wakes when someone comes back. VS Code keeps it awake only while you are working with it: opening a team folder or a terminal while the team is running, opening or saving a file, typing in a terminal, or using a forwarded port. A VS Code window left open does not keep it awake, and neither does VS Code reconnecting by itself. VS Code keeps the team awake while you open, read or save files; typing in an open file counts once you save. VS Code 0.1 windows still count their hourly reconnects as you being there, until they are updated to 0.2.0. In HQ in the browser, a team page or a terminal counts while it is on screen and you are at it: the window has focus, or you used the mouse, keyboard or touch screen in the last 10 minutes. What else keeps a Cloud Computer awake, including a question Claude asked that nobody answered, is in [When a Cloud Computer sleeps](/docs/ai-teams/sleep/). ## When the AI Team Cloud Computer is off [#when-the-ai-team-cloud-computer-is-off] Folders and files you already opened stay readable. Opening a new file, or saving, says, for example, "Backend team is off. Wake it to open this file." (or "to save this file") with a **Wake Team** link. Opening and reading files never wakes an AI Team Cloud Computer by itself. Once the team runs again (woken here, in HQ, or by a session), the notice closes by itself, and a file or folder that failed while it was off opens on its own, with no **Try Again** or **Refresh**. If the Cloud Computer is updating, the extension says when its files are back. If it needs an update first, the team shows `update needed` and the extension offers **Open Team Settings**, where a team owner (or an organization owner or admin) presses **Update Cloud Computer**. ## Search a team's files [#search-a-teams-files] Right-click a team and choose **Search in Team Files**, or run **HQ: Search in Team Files**. With an `hq://` file open, the search runs on that file's team. Type what to find, then pick options: **Match case**, **Whole word**, and **Regular expression** when you can edit the team. Then, optionally, the files to include and to exclude, as comma-separated patterns such as `src/**, *.ts`. The results appear in the **Search** view of the HQ sidebar, grouped by file. Click one to open the file at that line. The search runs on the AI Team Cloud Computer, so it covers every file, not only the ones you opened. A line that holds a secret value is left out of the results. When there are too many results, the view says "more were found; narrow the search". ## Good to know [#good-to-know] * Editors give team files basic support: syntax colors everywhere, and TypeScript and JavaScript features for the files you open. Language servers that need local files, such as most Python, Go and Rust tools, do not work on team files. Use a session terminal to run builds and tests. * The extension never runs anything from team files. * File contents are kept in the editor's memory only, never on this computer's disk, and are cleared when you sign out of the account they belong to. --- # VS Code overview URL: /docs/vscode The AI Workforce One HQ extension brings your HQ teams into VS Code, Cursor, Windsurf and VSCodium. Open a team's files, join its session terminals and forward its ports, with nothing installed on the AI Team Cloud Computer. The extension is at version 0.4.2, published on the Visual Studio Marketplace and on Open VSX. The extension talks only to HQ, with HQ's own permissions, and installs nothing on your AI Team Cloud Computers. Everything you see and do in VS Code is what your role on that team allows in HQ, and secrets stay masked, as in HQ. ## What it does [#what-it-does] * **Sign in** with **HQ: Sign In**. You approve this computer in HQ in your browser, the same way as `hq login`. The editor gets its own access, which you can remove at any time in HQ, under Account, Devices. * **Teams**: the AI Workforce One HQ sidebar lists your organizations, their teams (running, starting or off) and each team's sessions. * **Team files**: **Open Team Files** adds a team's folder to the Explorer. Open, edit and save its files, and search them on the AI Team Cloud Computer. * **Session terminals**: open any session you can see in a VS Code terminal. You type in your own sessions; other people's sessions are view only. Closing the terminal leaves the session running. * **Ports**: forward a port from an AI Team Cloud Computer to `localhost` on this computer and open it in your browser. Ports the Cloud Computer is listening on are offered to you. ## Before you start [#before-you-start] * **VS Code 1.90 or newer**, or Cursor, Windsurf or VSCodium. * **An HQ account** in at least one organization. * **Developer access on** for your organization. An organization owner turns it on in HQ, under Settings, Security, Developer access. Until then the Teams view says "No org has developer access on yet." * **Access to the team.** What you can do depends on your role on each team: | On a team, you can... | Viewer | Editor or owner | | ---------------------------- | ---------- | ------------------------------------ | | Open its files | Read only | Read and save (needs an active plan) | | Search its files | Plain text | Plain text and regular expressions | | Open its session terminals | Watch | Watch, and type in your own sessions | | Start a new session terminal | No | Yes (needs an active plan) | | Forward a port | No | Yes (needs an active plan) | | Wake its Cloud Computer | Yes | Yes | ## Quick start [#quick-start] Search for **AI Workforce One HQ** in the Extensions view and install it. See [Install](/docs/vscode/install/) for Cursor, Windsurf and VSCodium. Open the AI Workforce One HQ icon in the Activity Bar and press **Sign in**, or run **HQ: Sign In** from the Command Palette. Type the code in the HQ page that opens, and approve this computer. In **Teams**, right-click a team and choose **Open Team Files**, or open one of its sessions to join its terminal. ## Next [#next] The Marketplace, Open VSX, and updating. The device approval, where the sign-in is kept, and signing out. Every command, view and setting the extension adds. --- # Install URL: /docs/vscode/install Install AI Workforce One HQ from the Visual Studio Marketplace in VS Code, or from Open VSX in Cursor, Windsurf and VSCodium. The extension's id is `aiworkforceone.awo-hq` and its name is **AI Workforce One HQ**. It needs VS Code 1.90 or newer. Version 0.4.2 is a regular release. Earlier 0.1 versions were pre-releases; if your editor still has a 0.1 pre-release installed, update it to 0.4.2. ## VS Code [#vs-code] Open the Extensions view (`Ctrl+Shift+X`, or `Cmd+Shift+X` on macOS), search for **AI Workforce One HQ**, and install it. The publisher is **aiworkforceone**. ```bash code --install-extension aiworkforceone.awo-hq --pre-release ``` The listing is on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=aiworkforceone.awo-hq). ## Cursor, Windsurf and VSCodium [#cursor-windsurf-and-vscodium] These editors install extensions from Open VSX. Open the Extensions view, search for **AI Workforce One HQ**, and install it. The listing is on [Open VSX](https://open-vsx.org/extension/aiworkforceone/awo-hq). ## From a release file [#from-a-release-file] Every version is also on [GitHub](https://github.com/aiworkforceone/awo-hq-vscode/releases) as an `awo-hq-.vsix` file, with a `SHA256SUMS` file to check it. In the Extensions view, open the `...` menu, choose **Install from VSIX...**, and pick the file. An extension installed this way does not update on its own. ## Check that it worked [#check-that-it-worked] The AI Workforce One HQ icon appears in the Activity Bar. Open it: the **Teams** view says "Sign in to see your teams." Next, [sign in](/docs/vscode/sign-in/). ## Update [#update] Your editor updates extensions on its own unless you turned that off. To update by hand, open the Extensions view and choose **Check for Extension Updates** from its `...` menu. When HQ no longer accepts an old version, the extension says "This version of AI Workforce One HQ is no longer supported. Update it from the Extensions view." ## Uninstall [#uninstall] Run **HQ: Sign Out** first, so HQ ends this computer's access, then uninstall the extension from the Extensions view. If you already uninstalled it, remove the editor in HQ, under Account, Devices. ## Good to know [#good-to-know] * The extension always runs on your own computer, also in a remote window (WSL, a dev container or another remote host), so your sign-in and your forwarded ports stay on this computer. * It sends no telemetry and talks only to your HQ address. ## Next [#next] Approve this computer in HQ. Open a team's folder in the Explorer. --- # Ports URL: /docs/vscode/ports Forward a port from an AI Team Cloud Computer to localhost on this computer, open it in your browser, and forward the ports a session starts. ## Forward a port [#forward-a-port] In a session, start whatever listens on the port, for example a dev server on port 3000. It must use a port from 1024 to 65535. Press **+** in the HQ sidebar's **Ports** view, or right-click a team and choose **Forward a Port...**. Type the AI Team Cloud Computer's port, then the port on this computer (leave it as it is to use the same number). The Ports view lists the forward as `3000 → localhost:3000`, with the team's name (and, with more than one HQ account signed in, the account, as in `Backend team · owner@client`). Its buttons open it in your browser (**Open in Browser**), copy `http://localhost:3000` (**Copy Local Address**), and stop it (**Stop Forwarding**). You need editor or owner access to the team and an active plan. Starting a forward wakes an AI Team Cloud Computer that is off. The status bar counts your active forwards; click the count to open the Ports view. ## Ports a session starts [#ports-a-session-starts] While one of a team's sessions is open in a terminal, the Ports view lists the ports its Cloud Computer starts listening on, as `8000 detected · Forward?`. Press **Forward** to forward it to the same port on this computer, or **Dismiss** to hide it. ## After a reload [#after-a-reload] Forwards that were running when you closed the window come back **paused** (`paused · click to resume`). Click one to start it again. They never start, or wake a Cloud Computer, on their own. A forward that HQ ended is paused too, and the extension says "The forward of port 3000 ended." A window brings back the paused forwards of the account it uses. Paused forwards are kept per account, and if two windows had forwards open on the same account, the ones that come back are those of the last window that had any open. ## Good to know [#good-to-know] * A forwarded port listens on `127.0.0.1` only, so other computers on your network cannot reach it. Any program on this computer can, while the forward is open. * On the AI Team Cloud Computer, a forward reaches whatever listens on that port, including another member's dev server. * HQ refuses some ports: the Docker API (2375 and 2376), the Node debugger (9229 and 9230), and ports the AI Team Cloud Computer uses itself. The extension says "Port 2375 cannot be forwarded: the AI Team Cloud Computer uses it itself." * A forward works as the account that started it, whichever account the window uses now. Signing out of that account stops it, in every window; other accounts' forwards keep running. * If another window renews the forward's account, the forward restarts on the same local port. * A port offered from a session terminal forwards as that terminal's account. * If Developer access was turned on after the team's Cloud Computer started, forwarding waits for one restart. The team's **Settings** in HQ say "Restart needed so port forwarding works", and an organization owner or admin presses **Restart Cloud Computer** there. Sessions pause for about two minutes and come back where they were. ## Related [#related] Start a server from a session terminal. Refused and ended forwards. --- # Commands and settings URL: /docs/vscode/reference Every command, view and setting the AI Workforce One HQ extension adds to your editor. This page lists what the extension adds in version 0.4.2. ## Commands [#commands] Run these from the Command Palette (`Ctrl+Shift+P`, or `Cmd+Shift+P` on macOS). Most are also buttons or right-click items in the HQ sidebar. | Command | What it does | Also in | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | | **HQ: Sign In** | Approve this computer in HQ in your browser. Shown while this window has no account. With accounts already signed in on this computer, it opens **Choose an account** instead. | Teams and Account views | | **HQ: Sign Out** | Sign out of the account this window uses: end its access in HQ and close its terminals and forwards in every window. Asks first when more than one account is signed in. | Account view (icon beside each account) | | **HQ: Add Another Account** | Sign in to one more HQ account. Sign the browser in as that account first. | Account view, Teams view title (**+**) | | **HQ: Switch Account** | Choose which account this window uses. Nothing closes. | Status bar (with more than one account), Teams view title, Account view (click an account) | | **HQ: Sign Out of Account...** | Choose an account to sign out of. | Account view, **Choose an account** (icon beside each account) | | **HQ: Refresh** | Reload your organizations, teams and sessions. | Teams view title | | **HQ: Open Team Files** | Add a team's folder to the Explorer. | Team row (folder icon), right-click a team | | **HQ: Search in Team Files** | Search a team's files on its AI Team Cloud Computer. | Right-click a team | | **HQ: Attach** | Open a session in a terminal. | Session row (click it), right-click a session | | **HQ: New Session Terminal** | Start a new session on a team and open it. Needs editor or owner access. | Team row (**+**), right-click a team | | **HQ: Wake Team** | Start an AI Team Cloud Computer that is off. | Team row (play icon), right-click a team that is off | | **HQ: Forward a Port...** | Forward an AI Team Cloud Computer's port to this computer. Needs editor or owner access. | Ports view title (**+**), right-click a team | | **HQ: Open in HQ Web** | Open the team or session in HQ in your browser. | Right-click a team or a session | | **HQ: Manage Devices in HQ** | Open Account, Devices in HQ, where you can remove this computer. | Account view | These act on one row of the Teams, Ports or Search view, and are not in the Command Palette: | Command | Where | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Start Session** | A stopped session you may operate, in the Teams view (play icon, or right-click). | | **Stop Session** | A running session you may operate, in the Teams view (stop icon, or right-click). Asks first while it is answering. | | **Restart Session** | A running session you may operate, in the Teams view (restart icon, or right-click). Asks first while it is answering. | | **Open in Browser** | An active forward in the Ports view. | | **Copy Local Address** | An active forward in the Ports view. | | **Stop Forwarding** | An active or paused forward in the Ports view. | | **Resume Forwarding** | A paused forward in the Ports view (or click the row). | | **Forward** | A port the Cloud Computer started listening on, in the Ports view. | | **Dismiss** | A port the Cloud Computer started listening on, in the Ports view. | | **Open** | A result in the Search view (or click the row). | ## Views [#views] The AI Workforce One HQ icon in the Activity Bar opens the HQ sidebar: | View | What it shows | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Teams** | Your organizations, their teams (`running`, `starting` or `off`, plus `update needed` and `view only` when they apply) and each team's sessions. | | **Ports** | Your forwards (active and paused) and the ports an AI Team Cloud Computer started listening on. | | **Search** | The results of **HQ: Search in Team Files**. Shown after your first search. | | **Account** | Every account signed in on this computer (the one this window uses marked "Active in this window"), each with a sign-out icon and **Manage devices in HQ**, then **Add another account...** and the HQ address. An account whose sign-in needs renewing says "Sign in again"; click it. | The Teams view shows the teams of the account this window uses; its title shows that account's email. The status bar shows `HQ:` and the email of the account this window uses, plus the team and its state while an HQ terminal is the active one (`· other account` when that terminal works as another account). Click it to open the HQ sidebar, or, with more than one account signed in, **Choose an account**. A second item counts your active forwards. A command that needs an account (Wake Team, New Session Terminal, Attach, Forward a Port, Open Team Files, Search in Team Files, Refresh) uses the account of the row you ran it on, else the window's. In a window that has no account, it asks you to choose one first. ## Settings [#settings] All three are user settings: a team folder's own settings cannot change them. | Setting | Default | What it does | | ----------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `hq.localEcho` | `auto` | Local echo in HQ session terminals: `auto`, `always` or `off`. See [Local echo](/docs/vscode/terminals/#local-echo). | | `hq.host` | `https://hq.aiworkforceone.com` | The HQ address this editor signs in to. For AI Workforce One staff; leave it as it is. Changing it needs a new sign-in. | | `hq.allowedHosts` | `[]` | Extra HQ addresses this editor may sign in to. For AI Workforce One staff. | ## Team file addresses [#team-file-addresses] A team's folder opens at `hq://@//`, where `` is a short code for the HQ account that opened it and `` is the team's `hq-…` name, the same one `hq status` prints. For example `hq://a3f9c01b7e2d4@acme/hq-3f9a1c2e/src/app.py`. The code is not a password: it only picks among the accounts already signed in on this computer. Folders opened with version 0.1 have no account code (`hq://acme/hq-3f9a1c2e/`). They keep opening as the account that was signed in then. --- # Sign in URL: /docs/vscode/sign-in Sign in by approving this computer with a one-time code that you type into HQ in your browser. Your editor gets its own access, separate from the hq CLI. ## Sign in [#sign-in] Press **Sign in** in the Teams view, or run **HQ: Sign In** from the Command Palette (`Ctrl+Shift+P`, or `Cmd+Shift+P` on macOS). The extension asks HQ for a one-time code, copies it to your clipboard, and opens HQ's approval page in your browser: ```text Enter BCDF-GHJK in the browser (copied). Waiting for approval. ``` Press **Cancel** on that message to stop. The message closes by itself once the sign-in is approved, cancelled or fails. Sign in to HQ if you are not already, then paste or type the code. The page never fills it in for you, so a link someone else sent you cannot approve their computer. Check that the device name matches yours (for example `Visual Studio Code on my-laptop`), pick the organizations it may reach, and confirm with your password or your two-factor code. The extension notices the approval within a few seconds and says "Signed in to AI Workforce One HQ as [you@example.com](mailto:you@example.com)." The Teams view fills in. Run **HQ: Sign In** again for a new one. Denying the request in the browser ends the sign-in at once. If you have more than one editor window open, sign in from one of them. The other windows say "Signing in to AI Workforce One HQ from another VS Code window. Wait for it to finish, or sign in here instead." A window that had no account yet uses the new one once the sign-in finishes. ## Its own access [#its-own-access] The extension gets its own access to HQ, separate from `hq login`. Each one is listed in HQ, under Account, Devices, and each can be removed on its own. **Manage devices in HQ**, in the extension's Account view, opens that page. ## Use more than one account [#use-more-than-one-account] You can be signed in to more than one HQ account at once, for example your agency account and a client's own account. Each window works as one of them, and two windows can work as two accounts at the same time. The browser approves as whoever is signed in to HQ in it. Sign out of HQ in the browser and sign in as the account you want to add, or use a private window. The approval page says who is approving: "Approving as [owner@client.com](mailto:owner@client.com) · Not you? Sign out". Press **Add another account...** in the **Account** view, the **+** in the Teams view's title bar, or run **HQ: Add Another Account**. In VS Code's Accounts menu, signing in to AI Workforce One HQ again does the same. Approve the code in the browser as before. The extension says "Signed in to AI Workforce One HQ as [owner@client.com](mailto:owner@client.com). This window now uses it." * **Each account is its own access.** Each one is its own row in HQ, under Account, Devices, and can be removed on its own. * **Switch the window's account** from the status bar: with more than one account signed in, clicking it opens **Choose an account**. The Account view and **HQ: Switch Account** do the same. Switching changes what this window's Teams view shows and which account new terminals, folders and forwards use. Terminals, folders and forwards you already opened stay open, each working as the account that opened it. * **Names show the account.** With more than one account signed in, folder names, terminal tabs and port rows end in a short form of the account, such as `owner@client`. * **Each VS Code profile keeps its own accounts.** In a new profile, sign in again. If the browser approves as an account that is already signed in here, nothing is added: "The browser approved this sign-in as [a@agency.com](mailto:a@agency.com), who is already signed in here, so it was not kept. ..." The extension ends that new access in HQ at once. ### Going back to version 0.1 [#going-back-to-version-01] If you install version 0.1 again, the account you used with 0.1 keeps working, with no new sign-in. Version 0.1 shows only that account. Folders opened in 0.2 as another account do not open there ("This team is not available on this sign-in."); they never open as the 0.1 account. The other accounts' access stays listed in HQ, under Account, Devices: remove the ones you no longer use. Updating to 0.2 again brings every account back, with no sign-in. ## Where the sign-in is kept [#where-the-sign-in-is-kept] In your editor's secret storage on this computer: the system keychain on macOS and Windows, and the Secret Service (for example GNOME Keyring or KWallet) on Linux. On Linux without a keyring, the editor keeps it with weaker protection, and the extension says so once: "Your HQ sign-in is stored without the system keychain on this computer." ## Check who is signed in [#check-who-is-signed-in] The status bar shows `HQ:` and the email of the account this window uses. The **Account** view in the HQ sidebar lists every account signed in on this computer, marks the one this window uses "Active in this window", and has **Manage devices in HQ** under each, **Add another account...** and the HQ address. **Manage devices in HQ** opens HQ in your browser, signed in as whoever the browser is signed in as. ## Sign out [#sign-out] Run **HQ: Sign Out** to sign out of the account this window uses, or press the sign-out icon beside an account in the Account view or in **Choose an account**. With more than one account signed in, the extension asks first: "Sign out of [a@agency.com](mailto:a@agency.com)? Its HQ terminals and port forwards close in every window." HQ ends that account's access, and its terminals and port forwards close in every window. Other accounts are not touched. A window that was using the account you signed out of shows "You have other HQ accounts signed in on this computer." with **Switch Account** and **Add Another Account**; it never switches to another account on its own. If HQ cannot be reached, the extension still signs you out on this computer and says "Signed out on this computer. HQ could not be reached to end this computer’s access; remove it in HQ, under Account, Devices." ## When access ends from HQ [#when-access-ends-from-hq] If you or an admin remove this computer in HQ, or an account's access ends another way, the extension says "Your access to HQ as [a@agency.com](mailto:a@agency.com) ended on this computer. Sign in again, or switch to another account.", closes that account's terminals and port forwards, and offers **Sign in**. If your sign-in needs renewing, the extension says "Your HQ sign-in as [a@agency.com](mailto:a@agency.com) needs renewing." Press **Sign in** and approve as that same account. If the browser approves as someone else, that approval is ended at once and the extension says "You approved as [owner@client.com](mailto:owner@client.com), but this account is [a@agency.com](mailto:a@agency.com). ..." Sign the browser in as the right account and try again. ## The HQ address [#the-hq-address] The extension signs in to `https://hq.aiworkforceone.com`. The `hq.host` and `hq.allowedHosts` settings exist for AI Workforce One staff; leave them as they are. Changing the address needs a new sign-in. ## If it fails [#if-it-fails] | Message | What to do | | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | "The sign-in was denied in the browser." | Someone chose Deny on the approval page. Sign in again. | | "This sign-in code expired. Sign in again." | The 10 minutes ran out. Start over. | | "HQ for VS Code is not available on this HQ yet." | This HQ address does not offer the extension. Check `hq.host`. | | "Could not sign in: ..." | Read the reason. If it says HQ could not be reached, check your connection. | | "Your HQ sign-in as [a@agency.com](mailto:a@agency.com) needs renewing." | Press **Sign in** and approve as that account. | | "You approved as [owner@client.com](mailto:owner@client.com), but this account is [a@agency.com](mailto:a@agency.com). ..." | The browser was signed in as another account. Sign the browser in as [a@agency.com](mailto:a@agency.com), then sign in again. | | "The browser approved this sign-in as [a@agency.com](mailto:a@agency.com), who is already signed in here, so it was not kept. ..." | To add another account, sign the browser in as that account first. | | "Too many HQ sign-ins were started from this network. Wait a minute and try again." | Wait a minute, then sign in again. | More in [Troubleshooting](/docs/vscode/troubleshooting/). --- # Terminals and local echo URL: /docs/vscode/terminals Open an HQ session in a VS Code terminal, start a new one, wake an AI Team Cloud Computer, and see what you type at once with local echo. The person who started a session is the only one who can type in it. Everyone else who opens it watches it live, view only. To work yourself, start your own session. ## Open a session [#open-a-session] In the HQ sidebar's **Teams** view, expand a team and click one of its sessions. It opens in a VS Code terminal named `HQ · · `. **HQ: Attach** in the Command Palette asks you to pick a team and a session. With more than one HQ account signed in, the name also shows the account: `HQ · owner@client · Backend team · main`. A terminal works as the account that opened it. Switching the window's account leaves it open, still working as that account. The first line says whose session it is, and whether you can only watch: ```text Attached to "fix login bug" (Dana) · view only ``` Each session row shows who started it (`you` for your own), `starting` while HQ is still starting it, `view only` when you cannot type in it, and `Codex` for a Codex session. Clicking a session that is already open shows its terminal. **Closing the terminal leaves the session running in HQ.** Open it again any time. ## Start a new session [#start-a-new-session] Press **+** on a team, or right-click it and choose **New Session Terminal**. HQ starts a new session on that team and opens it in a terminal. You need editor or owner access to the team and an active plan; when the team is at its session limit, the extension says so. ## Start, stop and restart a session [#start-stop-and-restart-a-session] Each session row has buttons for what you may do with it, and the same items when you right-click it: * **Start Session** (play icon) on a stopped session. A team that is off starts for it, as when you press Start in HQ. Start on a session that is already starting says so: "Session "fix login bug" is already starting." * **Stop Session** and **Restart Session** on a running session. Restart stops it and starts it again, resuming its conversation. When Claude or Codex is answering in the session right now, Stop and Restart ask first, for example "Claude is answering in "fix login bug" right now. Stop it anyway?". Only **Stop Session** (or **Restart Session**) goes ahead. Only the session owner or a team owner can start, stop or restart a session, as in HQ. On a session you can only watch, the buttons do not show. When HQ refuses, a notification says why, for example when the team is at its session limit, or "Too many requests. Try again in 34 seconds." with the wait HQ asked for. The Teams view refreshes afterwards. Each start, stop and restart is recorded in your organization's Audit log in HQ as coming from VS Code. The computer's name shows to people who can manage remote access; others see a short device id. ## Paste or drop an image [#paste-or-drop-an-image] Give Claude a screenshot or a picture the way you would on your own computer: * **Paste it.** Copy an image, click in the session terminal and press **Cmd+V** (macOS) or **Ctrl+V** (Windows and Linux; **Ctrl+Shift+V** works too on Linux). "Uploading image..." shows, then the image's path appears at the prompt, for example `.uploads/pasted-20261002-101500-3f2a.png`. Describe what you want and press Enter. * **Drop it.** Drag image files from your computer onto the terminal. The extension asks first, for example "Upload \~/Desktop/screenshot.png to Backend team?": **Upload** adds each file and types its path; **Type the path** types your computer's path as it was, with nothing uploaded. * **From the team's own files.** Drag an image from the team's folder in the Explorer: its path in the team is typed, with nothing uploaded. Files from another team's folder are not added. PNG, JPEG, GIF and WebP images up to 10 MB are added, into the team's `.uploads` folder. When the clipboard holds text, it pastes as text, even if the copy also carries a picture (a copy from a spreadsheet or a slide does). An upload that does not finish within 30 seconds stops with "The image upload did not finish." If one file of several fails, the ones already added stay in `.uploads`, and **Cancel** during an upload may still leave that file in `.uploads` (nothing is typed). On Linux, image paste needs `wl-paste` (Wayland) or `xclip` (X11); without them, Ctrl+V pastes text only. You need to be able to change the team's files: with view access, the extension says so and adds nothing. ## When the AI Team Cloud Computer is off [#when-the-ai-team-cloud-computer-is-off] A team that is not running shows `off` in the Teams view. Two ways to start it: * **Wake Team**: press the play icon on the team, or right-click it and choose **Wake Team**. A notification shows the progress, "Waking Backend team... this usually takes 15-30 seconds" (30-45 seconds on Boost Max), then "Backend team is running." A team that is stopped (not asleep) cannot be woken: the message offers **Start a Session**, which starts its Cloud Computer. * **Open one of its sessions.** The terminal says "Backend team is off." and "Press any key to wake it." The next key you press wakes it, and the terminal connects when the Cloud Computer is ready. After 30 seconds (45 on Boost Max) the progress says "Taking longer than usual, still working.". If the Cloud Computer has not started within 3 minutes, the extension says so; check the team in HQ and try again. Viewers can wake a team too. ## When the connection drops [#when-the-connection-drops] The terminal reconnects on its own. HQ's connections are renewed about once an hour; the terminal moves to a fresh connection before that happens, with nothing to see and no keystroke lost. If the connection drops anyway, the terminal reconnects quietly, and says "Connection lost, reconnecting..." only when reconnecting takes more than a few seconds or the connection drops again. If it cannot reconnect, it says "The connection to HQ was lost." and "Press any key to reconnect.": the next key you press reconnects it in the same tab (that key is not typed into the session). When a session ends on HQ's side, for example because it was stopped, the terminal stays open with the reason, and its name ends in `· stopped`. Press any key to reconnect, or close it. Attaching a session whose terminal has ended (for example after VS Code restarted its extensions) opens a fresh terminal instead of the ended one. When the session's process is restarted on the AI Team Cloud Computer, the terminal clears and shows the new one by itself, at the terminal's width. If VS Code restarts its extensions (for example after an update), the HQ terminals that were open come back by themselves in fresh tabs. ## The same session in two places [#the-same-session-in-two-places] A session has one terminal size on the AI Team Cloud Computer. When the same session is open in more than one place, for example in HQ in your browser and in a VS Code terminal, or in two VS Code windows, the place you are using sets that size: * **The terminal in front sets it.** Clicking into the HQ terminal, switching to it, or bringing its VS Code window to the front gives the session this terminal's size. So does typing in it. * **The others follow it.** A terminal that is not in front draws the session at that size and redraws its screen once, so nothing overlaps or breaks mid-word. When its panel is larger, the extra space stays empty; when its panel is narrower than the session, it shows as much as fits until you bring it to the front. * **Watching never changes the size.** A view-only terminal follows the size of the one that can type, and never sets it. * **A very small terminal never sets it.** One smaller than 40 columns or 10 rows keeps showing the session at the other place's size, so it cannot shrink the session for everyone. * **A new size waits while Claude Code is writing.** If the size changes while Claude Code is writing an answer, the session takes the new size once it stops writing text, and never more than 30 seconds later. That keeps the part of the answer that has already scrolled up from being drawn twice for everyone who opens the session later. This terminal resizes at once, so until the session catches up it can show a few lines laid out for the old width. At a prompt, or while a tool runs, the first size change applies at once. Codex sessions always change size at once. ## Local echo [#local-echo] On a slow connection, local echo draws your keystrokes the moment you press them, before the AI Team Cloud Computer echoes them back. It only applies in sessions you can type in. Set it with the `hq.localEcho` setting: | Value | Behavior | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auto` | Show what you type at once where the session's prompt allows it, while the round trip to the AI Team Cloud Computer is slower than 60 ms. This is the default. | | `always` | Always show what you type at once. | | `off` | Show only what the session echoes back. | The setting applies to terminals you open after changing it. * **Your organization has to allow it.** An owner or admin turns on **Instant local echo** in HQ, under Settings, Security. When it is off, the extension says so once and the terminal works without it. * **VS Code has a local echo of its own.** When VS Code's own is on for a terminal (`terminal.integrated.localEchoEnabled`), HQ's local echo stays off there, so nothing is drawn twice, and the terminal says so. To use HQ's, set `terminal.integrated.localEchoEnabled` to `off`. ## Good to know [#good-to-know] * While an HQ terminal is the active one, the status bar shows its account, its team and whether it is running. When the terminal works as another account than the window's, the status bar ends in `· other account`. * If another window renews the terminal's account, the terminal says "Connection lost, reconnecting..." and comes back in the same tab. * When a session starts a server on a port, the **Ports** view offers to forward it. See [Ports](/docs/vscode/ports/). * Signing out of an account closes that account's HQ terminals, in every window. The sessions keep running in HQ. ## Related [#related] Reach a port on the AI Team Cloud Computer from this computer. Every message the extension shows, and what to do. --- # Troubleshooting URL: /docs/vscode/troubleshooting The messages the AI Workforce One HQ extension shows, what each one means, and the fix. In the messages below, "Backend team" and "Acme" stand for your team's and your organization's names. ## Signing in [#signing-in] | Message | What to do | | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | "Sign in to see your teams." | Press **Sign in**, or run **HQ: Sign In**. | | "No org has developer access on yet. An org owner turns it on in HQ, under Settings, Security." | An organization owner turns on **Developer access** in HQ, under Settings, Security. Then run **HQ: Refresh**. | | "The sign-in was denied in the browser." | Someone chose Deny on the approval page. Sign in again. | | "This sign-in code expired. Sign in again." | The 10 minutes ran out. Start over. | | "HQ for VS Code is not available on this HQ yet." | This HQ address does not offer the extension. Check the `hq.host` setting. | | "Signing in to AI Workforce One HQ from another VS Code window. Wait for it to finish, or sign in here instead." | Finish the sign-in in the other window, or press **Sign in here instead**. | | "Your HQ sign-in as [a@agency.com](mailto:a@agency.com) needs renewing." | Press **Sign in** and approve as that account. | | "Your access to HQ as [a@agency.com](mailto:a@agency.com) ended on this computer. Sign in again, or switch to another account." | That account was removed in HQ, or its access ended. Sign in again, or switch to another account. | | "Too many HQ sign-ins were started from this network. Wait a minute and try again." | Wait a minute, then sign in again. | ## More than one account [#more-than-one-account] | Message | What to do | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | "Signed in to AI Workforce One HQ as [owner@client.com](mailto:owner@client.com). This window now uses it." | Not an error: the account was added and this window uses it. | | "The browser approved this sign-in as [a@agency.com](mailto:a@agency.com), who is already signed in here, so it was not kept. To add another account, sign in to HQ in your browser as that account first." | The browser was signed in as an account you already have here. Sign the browser in as the account to add (or use a private window), then add it again. | | "You approved as [owner@client.com](mailto:owner@client.com), but this account is [a@agency.com](mailto:a@agency.com). Sign in to HQ in your browser as [a@agency.com](mailto:a@agency.com), then try again." | A renewal was approved as another account; that approval was ended. Sign the browser in as [a@agency.com](mailto:a@agency.com) and sign in again. | | "HQ could not be reached to undo that sign-in. Remove the newest computer in HQ, under Account, Devices." | The extension could not end an approval it did not keep. Remove the newest entry in HQ, under Account, Devices. | | "This sign-in could not be stored: another VS Code profile on this computer holds one for the same account. It was not kept." | Sign in again. If it repeats, email support. | | "Sign out of [a@agency.com](mailto:a@agency.com)? Its HQ terminals and port forwards close in every window." | Not an error: confirm to sign out of that account only. | | "Signed out of [a@agency.com](mailto:a@agency.com). Other accounts stay signed in." | Not an error: only that account was signed out. | | "You have other HQ accounts signed in on this computer." | This window's account was signed out. Press **Switch Account** or **Add Another Account**. | | "Could not read your HQ sign-in for [a@agency.com](mailto:a@agency.com) from the keychain. Unlock it and try again." | Unlock your system keychain, then try again. Nothing was signed out. | | An account says "Sign in again" in the Account view | Its sign-in cannot be used on this computer. Click it and approve as that account. | | "... is not an HQ address this editor may use. ..." | Set `hq.host` back to `https://hq.aiworkforceone.com`. | | "The HQ address changed. Sign in again to use it." | `hq.host` changed. Sign in again. | | "Your HQ sign-in is stored without the system keychain on this computer." | Not an error. On Linux, start a keyring (for example GNOME Keyring or KWallet) and sign in again if you prefer the keychain. | | "This version of AI Workforce One HQ is no longer supported. Update it from the Extensions view." | Update the extension. | | "HQ could not be reached. Check your connection and try again." | Check your network, then try again. | ## Teams and sessions [#teams-and-sessions] | Message | What to do | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A team shows `off` | Its AI Team Cloud Computer is not running. Press **Wake Team**, or open one of its sessions and press a key. | | A team shows `update needed` | Its Cloud Computer needs an update for the extension. A team owner (or an organization owner or admin) presses **Update Cloud Computer** in HQ, under the team's Settings. | | A team or session shows `view only` | You have viewer access to the team, or the session is someone else's. You can watch but not type or save. | | "Could not load sessions" | Run **HQ: Refresh**. If it repeats, open the team in HQ. | | "Backend team did not start within 3 minutes. Check it in HQ and try again." (4 minutes on the sizes from 80 GB) | Open the team in HQ to see its state, then try again. | | "Backend team is stopped. Wake only resumes a sleeping team: start a session to start its Cloud Computer." | Press **Start a Session** in that message (or start one in HQ). Wake Team only resumes a team that went to sleep. | | "Too many wake requests for this team. Wait a few minutes and try again." | Wait a few minutes. | | "This team is at its session limit. Stop a session in HQ, then try again." | Stop a session you no longer need. | | "Could not start a session: This AI Team's Cloud Computer is busy right now, so another session could not start. Stop a session you no longer need, or move the team to a bigger size, then try again." | The team's Cloud Computer is too busy for another session. Stop a session you no longer need, or ask an owner to give the team a bigger size. | | "Your plan is read-only. Reactivate billing in HQ to save files or start sessions." | An owner updates billing in HQ. Reading still works. | | "You can view this team but not start sessions on it." | You need editor or owner access to start a session. | ## Terminals [#terminals] | Message | What to do | | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | "Backend team is off." / "Press any key to wake it." | Press a key to wake the Cloud Computer. | | "Connection lost, reconnecting..." | Progress: the terminal reconnects on its own. | | "The connection to HQ was lost." and "Press any key to reconnect." | Press a key in the terminal; it reconnects in the same tab. Opening the session again from the HQ panel also gives a fresh terminal. | | "You can watch this session but not type in it." | Your access changed while the terminal was open. You can still watch. | | "Your access to this session ended." | Your access changed, or the session was closed. | | "You cannot open this session from this computer." | Your access to the team or to Developer access changed. Run **HQ: Refresh**. | | "Instant local echo is off for Acme. ..." | An owner or admin turns on **Instant local echo** in HQ, under Settings, Security. The terminal works without it. | | "Local echo is not available on this HQ yet." | The terminal works without local echo. | | "HQ local echo is off in this terminal because VS Code's own local echo is on (terminal.integrated.localEchoEnabled)." | Set `terminal.integrated.localEchoEnabled` to `off` to use HQ's. | ## Files [#files] | Message | What to do | | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | "Backend team is off. Wake it to open this file." | Press **Wake Team**, then open the file again. Files you already opened stay readable. | | "Backend team is off. Wake it to save this file." | Press **Wake Team**, then save again. | | "This file changed on the AI Team Cloud Computer. Save again to compare." | Save again, then compare or overwrite. | | "You can view this team but not change its files." | You have viewer access to the team. | | "This file came from an AI Workforce One HQ template, so it is read-only." | Template files on a template team cannot be changed. | | "This file contains masked secret values. Edit it from an HQ terminal." | Change it from a session terminal, or the secret in HQ. After a secret is removed in HQ, the file unmasks by itself within about 15 seconds. | | "This file is too large to open here. Open it in HQ or from a terminal." | Use HQ or a session terminal for that file. | | "This file's name has control characters HQ can't open. Rename it on the Cloud Computer." | Rename the file from a session terminal. | | "This team is not available on this sign-in. Sign in, or refresh the Teams view." | Run **HQ: Refresh**, or sign in again. | | "This folder belongs to [owner@client.com](mailto:owner@client.com), who is not signed in on this computer." | Press **Sign in as [owner@client.com](mailto:owner@client.com)** and approve as that account. The folder fills in. | | "This folder belongs to an HQ account that is not signed in on this computer. Open it again from the Teams view." | Remove the folder and open the team again with **Open Team Files**. | | "Backend team's Cloud Computer is updating. Its files are back once it is done. This usually takes about 5 to 6 minutes." | Wait for the update to finish. | | "Live file updates for Acme are paused: ..." | Too many editor windows are open for this sign-in. Close other HQ windows. Files still refresh every minute. | | "The search did not run: ..." | Read the reason, then search again. | ## Ports [#ports] | Message | What to do | | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "Port 9229 cannot be forwarded: the AI Team Cloud Computer uses it itself." | Forward another port. HQ refuses the Docker API, the Node debugger and the Cloud Computer's own ports. | | "Backend team started before Developer access was turned on. Restart it once (Restart Cloud Computer in HQ team settings) and ports will forward." | Developer access was turned on while the Cloud Computer was running. An organization owner or admin presses **Restart Cloud Computer** in the **Cloud Computer** section of the team's **Settings** in HQ. Sessions pause and come back where they were. This usually takes about 5 to 6 minutes. | | "You cannot forward ports from Backend team." | You need editor or owner access and an active plan. | | "Backend team is off. Wake it, then forward the port again." | Press **Wake Team**, then forward again. | | "Backend team is stopped. Start it from the team page in HQ, then forward the port again." | Start the team in HQ. | | "Could not forward the port: the port is already in use on this computer" | Something on this computer already uses that port. Forward again and pick another port on this computer. | | "The forward of port 3000 ended." | HQ ended the forward. Click it in the Ports view to start it again. | ## The extension's log [#the-extensions-log] **View, Output**, then pick **AI Workforce One HQ** in the list: the extension records its sign-ins, accounts (by a short code, not your email) and sign-outs there. It never records a token, a key, a sign-in code or the contents of a file. ## Still stuck? [#still-stuck] Email [support@aiworkforceone.com](mailto:support@aiworkforceone.com) with the extension's version (in the Extensions view), your editor's name and version, the exact message, and the lines of the extension's log from around that time.