Skip to main content

​
SDKs

The canonical NexSpace SDKs are generated by Stainless from the OpenAPI spec (server/openapi/openapi.yaml) and stainless.config.yml.
Neither package is published yet. npm install @nexspace/sdk and pip install nexspace will not resolve until the first Stainless release lands. The hand-written packages in this repo — packages/sdk-typescript/ ("private": true) and packages/sdk-python/ (classifier Private :: Do Not Upload) — are deprecated stopgaps, are not published, and export a different surface from the generated clients. Do not build against them. Track tools/stainless/README.md for release status.Until then, call the API over HTTP (see Quickstart), or use the CLI or the MCP server.

TypeScript

@nexspace/sdk — full TypeScript types, ESM, APIError hierarchy.

Python

nexspace — typed models, sync + AsyncNexSpace, PEP 561 typed.

​
SDK Features

What the generated clients actually do, per client_settings in stainless.config.yml: NexSpace-Version is a spec-level parameter (components.parameters.NexSpaceVersionHeader), deliberately not a client option: a client-level default would pin every caller in the process to one date. Omit it and you get the latest version — currently 2026-07-24. See Versioning and Idempotency.

​
Not in the SDKs

Three surfaces are deliberately absent, because generating them would ship code that always fails:
  • api_keys — /api/api-keys* answers 403 FORBIDDEN to any API-key-authenticated request before the handler runs (“API keys cannot be managed with an API key — sign in to the dashboard”), and these SDKs authenticate with API keys only. Mint and rotate keys in the dashboard.
  • mcp — MCP is JSON-RPC spoken by MCP clients, and the SDK is pinned to https://api.nexspace365.com, where every /mcp path answers 403 MCP_HOST_NOT_ALLOWED. Use https://mcp.nexspace365.com.
  • triggers — the /api/agent-builder/{id}/triggers* routes require the agents.manage permission, which no scope in the documented headless catalog satisfies. Manage automations in the dashboard; see Automations. (Not a hard boundary — see the reachability caveat in Authentication.)

​
Generation

Stainless builds from the merged spec rendered by scripts/generate-openapi.ts in the Build Stainless SDKs CI workflow, not from the static server/openapi/openapi.yaml alone — the merge adds the Verb_<id>_Input / _Output schemas for the agent verbs and the x-mcp-tools root extension. The API Reference tab of these docs renders the live https://api.nexspace365.com/api/openapi.json, which is the same merged document served by the running server. So the MCP verb schemas appear in the API reference and, now, in the SDK spec too. When the spec or stainless.config.yml changes, that workflow regenerates both SDKs and opens a release PR to the language production repos. See tools/stainless/README.md for the pipeline and ADR 0001 for the decision record.