Task envelope

Every task-shaped operation — design, remix, brand-kit extraction — returns the canonical Task envelope. (Canvas export is not one of them; it has its own two-shape payload — see below.) Pin Moda-Version: 2026-05-01 to get this shape.

Full shape

{
  "id": "task_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "kind": "design",
  "status": "queued",
  "created_at": "2026-04-15T12:00:00+00:00",
  "started_at": null,
  "completed_at": null,
  "progress": null,
  "attempt": 1,
  "max_attempts": 3,
  "attempts_started": 0,
  "first_started_at": null,
  "input": { "prompt": "Create a sales deck", "format": { "category": "slides", ... } },
  "result": null,
  "error": null,
  "credits": null,
  "links": {
    "self": "/v1/tasks/task_01HT9...",
    "events": null,
    "cancel": "/v1/tasks/task_01HT9.../cancel",
    "canvas": null
  },
  "retry_after_ms": 3000
}

Fields

Field	Type	Notes
`id`	string	`task_`-prefixed ID
`kind`	string	`design` / `export` / `remix` / `brand_kit_extract` — discriminator for `input` / `result` shape
`status`	string	`queued` / `running` / `succeeded` / `failed` / `canceled` / `expired`
`created_at`	ISO 8601	When the task was created
`started_at`	ISO 8601 / null	When the worker picked up the current attempt. Rewritten on every retry — see `first_started_at`
`first_started_at`	ISO 8601 / null	When the worker picked up the first attempt. `null` means unknown (task predates this field, or was never claimed)
`completed_at`	ISO 8601 / null	Terminal timestamp
`progress`	object / null	`{percent, step, message}` — populated during `running`
`attempt`	integer	Current attempt number, floored at 1. Cannot distinguish a never-claimed task from one retrying after a dead attempt — use `attempts_started` for that
`attempts_started`	integer	Attempts begun (not completed). `0` for a task no worker has claimed yet; `1` while the first attempt runs and through its retry backoff
`max_attempts`	integer	Usually 3 — auto-retry cap for transient failures
`input`	object	Varies by `kind` (design: `{prompt, format, ...}`; export: `{canvas_id, format, ...}`)
`result`	object / null	Populated on `succeeded`; varies by `kind` (design: `{canvas_id, canvas_url, conversation_id, export}`)
`error`	object / null	`{message, retryable, attempt}` — populated on `failed`, and on a non-terminal task carrying a previous attempt’s failure
`credits`	object / null	`{credits_used, credits_remaining}` on `succeeded`
`links`	object	HATEOAS-style relations: `self`, `events`, `cancel`, `canvas`
`retry_after_ms`	integer / null	Non-null while non-terminal; typically `3000` (3s)

Status state machine

queued   → running → succeeded
                   → failed
                   → canceled
                   → expired (rare; long-queued tasks time out)

Terminal: succeeded, failed, canceled, expired. Non-terminal: queued, running. Derive is_terminal = status in {"succeeded","failed","canceled","expired"}. Derive can_export = status == "succeeded" && result && result.canvas_id.

Distinguishing a retry from a queue wait

A task whose attempt died (execution-cap kill, worker timeout, lost heartbeat) is retried automatically, and it sits in queued for the whole backoff. That is not queue contention, and it is the single most-misread thing about this envelope: teams see a 10-minute queued and buy parallelism they do not need. Tell them apart:

Signal	Never started (real queue wait)	Retrying after a dead attempt
`status`	`queued`	`queued`
`attempts_started`	`0`	`>= 1`
`first_started_at`	`null`	the first attempt’s start
`error`	`null`	the previous attempt’s failure

is_retrying = status in {"queued", "running"} and attempts_started >= 1 and error is not None

Notes:

>= 1, not >= 2. attempts_started is incremented when a worker claims the task, so a first attempt that is currently running already reads 1, and it stays 1 through that attempt’s backoff. Combine it with status — running + attempts_started == 1 is an ordinary first run, queued + attempts_started == 1 is a retry.
error on a non-terminal task describes the previous attempt, not the current one. Its attempt field says which attempt produced it. A task that is running again after a failure deliberately keeps the failing reason for triage — do not render it as “this attempt failed”.
Wall-clock attribution. created_at → first_started_at is the true queue wait. created_at → started_at spans every dead attempt and its backoff too, so it overstates queueing on any retried task.
first_started_at: null means unknown, never “never started” — tasks created before this field shipped have no value for it. Read attempts_started for the never-started case.

There is no retrying status. The public status taxonomy is frozen, and consumers derive is_terminal from it, so a new value would break existing pollers.

Discriminator — `kind`

Task shape is polymorphic on kind:

