API changelog
What changed in the HQ API, by dated version.
2026-11-01
The first version of the HQ API.
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
Changed within this version, without a new version date.
-
New:
POST /schedules/{schedule_id}/move_to_session_ownermoves 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. -
PATCH /schedules/{schedule_id}that changes theprompt, thetarget_sessionorcreate_new_sessionof a schedule on someone's own Claude login (run_with: personal) answers403 session_not_ownedunless 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
promptthat contains a control character (tabs and line breaks are fine) or the textkr-run:is now refused with422 validation_failedonPOST /schedulesandPATCH /schedules/{schedule_id}, like a prompt that starts with/,!or#.detailsays which rule it broke. See Schedules. -
Files: a folder entry carries
protected. It is alwaysfalsefor 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.readwill getprotectedin 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. -
HQ-Accountis now refused with400 invalid_requeston any credential that is not an agency key. 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
succeedsonly 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 answers409 operation_conflict(it answered409 workspace_updatingin some cases). A refused request no longer leaves afailedoperation or sendsoperation.failed, and an update that starts nothing answers200with the computer (it answered afailedoperation). -
A move to a smaller tier on a running Cloud Computer answers
200with the computer and the newchange_pendingfield, not an operation: it applies at the next restart, as in HQ. -
A prompt to a sleeping Cloud Computer answers
queuedwithwaiting_for: "wake"(it answeredaccepted), and the event stream reportssession.statusasleepfor it (it saidunknown). -
Retrying
POST /webhook_endpointsor a secret roll with the sameIdempotency-Keyanswers the endpoint again, withoutsecretand withsecret_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_momentand 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_deniednow 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". Withoutreason, 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 answerswaiting_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 withcode: "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 failedwake_timeout, and could record a wake of the machine that never happened. -
Retrying a
DELETEwith the sameIdempotency-Keyanswers the first204again, withIdempotent-Replayed: true. It answered404once the schedule, session or AI team was gone. -
A message one Claude session receives from another (a teammate or helper session) is a
session.noticewithkind: "peer_message"and a shorttext, in the event stream and in/items. It was asession.message.completedwithrole: "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 atextlike3 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.noticewithkind: "peer_held", without the message itself. Itssession.input_required(kind: "peer_hold") has the fixed titleA 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_requiredhaskind: "resume_offer", the one choiceresume, andanswerable_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}/interruptanswers409 held_peer_messageand 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.noticewithkind: "background_job"and a one-linetextsuch asBackground job finished: Run the tests (exit code 0)(Helper finished: …for a helper). It sent nothing before. A notice withkind: "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_changedevent with its ownid, on the event stream and in webhooks. A prompt that retried sent the sameidagain for a repeatedtypingorqueued, so a client that drops duplicates byidmissed 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 was403 permission_denied). -
400 invalid_requestfor an unknownHQ-Versionnow carries the current version in its ownHQ-Versionheader. -
A
starting_afteronGET /v1/audit_eventsorGET /v1/billing/invoicesthat 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 namedLast-Event-IDbefore, even when only?after=was sent. Theerrors[].fieldand the code (invalid_cursor) are unchanged. -
An empty
Last-Event-IDheader 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 answers400 invalid_request(invalid_cursor, fieldafter). -
Unknown field names echoed in errors are now cut to 64 characters.
-
A schedule with neither or both of
target_sessionandcreate_new_session: true(onPOST /schedules, or aPATCH /schedules/{schedule_id}that leaves it so) now says "Specify exactly one of target_session or create_new_session: true." and lists both fields inerrors(codeexactly_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 andcodevalues are unchanged. -
409 workspace_pausedis now documented: creating withstart, starting or restarting a session on a paused AI team answers it. Starting and creating withstartare unchanged; a restart of a running session now leaves it running (it was stopped first, and then not started again). See Errors. -
409 workspace_updatingis now documented: creating withstart, 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. -
PATCH /schedules/{schedule_id}can switch a schedule's mode with one field:create_new_session: trueclears itstarget_session, andtarget_sessionturnscreate_new_sessionoff. Either switch was refused with422 validation_failedbefore.