​

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 Tier 3

In-product agent automations. Cron schedule and event triggers (GET/POST/PATCH/DELETE /api/agent-builder/{id}/triggers, plus /toggle and /run-now) that fire agents through the durable run path. A timezone-aware cron dispatcher computes nextRunAt and auto-disables a trigger after a consecutive-failure streak; event triggers dispatch on matching business events. Both inherit the one-run-per-agent guard, the lifecycle webhooks, and the approval loop. Adds the runAsUserId privilege-escalation guard (binding another user is internal-operator only, otherwise 403 RUN_AS_FORBIDDEN) and per-mutation audit. See Agent Automations.

• Status: Stable
• Sunset: none

​

2026-07-22 — Headless AI Tiers 1–2

Tier 1 — the agent-run API. POST /api/agents/{id}/runs behind the agents:run scope, with resumable SSE streaming (Last-Event-ID), MCP request-id correlation, MCP idempotency, and outputSchema on registry tools. Tier 2 — the approval-resolution loop. List a paused run’s approvals, then approve/reject with the agents:approve scope to resume or terminate it; the rejected run status; run lifecycle webhooks (agent_run.pending_approval, agent_run.completed, agent_run.failed); MCP approval verbs; run list and cancel (GET/DELETE /api/agents/{id}/runs); and orphan/retention reconciliation. See Agent Runs.

• 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 successful API-key-authenticated response, so agents can throttle proactively. The 429 rejection carries the first four plus Retry-After, but not X-RateLimit-Policy. 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.

​

Headless capability waves

These expanded what a headless credential can reach over MCP. All are additive: no REST contract changed, and no existing NexSpace-Version pin is affected. Several introduce new scopes, though — a credential minted before those waves shipped will not reach the new tools until the scope is granted, and none of the new scopes are part of the default connector set.

• CRM writes (crm:write) — the crm tool category flipped from read-only to read_write over MCP after a tenancy audit of its write tools. The legacy crm:* wildcard also satisfies the new scope. See Scopes and the Tool catalog.
• Scheduling writes (scheduling:write) — the scheduling category flipped to read_write: the shift writers plus the schedule-settings writers. See Scopes and the Tool catalog.
• Communications writes (communications:write) — the communications category flipped to read_write: scoped individual outreach (send_sms, send_email_notification) and the org-verified campaign writers. Fan-out tools that never had a delivery engine stay denylisted. See Scopes and the Tool catalog.
• Connected-apps lane (apps:read / apps:write) — whitelabeled third-party actions (Slack, QuickBooks, HubSpot, …) brokered through the org’s connected accounts, on their own scope lane rather than a tool category. Deliberately not part of the default connector scopes: reaching into an owner’s outside SaaS has to be an explicit grant. See MCP → Connected-app actions. Ships with list_connected_apps, a read-only tool listing which apps the current user has connected.
• Deep-research tools (search / fetch) — two read-only knowledge-base tools using the names ChatGPT’s connector expects: search returns matching organization documents, fetch returns one document’s full text by the id search returned. Results are scoped to the caller’s organization and role. See ChatGPT.
• get_approval_status — a read-only tool that resolves the approvalId returned when a write answers pending_approval, reporting the lifecycle status (pending / approved / rejected / expired) and, once resolved, the execution result or rejection reason. Only your own submitted actions are visible. See MCP → Approvals.
• Org guardrails on MCP dispatch — organization AI guardrail policies (block / require_approval / warn) are now evaluated on the headless MCP path, not just inside the in-app agent loop. A blocking policy answers JSON-RPC -32003 with the policy name under error.data.guardrail; a require_approval policy forces the approval gate on a write that would otherwise auto-execute. See Governance.
• MCP rate limiter — MCP calls are now metered by their own limiter, separate from the /api per-key budget: 120 requests/minute by default, bucketed per API key, else per user, else per IP. See Rate limits → MCP rate limits.
• Model-tier equivalence gate — an operator can require a capable model for a specific tool. Since your model is invisible to the server, an external caller is graded by a credential-level tier equivalence; an ungraded credential fails closed against a floored tool with -32003 carrying requiredTier and tierEquivalence. No tool ships with a floor by default. See Model tier gate.

​

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.