Skip to main content

​
Upstream findings from the docs verification pass (2026-08-31)

Everything below was found while grounding docs.stateset.com in each server’s source and live behaviour, and is already worked around in the docs (spec overlays in spec/overlays/, generated pages, or corrected prose). Fixing it upstream lets the overlays shrink to zero and keeps the published contracts honest at the source. One section per repo — each item is paste-ready for an issue.

​
stateset-sync-server

  • src/openapi.rs references 67 component schemas it does not export (JobQueuedResponse, WebhookResponse, PaginatedResponse, Order, ScheduleInfo, …): 67 operations’ responses dangle, and 28 request bodies with them. The docs type them from the handler structs (spec/overlays/sync.json) — the fix is registering the types in components(schemas(...)).
  • docs/SHOPIFY_NETSUITE_GETTING_STARTED.md predates POST /sync/netsuite and says there is no built-in Shopify→NetSuite job; the code has one. The doc points at ACP instead.

​
next-temporal-rs

  • GET /v1/workflows/order-fulfillment/{id}/status returns Json<String> ("<status>:<phase>"), while docs/openapi.yaml declares WorkflowStatusResponse.
  • BRANDED_WORKFLOW_PREFIXES in events.rs omits order-fulfillment-, so a brand-scoped key gets 400 on the event stream for its own workflow; the docs tell readers to use a global key as a workaround.
  • ~137 operations are GenericObject in the exported spec, and 33 signal/cancel routes list a 200 they never return (they answer 202; api-key revoke answers 204).

​
stateset-phone-server (rust-phone-server)

  • utoipa declares bare arrays for four list endpoints (/callback-tasks, /operator-queues, /operator-queues/stats, /supervisor-actions) whose handlers wrap in {ok, tenant, count, …} envelopes.
  • The published spec covers 61 tenant paths but not the agent-management plane (/voice/agents, /voice/phone-numbers, /voice/web-calls, /voice/calls, /api-keys) that VOICE_ENGINE_API.md documents and the server serves.

​
stateset-sandbox

  • The live /openapi.json (43 ops) omits six routes the server serves behind auth (tunnels ×3, inference, files/list, files/download, create-from-template — all verified 401).
  • Registered paths vs express routers disagree in the checkout: OpenAPI registers /files/write and /files/read; the routers in the current source serve those operations at POST/GET /sandbox/:id/files. The live deploy answers both styles — the build and the checkout have drifted.
  • POST /api/v1/webhooks returns 200; its own spec declares 201.

​
stateset-nsr

  • POST /api/v1/model/export is an always-501 (model_handlers.rs); ExportModelResponse is dead code. The docs document the 501 honestly.
  • The spec’s /v1/decisions responses do not list the 503 fail-closed path that errors.rs implements and the product story depends on.
  • Several NSR spec parameters are declared in: path for what the handlers read as query.

​
stateset-computer-use-agent

  • The approval gate (ApprovalPolicy/ApprovalRequest, awaiting_approval) is fully specified in the API models and routes, but nothing in worker.py/agent/ constructs an ApprovalRequest — the pause may not be wired in the deployed worker.
  • api.computer.stateset.app answers 503 on every path (docs mark it “being provisioned”).

​
stateset-agents

  • spec/sdk-surface.json in the docs pins @stateset/cli 1.28.0; source is 1.28.1 (surface identical). The skill’s stateset heartbeat … example is accepted as natural language but no heartbeat tool exists in src/tools.
  • The API’s own spec servers list names api.stateset.io / staging-api.stateset.io, neither of which serves this API.

​
stateset-edi

  • stateset-edi/overview.mdx (docs, fixed) showed a JSON response for outbound 810; the handler returns wire-ready X12 (application/edi-x12). Upstream: the utoipa annotation for GET /v1/usage claims bare UsageSummary; the handler wraps it in {success, data, period}.

​
response-chat-widget

  • package.json says response-chat-widget / the admin docs imply @stateset/… naming; the package is unpublished either way. The widget’s docs/ADMIN-API.md route table is accurate (verified against src/server/admin).

​
Packages referenced by docs but not on npm (~16)

@stateset/icommerce-skills (repo name icommerce-skills — align before publishing), @stateset/cctp-sdk, stateset-cctp, @stateset/client, @stateset/agent-sdk, @stateset/acp, @stateset/types, ss-onboard-agent, and friends. Every referencing page carries a “not yet published” note; this list is the publish checklist.

​
Platform

  • status.stateset.com is a 404 (docs now link the probed host-status page instead).
  • prod-api.stateset.cloud.stateset.app (another session pointed api-reference/v1/* at it) answers 503 — when it goes live, the docs adopt it (see memory: prod-api-host-candidate).
  • kb.stateset.com serves 401 on every path including /openapi.json — a real service with no public contract; decide whether it is integrator-facing.
Last modified on August 31, 2026