REST API

List owned active OAuth authorization identities for explicit connector grants; no tokens

Request

No body; see live OpenAPI for query parameters.

Response

See live OpenAPI and the operation status returned by the server.

Begin separate GitHub App authorization for a verified installation

Request

{"connectionId":"","expectedRevision":1,"installationId":""}

Response

See live OpenAPI and the operation status returned by the server.

Complete one-use GitHub authorization bound to the initiating session

Request

No body; see live OpenAPI for query parameters.

Response

See live OpenAPI and the operation status returned by the server.

List repositories accessible to the user and selected GitHub installation; connectionId and page query parameters

Request

No body; see live OpenAPI for query parameters.

Response

See live OpenAPI and the operation status returned by the server.

Resolve a selected repository branch or tag to an immutable commit

Request

{"connectionId":"","repositoryId":"","ref":"main"}

Response

See live OpenAPI and the operation status returned by the server.

Receive signature-verified GitHub installation and authorization revocations

Request

{}

Response

See live OpenAPI and the operation status returned by the server.

Copy a granted image snapshot into isolated project assets without changing the document

Request

{}

Response

See live OpenAPI and the operation status returned by the server.

Reconcile an uncertain Drive upload or GitHub PR using recorded identities; never repeats external writes

Request

{"expectedRevision":1}

Response

See live OpenAPI and the operation status returned by the server.

Download an authorized prepared PDF, PPTX or React ZIP for inspection before upload

Request

No body; see live OpenAPI for query parameters.

Response

See live OpenAPI and the operation status returned by the server.

Begin separate session-bound Google Drive authorization

Request

{"connectionId":"","expectedRevision":1}

Response

See live OpenAPI and the operation status returned by the server.

Redeem a one-use Google callback for the initiating session

Request

No body; see live OpenAPI for query parameters.

Response

See live OpenAPI and the operation status returned by the server.

Obtain a transient selected-account access token for Google Picker; never returns refresh credentials

Request

{"connectionId":""}

Response

See live OpenAPI and the operation status returned by the server.

Supply explicitly reviewed input to a paused MCP operation; creates a separately approved continuation

Request

{"expectedRevision":1,"inputResponses":{}}

Response

See live OpenAPI and the operation status returned by the server.

List saved run metadata without advancing

Request

No body; see live OpenAPI for query parameters.

Response

See live OpenAPI and the operation status returned by the server.

Persist a bounded run at exact document and brief versions

Request

{"provider":"openai","prompt":"Refine design","bindingIds":[],"sourceSnapshotIds":[],"expectedDocumentRevision":1,"expectedBriefRevision":1,"idempotencyKey":"unique-request-key"}

Response

See live OpenAPI and the operation status returned by the server.

Read run status, authorized proposal and provider usage

Request

No body; see live OpenAPI for query parameters.

Response

See live OpenAPI and the operation status returned by the server.

Advance exactly one run step with current grants

Request

{"expectedRevision":1}

Response

See live OpenAPI and the operation status returned by the server.

Cancel future steps and preserve uncertain in-flight outcomes

Request

{"expectedRevision":1}

Response

See live OpenAPI and the operation status returned by the server.

Revalidate a completed unsaved proposal against current authority and versions

Request

No body; see live OpenAPI for query parameters.

Response

See live OpenAPI and the operation status returned by the server.

List private source metadata; agent results are limited to current source grants

Request

No body; see live OpenAPI for query parameters.

Response

See live OpenAPI and the operation status returned by the server.

Download an authorized immutable source as inert data

Request

No body; see live OpenAPI for query parameters.

Response

See live OpenAPI and the operation status returned by the server.

Import a new source snapshot without replacing existing content or brief

Request

{}

Response

See live OpenAPI and the operation status returned by the server.

Remove an owned source snapshot and invalidate dependent work

Request

No body; see live OpenAPI for query parameters.

Response

See live OpenAPI and the operation status returned by the server.

Import one selected MCP resource or Drive file as an immutable source snapshot

Request

{"uri":"resource://selected"}

Response

See live OpenAPI and the operation status returned by the server.

List the latest 50 operation records without private payloads

Request

No body; see live OpenAPI for query parameters.

Response

See live OpenAPI and the operation status returned by the server.

Prepare a selected tool operation against exact observed versions; unknown effects require human approval

Request

{"bindingId":"","action":"","arguments":{},"idempotencyKey":"unique-request-key","expectedVersions":{"connectionRevision":1,"credentialVersion":1,"policyRevision":1,"documentRevision":1,"briefRevision":0,"sourceSnapshotIds":[]}}

