AI & Agent APIs
Three authenticated endpoint families let software — your own or a third-party AI client — read and change a workspace through the same validated domain tools the in-app assistant uses. They are documented in full on the MCP / agent page; this section is the map and the rules that differ from the rest of this API.
X-API-Key is not accepted on any of these routes
Every endpoint below requires a Supabase session (Authorization: Bearer) or, for the MCP transport, a scoped MCP connection token minted in Dashboard → Integrations → AI Connections. An SDK API token will not authenticate here — deliberately: it is owner-scoped across every project and carries no per-tool scopes.
Tool Layer
One registry of schema-validated domain tools — reads (projects, option blocks, pricing, materials, model parts, documentation) and controlled writes.
A write never applies silently. Low-risk tools commit immediately; high-risk tools (pricing, SKUs, deletions, bulk edits, shared materials, commerce links) return write.status: "proposed" with a pendingChangeId and the full before → after plan, and only a human confirmation applies them. Proposals expire after 15 minutes; applying one re-checks role, arguments and staleness (409 if the project moved). Every applied change is snapshotted, re-validated, audit-logged, and undoable through the revisions endpoints. Mutations are rate-limited to 30 per 10 minutes per workspace (429).
Agent workflows
Bounded, resumable, deterministic multi-step goals (audit a configurator, apply safe repairs, build material options, price from a catalogue file, build a configurator from a brief) that orchestrate the Tool Layer. They persist after every step, so a workflow survives a closed tab and is resumed rather than restarted.
A run reports a normalized state (queued, planning, running, waiting_for_input, waiting_for_approval, paused, completed, completed_with_warnings, failed, cancelled). Questions and approvals are answered only by the human who started the run — the model has no answer surface. Two write workflows never run concurrently on one project. Catalogue ingestion accepts CSV, XLSX and JSON up to 4 MB and stages the file for review; nothing is written because a file parsed.
MCP connections
Scoped credentials for external AI clients, plus the Model Context Protocol transport itself. Connection management is session-authenticated; the transport authenticates with the connection token (or OAuth 2.1 + PKCE).
A connection token is a credential-grade bearer secret for its full 90-day life — mint least-scope connections, and rotate immediately after any exposure. A connection is bound to ONE workspace at creation: a project owned by another account resolves as not_found by design, and there is no workspace header that changes that.
Full tool catalogue, scopes, error taxonomy, client configuration and the surface changelog: /docs/mcp.
Not in the SDK
The TypeScript SDK deliberately does not wrap these families. They are agent surfaces with their own confirmation, approval and scope model; a thin client wrapper would invite treating a high-risk proposal as an ordinary write. Call them over HTTP, or connect an MCP client.