MOmoda
tasks

Start Design Task

Changed on

Start an AI design task. Returns immediately with a task ID for polling.

post/tasks

Request

  • Base URL
    https://api.moda.app/v1
  • URL
    https://api.moda.app/v1/tasks
  • Auth
    HTTP bearer

Headers

Moda-Version'2026-04-12' | '2026-05-01'
Example:2026-05-01

Calendar-dated API version pin. New integrations should pin 2026-05-01 to opt into the newest response shapes. For back-compat the server also accepts requests with no header and resolves them to the current default (today: 2026-04-12); that default advances on each sunset date. Any unsupported value returns 400 unsupported_version.

Request body

promptstring required

Natural-language description of the design task for the AI agent.

user_request_quotestring nullable

For an agent handing work to Moda's agent on a user's behalf: the user's own words naming Moda as the ACTOR ("have the Moda agent design it"), quoted verbatim. Recorded on the usage event so the delegation decision is auditable. Not validated and not interpreted — it grounds the decision, it does not gate it. Optional here (the app and existing API integrations start their own tasks and have no user to quote); the agent surfaces that expose delegation as a choice — moda task submit and the connector's task_delegate — require it.

conversation_idstring nullable

Prefixed conv_ wire ID (Crockford base32 body) — the canonical, recommended form. For back-compat, a bare UUID string is also accepted in both path parameters and JSON request bodies (older integrations that stored raw UUIDs keep working), as is the prefix over a UUID body (conv_00000000-0000-4000-8000-000000000000). All three are permanent, supported inputs; only the canonical form is ever emitted.

canvas_idstring nullable

Prefixed cvs_ wire ID (Crockford base32 body) — the canonical, recommended form. For back-compat, a bare UUID string is also accepted in both path parameters and JSON request bodies (older integrations that stored raw UUIDs keep working), as is the prefix over a UUID body (cvs_00000000-0000-4000-8000-000000000000). All three are permanent, supported inputs; only the canonical form is ever emitted.

template_canvas_idstring nullable

Prefixed cvs_ wire ID (Crockford base32 body) — the canonical, recommended form. For back-compat, a bare UUID string is also accepted in both path parameters and JSON request bodies (older integrations that stored raw UUIDs keep working), as is the prefix over a UUID body (cvs_00000000-0000-4000-8000-000000000000). All three are permanent, supported inputs; only the canonical form is ever emitted.

canvas_namestring nullable

Name for the new canvas. Used when creating (canvas_id omitted) or when remixing via template_canvas_id (overrides the default Remix of <source>).

brand_kit_idstring nullable

Prefixed bk_ wire ID (Crockford base32 body) — the canonical, recommended form. For back-compat, a bare UUID string is also accepted in both path parameters and JSON request bodies (older integrations that stored raw UUIDs keep working), as is the prefix over a UUID body (bk_00000000-0000-4000-8000-000000000000). All three are permanent, supported inputs; only the canonical form is ever emitted.

skip_brand_kitboolean

If true, no brand kit is applied — every brand-kit source is suppressed, including the canvas's own kit, the team default, and any explicit brand_kit_id override. Use only when the design must be unbranded; to merely leave the canvas's existing kit alone, omit brand_kit_id instead.

callback_urlstring nullable

HTTPS URL to receive a webhook POST when the job completes, fails, or is cancelled. See the Webhooks documentation for payload format and signature verification.

idempotency_keystring nullable

Client-generated unique key to prevent duplicate job creation. If a job with this key already exists, its status is returned instead of creating a new one.

model_tier'pro' | 'pro-fast' | 'fable-5.1' | 'standard' | 'lite' | 'kimi-k2.5' | 'kimi-k2.6' | 'gpt-5.6' nullable

AI model tier: 'pro' (best for complex tasks), 'pro-fast' (the same quality as Pro with faster output and higher credit usage), 'fable-5.1' (Claude Fable 5.1 at low effort; premium plans only), 'standard', 'lite', 'kimi-k2.5' (Fireworks-hosted Kimi K2.5), 'kimi-k2.6' (Fireworks-hosted Kimi K2.6), or 'gpt-5.6' (OpenAI GPT-5.6 at high reasoning). Defaults to automatic selection based on task complexity.

reference_canvas_idsstring[] nullable

List of prefixed cvs_ IDs to use as design inspiration. The agent can see these designs and reference their style, layout, or content.

number_of_slidesinteger nullable

Optional maximum number of slides for slide-generation jobs. When omitted for slides, Moda defaults to an 8-slide target and clamps to your plan limit. Rejected with a role='import' attachment — an existing-deck edit keeps the deck's own slide count.

Example request

{
  "conversation_id": "conv_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "canvas_id": "cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "template_canvas_id": "cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "brand_kit_id": "bk_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "attachments": [
    {
      "file_id": "file_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
      "role": "source",
      "label": "Q2 strategy brief"
    }
  ],
  "reference_canvas_ids": [
    "cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV"
  ]
}

Response

Successful Response

idstring required

Prefixed task_... identifier.

kind'design' | 'export' | 'remix' | 'brand_kit_extract' | 'layerize_assets' required

Discriminator for the kind-specific result payload.

status'queued' | 'running' | 'succeeded' | 'failed' | 'canceled' | 'expired' required

Frozen public status taxonomy. DB enum values are mapped at the API boundary -- never exposed directly.

created_atstring nullable

ISO 8601 timestamp.

started_atstring nullable

ISO 8601 timestamp.

completed_atstring nullable

ISO 8601 timestamp.

attemptinteger required

Current attempt number (1-based).

max_attemptsinteger required

Maximum attempts before dead-lettering.

attempts_startedinteger required

Number of attempts STARTED (claimed by a worker) — never attempts completed. 0 means the task has never been claimed. The claim itself increments the counter, so a task on its first attempt reports 1 while RUNNING and stays at 1 through that attempt's retry backoff. The retry signal is therefore status == "queued" && attempts_started >= 1 (a queued task that has already burned an attempt), NOT >= 2. Unlike attempt, this is the raw counter and is not floored to 1.

first_started_atstring nullable

ISO 8601 timestamp of when the FIRST attempt was claimed. null means unknown — either the task has never started, or it predates this field being recorded. started_at remains the CURRENT attempt's start, so on a retried task the two differ and the gap is the real wall-clock age of the work.

inputobject nullable

Sanitized echo of the original request.

errorobject nullable

Error info: {message, retryable, attempt}. Present for failed tasks, and also for a NON-terminal task that carries an error from an earlier attempt — on a non-terminal task this always describes the PREVIOUS, already-dead attempt, never the one currently in flight. attempt is the attempts_started value the error is tied to (0 when the failure happened before any claim).

retry_after_msinteger nullable

Suggested milliseconds to wait before the next poll. Null for terminal tasks.

Changes

  • 9ac6a3abc0f8Revision changes
    • breaking

      removed the enum value fable of the request property /

    • warning

      added the new layerize_assets enum value to the response property for the response status

    • info

      added the new optional request property

    • info

      added the new fable-5.1 enum value to the request property /

    • info

      added the new pro-fast enum value to the request property /

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added to the response property anyOf list for the response status

    • info

      added the required property to the response with the status