Response

See live OpenAPI and the operation status returned by the server.

Inspect an operation and authorized private payload without advancing it

Request

No body; see live OpenAPI for query parameters.

Response

See live OpenAPI and the operation status returned by the server.

Claim approved operation once; uncertain results are never replayed

Request

{"expectedRevision":1}

Response

See live OpenAPI and the operation status returned by the server.

Approve once or deny the exact operation in an authenticated browser session

Request

{"expectedRevision":1,"decision":"approve"}

Response

See live OpenAPI and the operation status returned by the server.

Cancel own pending operation with revision protection

Request

{"expectedRevision":1}

Response

See live OpenAPI and the operation status returned by the server.

List project connections

Request

Project ID.

Response

{ connections }; agent selections are restricted by their grants.

Requires CONNECTORS_ENABLED. Human sessions can inspect disconnected bindings for recovery; agents receive only authorized connected bindings.

Bind a project connection

Request

connectionId, role and explicit selection; see OpenAPI.

Response

201 { binding } with policyRevision.

Creates no agent authority. Grant access separately.

Remove a project connection

Request

{ expectedPolicyRevision }

Response

{ ok }; related grants revoked, snapshots removed and dependent work invalidated.

Grant project connector access

Request

recipient, expectedPolicyRevision, capabilities, selection and expiresAt; see OpenAPI.

Response

201 { grant }.

Selection must be within the binding and expiry within 90 days. API-key, OAuth and WebMCP access are separate.

Revoke connector access

Request

Project, binding and grant IDs.

Response

{ ok }; subsequent authorization fails.

List external connection metadata

Request

Optional projectId query; required for API, OAuth and WebMCP callers.

Response

{ connections }; no credentials.

Operator must enable CONNECTORS_ENABLED. Connector workflows are experimental and require configured external accounts. Tool-assisted runs use explicit approvals and return unsaved proposals.

Read connection metadata

Request

Connection ID; projectId query for agents.

Response

{ connection } with status and revision.

Create pending connection

Request

displayName and config; see OpenAPI schema.

Response

201 { connection }; pending until verified.

Never put credentials in endpoint URLs. Native connector authorization is not enabled by creating metadata.

Disconnect and revoke connector authority

Request

{ expectedRevision }

Response

{ connection }; credentials removed, grants revoked, active work invalidated.

Verify anonymous or bearer MCP

Request

connectionId, expectedRevision, optional accessToken in request body.

Response

Verified connection metadata and negotiated protocol; no credential.

Successful connection does not establish catalog or tool access. API, OAuth and WebMCP callers cannot manage setup.

Start outgoing MCP OAuth

Request

connectionId, expectedRevision, options; modern CIMD or registered client, explicit legacy DCR.

Response

Authorization URL and new revision.

New authorization revokes previous grants. Callback is fixed to this installation.

Read OAuth client metadata

Request

No body.

Response

Canonical client ID and exact redirect URI; no secret.

Complete outgoing MCP OAuth

Request

Authorization server callback state, code, iss or error.

Response

Verified connection metadata.

One-use state; owner, session, issuer, resource and revision checked. Callback cannot grant local agent authority.

Summarize account activity and measured usage

Request

Query: scope=owner|all; days=1..30 (default7); projectId, actorId (all only), channel, kind, status, action.

Response

{ scope, days, totals, usage, byAction, byActor, byProvider, coverage }

Unknown measurements remain null. OAuth cannot read all-account scope.

Read paginated activity logs

Request

Summary filters plus limit=1..100 (default50), cursor from previous page.

Response

{ events, nextCursor }; safe metadata only, 30-day retention.

Follow correlated request steps

Request

Trace ID from X-Request-ID or event. Query: scope, days (default7; maximum30).

Response

{ traceId, events, truncated }; 404 for unavailable traces.

Record an allowlisted browser event

Request

{ event, page?, action?, projectId?, requestId?, outcome?, errorCode? }; strict enums in OpenAPI schema.

Response

Accepted telemetry; optional PostHog forwarding is isolated from product operations.

Never send arbitrary text, credentials, names, URLs or exception messages. Not exposed as an agent mutation tool.

Check service health

Request

No body.

Response

{ "ok": true, "service": "design-studio-ai" }

Read live JSON Schemas

Request

No body.

Response

{ document: JSONSchema, operations: JSONSchema, designSystem: JSONSchema, interview: JSONSchema, scope: JSONSchema }; semantic validation still runs on writes.

Discover API operations and request schemas

Request

No body.

Response