`kind`	`input` includes	`result` includes (on succeeded)
`design`	`prompt`, `format`, `attachments`, `brand_kit_id`, `number_of_slides`, …	`canvas_id`, `canvas_url`, `conversation_id`, `export`
`remix`	`canvas_id`, `prompt`, `brand_kit_id`, …	`canvas_id`, `canvas_url`, `source_canvas_id`
`export`	declared in the enum; no code path produces a task of this kind today	—
`brand_kit_extract`	`url`	`brand_kit_id`

Always check kind before reading result fields. On a succeeded design task, result.export carries the finished design already rendered to a file — {url, format, status, page_count}, exported in the canvas’s category-default format. Read it directly instead of issuing a separate POST /v1/canvases/{id}/export. It is absent when auto-export was disabled (export_on_complete: {enabled: false}) or did not finish within the budget. Note: POST /v1/canvases/{id}/export never returns a Task envelope. It returns its own payload — {status: "completed", url, format, source} when the render lands inside the ~20s wait budget, or {status: "in_progress", task_id, retry_after_seconds} when it doesn’t. Poll GET /v1/canvases/{id}/export-status?task_id=… for the async case, not /v1/tasks/{id}. The export task kind and the export.succeeded / export.failed webhook events are declared in the public taxonomy but nothing emits them today. See canvases-and-exports.md.

Delivery patterns

Pick one per task — don’t stack:

1. Webhook (`callback_url`) — recommended for async backends

Pass callback_url in the task body. Webhook fires on terminal state only. Requires moda_live_… API key auth (OAuth callers get 400). See webhooks.md.

2. Polling — simplest for short-lived callers

POST /v1/tasks → task envelope with retry_after_ms
loop:
  wait retry_after_ms
  GET /v1/tasks/{id}
  break when status is terminal

Respect retry_after_ms. Don’t poll faster.

No sync-feel header

The API does not currently implement RFC 7240 Prefer: wait — the header is ignored on every endpoint. Operations that are fast (brand-kit creation, remix without a prompt) are simply synchronous; everything else is webhook or polling.

Timing expectations

Operation	Typical time
`POST /v1/tasks` (design from scratch)	2–10 min
`POST /v1/tasks` with `conversation_id` (follow-up edit)	1–5 min
`POST /v1/remix` with a prompt	2–10 min (it’s a design task under the hood)
`POST /v1/remix` without a prompt (plain duplicate)	< 1s (synchronous, no task)
`POST /v1/brand-kits` (from URL)	10–30s
`POST /v1/canvases/{id}/export`	seconds (signed URL inline); slow renders return a `task_id` after ~20s and finish in the background

Set user expectations up front. Don’t block callers on multi-minute operations.

Common wrong guesses

Polling faster than retry_after_ms. Burns your rate budget for no latency benefit.
Reading response.canvas_id on a canonical response. It’s response.result.canvas_id. The flat field is legacy (2026-04-12).
Expecting export kind from POST /v1/canvases/{id}/export. That endpoint does not return a Task envelope — its task_id is polled via /canvases/{id}/export-status.
Reading a long queued as queue contention. Check attempts_started first — a retry after a dead attempt looks identical to a queue wait on status alone.
Treating expired as a failure. It is terminal (same as the others) but the cause is queue-depth or worker-starvation, not a user-actionable error — retry the task fresh.

Upstream

docs.moda.app/api/tasks/startTask
docs.moda.app/api/tasks/getTask
docs.moda.app/api/versioning — for the legacy → canonical migration map

Welcome

Getting started

Brand kit

The AI agent

The canvas

Animation

Workspace

Export & sharing

Websites

Credits & billing

Integrations

Trust & security

FAQ

Task envelope

Task envelope

Full shape

Fields

Status state machine

Distinguishing a retry from a queue wait

Discriminator — `kind`

Delivery patterns

1. Webhook (`callback_url`) — recommended for async backends

2. Polling — simplest for short-lived callers

No sync-feel header

Timing expectations

Common wrong guesses

Upstream

​Task envelope

​Full shape

​Fields

​Status state machine

​Distinguishing a retry from a queue wait

​Discriminator — kind

​Delivery patterns

​1. Webhook (callback_url) — recommended for async backends

​2. Polling — simplest for short-lived callers

​No sync-feel header

​Timing expectations

​Common wrong guesses

​Upstream

Task envelope

Full shape

Fields

Status state machine

Distinguishing a retry from a queue wait

Discriminator — `kind`

Delivery patterns

1. Webhook (`callback_url`) — recommended for async backends

2. Polling — simplest for short-lived callers

No sync-feel header

Timing expectations

Common wrong guesses

Upstream