​

API Changelog

NexSpace uses date-based API 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.

​

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

• 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 and 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. 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.
• 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.
• 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.
• 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. 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.

​

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.