Endpoints

Compressed catalog of every 2026-05-01 endpoint by router, with scope and a one-line purpose. Not a substitute for the OpenAPI spec — a scannable index. Base URL: https://api.moda.app/v1

Tasks

Verb	Path	Operation	Scope	Purpose
POST	`/tasks`	`startTask`	`tasks:write`	Start an AI design task. Returns Task envelope immediately; poll or webhook.
GET	`/tasks/{id}`	`getTask`	`tasks:read`	Fetch current task envelope.
GET	`/tasks`	`listTasks`	`tasks:read`	Cursor-paginated list of team’s tasks.
POST	`/tasks/{id}/cancel`	`cancelTask`	`tasks:cancel`	Request cancellation. Returns 202 + updated envelope.

Remix

Verb	Path	Operation	Scope	Purpose
POST	`/remix`	`remixCanvas`	`canvases:write`	Duplicate canvas and optionally run a design task on the copy. Always returns a Task envelope (`kind: "remix"`).

Without a prompt: completes synchronously, returns status: "succeeded" inline. With a prompt: queues a task, returns non-terminal envelope; poll.

Canvases

Verb	Path	Operation	Scope	Purpose
GET	`/canvases`	`listCanvases`	`canvases:read`	Cursor-paginated list of team canvases.
GET	`/canvases/search`	`searchCanvases`	`canvases:read`	Relevance-ranked search by name/content (`q` query param). Offset-paginated — the one non-cursor list in this catalog.
GET	`/canvases/{id}`	`getCanvas`	`designs:read`	Fetch canvas spec (pseudo-HTML + CSS). `share_token` query param for public reads.
GET	`/canvases/{id}/tokens`	`getCanvasTokens`	`designs:read`	Extract design variables / colors / fonts / radii only.
GET	`/canvases/{id}/pages`	`listCanvasPages`	`designs:read`	List page metadata (id, name, dimensions, node_count).
POST	`/canvases/{id}/export`	`exportCanvas`	`designs:export`	Export to PNG / JPEG / PDF / PPTX / MP4 / GIF. Returns `{status: "completed", url, format}` when it finishes inside the ~20s wait budget, else `{status: "in_progress", task_id}`. `409 + Retry-After: 10` when an active design task runs on this canvas.
GET	`/canvases/{id}/export-status`	`getExportStatus`	`designs:read`	Poll an in-progress export by `task_id` until `is_terminal`.
POST	`/canvases/{id}/share`	`makeCanvasPublic`	`canvases:write`	Create / retrieve a public share link. Blocks on thumbnail generation by default; pass `wait_for_thumbnail=false` to skip.
PATCH	`/canvases/{id}`	`updateCanvas`	`canvases:write`	Update a canvas’s name, description, or template_type.

See canvases-and-exports.md for the export semantics and the share-token read pattern.

Brand kits

Verb	Path	Operation	Scope	Purpose
GET	`/brand-kits`	`listBrandKits`	`brand_kits:read`	Cursor-paginated list. Team is implicit from the API key context.
POST	`/brand-kits`	`createBrandKit`	`brand_kits:write`	Extract brand data from a URL (Firecrawl-backed). Returns the kit record.
PATCH	`/brand-kits/{id}`	`updateBrandKit`	`brand_kits:write`	Partial update. Array fields (`colors`, `fonts`) replace wholesale.
DELETE	`/brand-kits/{id}`	`deleteBrandKit`	`brand_kits:write`	Soft delete. Returns 204.
POST	`/brand-kits/{id}/images`	`addBrandKitImage`	`brand_kits:write`	Attach an uploaded file (logo / reference / asset). Requires `file_id` from `POST /uploads`.
GET	`/brand-kits/{id}/images`	`listBrandKitImages`	`brand_kits:read`	List images attached to a brand kit.
DELETE	`/brand-kits/{id}/images/{image_id}`	`removeBrandKitImage`	`brand_kits:write`	Remove an attached image. Returns 204.

See brand-kits.md for update semantics.

Uploads

Verb	Path	Operation	Scope	Purpose
POST	`/uploads`	`uploadFile`	`uploads:write`	Multipart upload, files up to ~32 MiB (gateway body cap). Returns `{id: "file_...", url, filename, mime_type, size_bytes, was_duplicate}`.
POST	`/uploads/url`	`createUploadUrl`	`uploads:write`	Mint a short-lived signed PUT URL for direct-to-storage upload. Step 1 of the large-file flow.
POST	`/uploads/register`	`registerUpload`	`uploads:write`	Finalize a signed-URL upload into a file row. Returns the same shape as `uploadFile`. Step 3.
POST	`/uploads/from-url`	`uploadFromUrl`	`uploads:write`	Server fetches from a public URL, validates MIME, stores. SSRF-validated.

