> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nexspace365.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Changelog

> Version history, additive changes, and deprecations for the NexSpace API

# API Changelog

NexSpace uses [date-based API versioning](/concepts/versioning). Breaking
changes ship only under a new version date; additive, non-breaking changes
(new fields, new endpoints) roll out to all active versions and are listed
here under **Additive changes**.

<Info>
  The machine-readable source of truth for supported versions is
  `GET https://api.nexspace365.com/.well-known/api-versions`. Pin your
  integration with the `NexSpace-Version` header.
</Info>

## Versions

### `2026-07-24` — Headless AI follow-on

Extends the headless stack after Tiers 1–3:

* **Broadened event triggers.** `event` automations now fire on `staff.onboarded`,
  `lead.qualified`, and `credential.expired` in addition to the shift events. See
  [Agent Automations](/concepts/automations).

* **Run-outcome auto-disable.** A trigger's `consecutiveFailures` streak now
  counts runs that **error mid-flight** (not just dispatch failures); a completed
  run resets it. The auto-disable quarantine therefore reacts to agents that
  repeatedly error, not only ones that fail to enqueue.

* **MCP Streamable-HTTP.** Send `Accept: text/event-stream` on a `tools/call` to
  receive the response as SSE. Supply `params._meta.progressToken` to also get
  `notifications/progress` frames. Streams are resumable: reconnect to
  `GET /mcp/stream/{streamId}` (from the `Mcp-Stream-Id` response header) with a
  `Last-Event-ID` header to replay missed frames.

* **CLI `agents run`.** Start and stream a headless run from the terminal, with
  `--output-format stream-json` for line-delimited JSON (NDJSON) events.

* **Status:** Latest · stable

* **Sunset:** none

### `2026-07-23` — Headless AI Tiers 1–3

The full headless agent stack: the agent-run API (`agents:run`) with resumable
SSE, MCP request-id correlation + idempotency, and registry tool `outputSchema`
(Tier 1); the approval-resolution loop with `agents:approve`, the `rejected`
run status, run lifecycle webhooks, and run list/cancel (Tier 2); and
**in-product agent automations** — cron `schedule` and `event` triggers
(`/api/agent-builder/{id}/triggers`) that fire agents through the durable run
path with a privilege-escalation guard and per-mutation audit (Tier 3). See
[Agent Automations](/concepts/automations).

* **Status:** Stable
* **Sunset:** none

### `2026-05-10` — Initial public API

The headless ecosystem launch: API keys, OAuth 2.1 (PKCE + Dynamic Client
Registration), the hosted MCP server, curated agent verbs, idempotency,
sandbox test keys, and usage analytics.

* **Status:** stable
* **Sunset:** none

## Additive changes

Non-breaking improvements applied to all active versions. These do not require
a version bump — your existing `NexSpace-Version` pin keeps working.

* **`@nexspace/cli@0.2.0` agent surface** — discovery loop (`search` →
  `mcp schema` → `--dry-run`), first-class MCP verb commands, `skill install`,
  `context use`, webhooks + `events listen` (HMAC), approvals / audit /
  `logs tail`, fixtures, and `conformance run`. See [CLI Overview](/cli/overview)
  and [Commands](/cli/commands). The CLI ships on its own semver, independent of
  the dated API versions above — nothing here changes the REST contract. Note
  that 0.2.0 does change the CLI's **default output format** for scripts:
  see [Output format](/cli/overview#output-format).

  0.2.0 also fixes the documented exit codes, which never actually worked: the
  bin entrypoint collapsed every failure to `1`, so `2` (auth) and `3` (bad
  input) were unreachable. Agents branching on exit status will now see the
  distinct codes instead of a uniform `1`.
* **Rate-limit headers on every API-key response** — `X-RateLimit-Limit`,
  `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-RateLimit-Window`, and
  `X-RateLimit-Policy` now accompany every API-key-authenticated response (and
  the `429`), so agents can throttle proactively. See [Rate Limits](/concepts/rate-limits).
* **Structured error contract for agents** — error responses now carry
  `suggestion` and `retryable` fields (and, over MCP, a `Suggestion:` line in
  tool-error text) so LLM agents can self-correct. See [Error Handling](/concepts/errors).
* **Webhook retries & auto-disable** — failed deliveries now retry on a fixed
  exponential backoff (30s, 2m, 15m, 1h, 6h). After the initial send plus 5
  retries all fail, the subscription is automatically disabled and its creator is
  notified; re-enable it with `PATCH /api/webhooks/{id}`. See
  [Webhooks → Retry Policy](/concepts/webhooks#retry-policy).
* **On-demand sandbox reset** — `POST /api/sandbox/reset` clears a facility's
  `nex_test_` sandbox rows and re-seeds a small synthetic dataset for a clean
  slate. See [Sandbox](/concepts/sandbox). Prefer
  `nexspace fixtures sandbox-reset --facility-id N` when using the CLI
  (session auth only).
* **Credential-agnostic identity probe** — `GET /api/auth/me` returns the
  identity a credential authenticates as, accepting any supported credential
  (API key, PAT, OAuth access token, or session). It's the shared "who am I"
  endpoint for the CLI (`nexspace whoami`), SDKs, and MCP clients. See
  [Authentication → Verify identity](/authentication#verify-identity).

## Deprecation policy

* **12-month window** — a deprecated version keeps working for at least 12
  months. During that window responses include RFC 8594 `Deprecation` and
  `Sunset` headers.
* **After sunset** — requests pinned to a removed version return `410 Gone`
  with code `VERSION_SUNSET`. Upgrade to the latest version to resolve.
* Migration notes for each new version are published on this page before the
  previous version's sunset date.