# 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.