OpenAPI document with path/query parameters, multipart uploads, and shared component schemas.

List your design systems

Request

No body.

Response

{ systems: DesignSystem[] }; latest saved versions for this owner.

Create a reusable design system

Request

Definition object matching /api/schema → designSystem.

Response

201 { system }; initial version is 1.

Includes theme tokens, component variants and reusable page compositions. Private media references cannot be captured; embed media or use public HTTPS URLs.

Read a library version

Request

Optional positive integer query: version. Omit for latest.

Response

{ system: { id, version, definition, createdAt } }

List immutable library versions

Request

No body.

Response

{ versions: [{ version, createdAt }] }; newest first.

Append a library version

Request

{ expectedVersion, definition }; read the definition and its version first.

Response

{ system }; stale expectedVersion returns 409.

Previous definitions stay immutable. Never substitute a newer version number to force stale content through a conflict.

Apply a saved design system

Request

{ projectId, expectedRevision, version? }

Response

{ project }; project revision increments.

Own both library and project. Optional version selects a saved library version. Applies tokens/system while preserving authored component overrides; pins the library version in the project.

Insert a library item

Request

{ projectId, expectedRevision, pageId, itemId, version? }

Response

{ project }; inserts the saved component/composition with fresh node IDs and remapped hierarchy/interactions.

Delete a design-system library

Request

No body.

Response

{ "ok": true }

Deletes this owned library and its versions. Previously applied project content remains embedded.

Discover Google Fonts

Request

Optional q query, maximum 200 characters; matches family/category without case sensitivity.

Response

{ fonts, source, message, fetchedAt? }; source is live, cache, or fallback.

The full catalog uses an operator Google Fonts API key. Without it, returns clearly labeled curated starter families. Choosing a Google font loads its face separately.

Discover provider model IDs

Request

Provider: openai|anthropic|gemini|openrouter|fal|deepseek|leonardo|grok|custom-<slug>. Optional q query, maximum 200 characters; matches ID/name/category.

Response

{ models, source, message, fetchedAt?, truncated? }

Uses the saved provider connection. Custom endpoints and unavailable connections return labeled starter suggestions; manual model IDs remain available. OAuth MCP credentials cannot call this endpoint. No raw provider key is returned.

Read built-in design resources

Request

No body.

Response

{ themes, templates, blocks }

Read public configuration

Request

No body.

Response

Public feature configuration, including googleClientId, allowRegistration, githubEnabled, observability eligibility/retention, and analytics availability. Never includes provider keys or server secrets.

Create an account

Request

{ "email": "you@example.com", "password": "<12–128 characters>", "name": "Your name" }

Response

201 { user: { id, email, name } } + HttpOnly session cookie.

Registration must be enabled by the operator. Email is normalized; name is optional. Rate limited.

Start an email/password session

Request

{ "email": "you@example.com", "password": "<your password>" }

Response

{ user: { id, email, name } } + HttpOnly session cookie.

Read the current account

Request

No body.

Response

{ user: { id, email, name } | null }

Start GitHub sign-in

Request

Navigate using the sign-in button. No request body.

Response

Redirects to GitHub authorization with browser-bound state and S256 PKCE; configuration errors redirect to /?auth_error=….

Complete GitHub sign-in

Request

GitHub supplies code and state, or an authorization error.

Response

Issues the studio session and redirects home on success. Errors redirect to /?auth_error=….

This is an OAuth callback, not an endpoint to call manually. Existing email/password accounts are not automatically linked by email.

Read your GitHub connection

Request

No body.

Response

{ enabled: boolean, connected: boolean, login: string | null }

Connect GitHub to your existing account

Request

No body.

Response

{ url }; navigate to the returned GitHub authorization URL.

The callback must complete in the same signed-in session. A GitHub identity already linked to another account is rejected.

End a browser session

Request

No body.

Response

{ "ok": true }; clears the session cookie.

Logging out of a browser does not revoke API keys.

Search and list projects

Request

Query: q (name/description), kind (web|slides|report|wireframe|3d|video), sort (updated|created|name).

Response

{ projects: ProjectSummary[] }; up to 500 owned projects. Summaries exclude document.

Create or clone a project

Request

{ "name": "Product story", "kind": "slides", "templateId": "product-deck" }

Response

201 { project: Project }; initial revision is 1.

Optional description, themeId, templateId, document. Supplying an owned document creates a new project and copies owned asset bytes; there is no separate REST clone route.

Read a project and revision

Request

Replace :id with an actual project ID.

Response

{ project: { id, name, description, kind, document, revision, createdAt, updatedAt, publishedUrl? } }