Deduplicates by content hash. Files are capped at max_file_bytes on every path — that ceiling is per-workspace (250 MB is the deployment maximum, a free workspace is lower), so read it from GET /v1/uploads/limits rather than hard-coding a number; the multipart path is additionally capped at ~32 MiB by the gateway, so larger files must use /uploads/url + /uploads/register. See uploads.md.

Organizations

Verb	Path	Operation	Scope	Purpose
GET	`/organizations`	`listOrganizations`	`organizations:read`	Cursor-paginated list of orgs + teams the key’s owner belongs to.

Role scoped: admins see all, members see their own.

Credits

Verb	Path	Operation	Scope	Purpose
GET	`/credits`	`getCredits`	`credits:read`	Current balance, plan, reset date. `null` fields when billing is disabled.

Verb	Path	Operation	Scope	Purpose
POST	`/share_links/resolve`	`resolveShareLink`	(none — public-ish)	Parse a `moda.app/s/…` URL into `{canvas_id, share_token, permission, expires_at}`. Distinguishes `share_link_revoked` from `share_link_not_found`.

Usage / events (observability)

Verb	Path	Operation	Scope	Purpose
GET	`/usage`	`getApiUsage`	(admin)	Summary + daily / per-key / per-operation aggregates. 7-day default, 90-day max window.
GET	`/events`	`listApiEvents`	(admin)	Cursor-paginated activity log. Rows include HTTP status, `operation_id`, `timestamp`, `trigger_source` (api / mcp).

Admins see everything; members see only their own keys’ events.

Webhook deliveries

Verb	Path	Operation	Scope	Purpose
GET	`/webhook_deliveries`	`listWebhookDeliveries`	(any authenticated key)	Cursor-paginated delivery log for the team; role-scoped (admins see all, members see their own keys’ deliveries). `from` / `to` window defaults to the last 7 days, 90-day max — pass them explicitly to look further back.
POST	`/webhook_deliveries/{id}/redeliver`	`redeliverWebhook`	(any authenticated key)	Queue a manual replay of a delivery. Returns 202. `403` unless you created the dispatching key or are a team admin — if that key has since been deleted, only admins can replay; `409` if the source task no longer exists.

Cross-cutting request headers

Header	Required	Notes
`Authorization: Bearer moda_live_…`	Yes (except `/share_links/resolve`)	See `authentication.md`
`Moda-Version: 2026-05-01`	Should	Pin in production. Omitting resolves to default.
`Content-Type: application/json`	POST / PATCH
`Prefer: wait=<seconds>`	No — not implemented; ignored	Use webhooks or polling instead.
`Idempotency-Key` (header)	No — not yet implemented	Body field `idempotency_key` instead.

Cross-cutting response headers

Header	Always present
`Moda-Version`	Yes — the resolved version
`X-Request-ID`	Yes — matches the `request_id` in error envelopes
`Retry-After`	On `429 rate_limited` and `409 canvas_active_job`

Common wrong guesses

Using the operation ID (startTask) as the path. Operation IDs are for SDKs; the HTTP path is what matters.
Expecting /tasks/{id}/cancel to be a DELETE. It’s a POST.
Confusing POST /canvases/{id}/share with generating a share link on every call. It creates one if missing, returns the existing one otherwise. It also blocks on thumbnail generation by default.
Calling GET /canvases/{id} without share_token= on a share-only-visible canvas. You’ll get 404 — the call resolves through the key’s team access, not the share link.
Reading url off an export response without checking status. A slow export returns {status: "in_progress", task_id} with url: null — poll /canvases/{id}/export-status. It is still not a Task envelope, so don’t poll /tasks/{id}.
Treating 409 + Retry-After: 10 on export as a failure. It’s the retry signal when a design task is running on the canvas.

Upstream

Full OpenAPI spec: docs.moda.app/openapi/moda-public-api.yaml
Per-endpoint docs: docs.moda.app/api/*

Welcome

Getting started

Brand kit

The AI agent

The canvas

Animation

Workspace

Export & sharing

Websites

Credits & billing

Integrations

Trust & security

FAQ

Endpoints

Endpoints

Tasks

Remix

Canvases

Brand kits

Uploads

Organizations

Credits

Usage / events (observability)

Webhook deliveries

Cross-cutting request headers

Cross-cutting response headers

Common wrong guesses

Upstream

​Endpoints

​Tasks

​Remix

​Canvases

​Brand kits

​Uploads

​Organizations

​Credits

​Share links

​Usage / events (observability)

​Webhook deliveries

​Cross-cutting request headers

​Cross-cutting response headers

​Common wrong guesses

​Upstream

Endpoints

Tasks

Remix

Canvases

Brand kits

Uploads

Organizations

Credits

Share links

Usage / events (observability)

Webhook deliveries

Cross-cutting request headers

Cross-cutting response headers

Common wrong guesses

Upstream