Update project metadata

Request

{ "name": "Updated name", "description": "Updated description" }

Response

{ project: Project }; increments revision.

Both fields are optional. This metadata route checks the revision read by the server; use document PUT or CLI rename for an explicit client expectedRevision.

Save the canonical document

Request

{ "document": "<complete DesignDocument object>", "expectedRevision": 1 }

Response

{ project: Project }; revision increments atomically. A stale expectedRevision returns 409.

document is an object, not a string: replace the illustrative placeholder. Preserve project ID/kind. Owned asset references must belong to this project. Targeted patch operations are available through CLI/MCP, which reuse this save contract.

Merge concurrent human and agent edits

Request

{ baseRevision, base, document }; base is the complete document originally read, document is your edited copy.

Response

{ project: Project }; saves the reconciled document. Overlapping edits return 409 with error.code merge_conflict and error.details.paths.

baseRevision is the positive project revision originally read, separate from the brief revision. Preserve the exact base and project ID/kind. Never alter the base or invent its revision to force a merge; resolve overlapping changes explicitly.

Observe the saved project revision

Request

Optional query: since, the last observed nonnegative project revision; default 0.

Response

{ revision, unchanged: true } when since equals the saved revision; otherwise { revision, project: Project }.

Returns the current saved project when changed, not a history or operation log. Does not include unsaved browser edits.

Delete a project

Request

No body.

Response

{ "ok": true }

Deletes the project, stored assets, and publications. This is destructive.

Inspect the saved design

Request

No body.

Response

{ projectId, revision, issues, counts: { warnings, information, total }, truncated, limitations }

Read-only deterministic preflight with node/page IDs and suggestions. Estimates bounds, text fit, opaque-hex contrast, missing/remote media, chart data, and duration limits. Does not certify accessibility or visual quality; inspect the actual preview.

Read the design brief and scope

Request

No body.

Response

{ brief: DesignBrief | null }

A brief has its own revision, separate from the document revision, plus request, status, message, questions, answers, scope, approvedAt, and updatedAt.

Save a brief, interview, answers, or scope

Request

{ "expectedRevision": 0, "request": "Create a six-slide introduction for our team." }

Response

{ brief: DesignBrief }; increments the brief revision. Stale revisions return 409.

Revision 0 creates a brief and requires request. Supply at least one of request, interview, answers, or scope. Read interview/scope JSON Schemas at /api/schema. Answers map question IDs to text or multiple-choice arrays. Every edit invalidates prior approval. External agents can supply their own interview and scope without server BYOK.

Generate contextual interview questions or scope

Request

{ "expectedRevision": 1, "provider": "openai" }

Response

{ brief: DesignBrief }; saves the validated provider response with revision protection.

Requires an existing brief and configured text-provider BYOK; charges may apply. Providers: openai, anthropic, gemini, openrouter, deepseek, custom-<slug>; model is optional. Returns up to eight contextual questions or a concrete scope. Invalid provider responses leave the saved brief unchanged.

Approve the current scope

Request

{ "expectedRevision": 2 }

Response

{ brief: DesignBrief }; status becomes approved and approvedAt is recorded.

Requires a scope and answers to all required questions. Obtain explicit human approval of the current scope before calling. Approval increments the brief revision; it does not generate a design, save the document, or publish.

List project assets

Request

No body.

Response

{ assets: [{ id, name, type, mimeType, url, size }] }

Upload private media

Request

multipart/form-data with a file field. Let your HTTP client set the multipart boundary.

Response

{ asset: { id, name, type, mimeType, url, size } }

Maximum 20 MB. PNG/JPEG/WebP/GIF, MP3/WAV/OGG, MP4/WebM, and GLB are supported with signature validation. Upload does not place a node on the canvas.

Download private asset bytes

Request

Replace :id with an actual asset ID.

Response

Binary response with the stored MIME type.

Read saved conversation

Request

No body.

Response

{ messages: [{ id, role, text, createdAt }] }; latest 200 messages in chronological order.

Append a conversation message

Request

{ "role": "user", "text": "Make the title more concise." }

Response

201 { message: { id, role, text, createdAt } }

role is user or assistant; text is 1–30,000 characters. This stores a message; it does not invoke a provider.

Generate a design proposal

Request

{ "provider": "openai", "prompt": "Make the opening slide more spacious.", "expectedRevision": 1 }

Response

{ document: DesignDocument, usage? }

Optional model. Providers: openai, anthropic, gemini, openrouter, deepseek, custom-<slug>. Requires configured BYOK, may incur charges, and does not save. Prompt maximum 12,000 characters. Inspect, then save with the original revision.

Generate or transform media

Request

{ "provider": "fal", "kind": "audio", "prompt": "Warm ambient instrumental music", "durationSeconds": 30 }

Response

OpenAI, Gemini, Grok, custom: { asset }. fal and Leonardo: 202 { job: { id, status: "queued" } }.

kind: image|audio|video. Optional model, voice, sourceAssetId, durationSeconds, strength. Sources must belong to this project. OpenAI image/edit/speech; Gemini, Grok and Leonardo prompt-only images; custom OpenAI/Gemini compatible prompt-only images; fal image/edit, video/edit, music/effects/audio transformation. Requires BYOK and can incur charges.

Poll a media job

Request

Use the project ID and returned job ID.

Response

{ status: "queued" | "processing" } or { status: "completed", asset }.

Supports all fal media kinds. A completed result is reused on later polls. Failures return actionable errors; queued is not completed.

Download a rendered file

Request

{ "format": "png", "pageIndex": 0, "expectedRevision": 1 }

Response

File bytes with Content-Type and Content-Disposition. No JSON success envelope.

Formats: json, html, svg, png, pdf, pptx, webm, mp4, react, glb, gltf. React returns a runnable frontend ZIP for Web/App or wireframe projects. GLB/glTF export the selected scene with geometry/materials/animation. pageIndex defaults to 0; expectedRevision is optional. PDF/PPTX include all pages. Import remote media before isolated cloud rendering. React source export does not require Chromium; GLB/glTF and raster/video formats use the configured browser renderer. Size and encoder limits apply.

Create Google Slides

Request

{ "accessToken": "<short-lived Google OAuth access token>" }

Response

{ url, presentationId }

Requires real Google authorization. Native text/shapes/HTTPS images are supported; unsupported complex nodes and private image URLs fail explicitly. Do not put the token in source files.

Publish an immutable snapshot

Request

No body.

Response

{ url, revision }

Makes this saved design and its referenced snapshot assets public. Later private edits do not change it.

Unpublish a project

Request

No body.

Response

{ "ok": true }; removes all public snapshots of this project.

Create a public preview link

Request

No body.

Response

{ url, revision }

Creates the same immutable public snapshot as publish, under the preview naming used by agents. Later private edits do not change it.

Remove preview links

Request

No body.

Response

{ "ok": true }; removes all public snapshots of this project.

Create a public share link

Request

No body.

Response

{ url, revision }

Creates the same immutable public snapshot as publish, under the share naming used by agents.

Remove share links

Request

No body.

Response

{ "ok": true }; removes all public snapshots of this project.

View a published snapshot

Request

Use the slug from a publish response.

Response

HTML snapshot, including the trusted 3D/timeline viewer where applicable.

Read a snapshot asset

Request

Use the snapshot asset URL. Private API asset URLs do not become public.

Response

Asset bytes only when this publication references the asset.

List masked provider settings

Request

No body.

Response

{ providers: [{ provider, name, baseUrl, model, protocol, authMethod, authHeader, configured, apiKey: "••••••••" }] }

API-key MCP clients can use list_provider_connections for these masked IDs. MCP OAuth tokens cannot access provider settings.

Save a BYOK connection

Request

{ "apiKey": "<provider secret from secure input>", "model": "<optional model ID>" }

Response

{ provider, name, baseUrl, model, protocol, authMethod, authHeader, configured: true, apiKey: "••••••••" }

Providers: openai, anthropic, gemini, openrouter, fal, deepseek, leonardo, grok or custom-<slug>. Custom connections require name, baseUrl and model; protocol is openai, anthropic or gemini. authMethod: bearer, api-key (authHeader), basic (username:password credential), none. HTTPS origins must be operator-allowlisted. Omit apiKey to retain it; endpoint/auth changes require a new credential. Secrets are encrypted. Prefer CLI --key-env or --key-stdin; ChatGPT subscriptions do not include OpenAI API access.

Remove a BYOK connection

Request

No body.

Response

{ "ok": true }

List API-key metadata

Request

No body.

Response

{ tokens: [{ id, name, createdAt, lastUsedAt }] }

Raw keys are never returned by list. MCP OAuth cannot manage permanent credentials.

Create an API key

Request

{ "name": "Local design agent" }

Response

201 { id, token }; raw token is returned once.

Treat this response as a secret. Use the signed-in key-management UI to create your first key.

Revoke an API key

Request

Use the key ID from the metadata list, not the secret value.

Response

{ "ok": true }; revoked keys no longer authenticate.