Skip to main content
POST
/
tasks
Start Design Task
curl --request POST \
  --url https://api.moda.app/v1/tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "conversation_id": "conv_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "canvas_id": "cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "template_canvas_id": "cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "canvas_name": "<string>",
  "brand_kit_id": "bk_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "skip_brand_kit": false,
  "callback_url": "<string>",
  "idempotency_key": "<string>",
  "attachments": [
    {
      "url": "<string>",
      "name": "<string>",
      "type": "image"
    }
  ],
  "format": {
    "width": 123,
    "height": 123,
    "label": "<string>",
    "page_count": 3
  },
  "reference_canvas_ids": [
    "cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV"
  ],
  "number_of_slides": 2
}
'
{
  "id": "task_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "attempt": 123,
  "max_attempts": 123,
  "links": {
    "self": "<string>",
    "events": "<string>",
    "cancel": "<string>",
    "canvas": "<string>"
  },
  "created_at": "<string>",
  "started_at": "<string>",
  "completed_at": "<string>",
  "progress": {
    "percent": 123,
    "step": "<string>",
    "message": "<string>"
  },
  "input": {},
  "result": {},
  "error": {},
  "credits": {
    "credits_used": 123,
    "credits_remaining": 123
  },
  "retry_after_ms": 123
}

Documentation Index

Fetch the complete documentation index at: https://docs.moda.app/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

API key from Settings > Developer > REST API

Headers

​
Moda-Version
enum<string>
default: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.

Available options:
2026-04-12,
2026-05-01
Example:

"2026-05-01"

Body

application/json
​
prompt
string
required

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

​
conversation_id
string | null

Prefixed conv_ wire ID (Crockford base32 body). Path parameters additionally accept a bare UUID string for back-compat; JSON body fields require the prefixed form.

Pattern: ^conv_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$
Example:

"conv_01HT9WK8N3M2J4A5Z6P7Q8R9TV"

​
canvas_id
string | null

Prefixed cvs_ wire ID (Crockford base32 body). Path parameters additionally accept a bare UUID string for back-compat; JSON body fields require the prefixed form.

Pattern: ^cvs_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$
Example:

"cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV"

​
template_canvas_id
string | null

Prefixed cvs_ wire ID (Crockford base32 body). Path parameters additionally accept a bare UUID string for back-compat; JSON body fields require the prefixed form.

Pattern: ^cvs_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$
Example:

"cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV"

​
canvas_name
string | null

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

​
brand_kit_id
string | null

Prefixed bk_ wire ID (Crockford base32 body). Path parameters additionally accept a bare UUID string for back-compat; JSON body fields require the prefixed form.

Pattern: ^bk_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$
Example:

"bk_01HT9WK8N3M2J4A5Z6P7Q8R9TV"

​
skip_brand_kit
boolean
default:false

If true, no brand kit is applied — even if the team has a default. Overrides brand_kit_id when both are provided.

​
callback_url
string | null

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_key
string | null

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.

​
attachments
(AttachmentInput · object | FileAttachment · object)[] | null

List of reference images or files for the AI agent to use as inspiration. Each item is either a URL-shape attachment ({url, name?, type?}) or a file-id-shape attachment ({file_id, role, label?}) referencing a file previously uploaded via POST /v1/uploads. The two shapes are distinguished by their required fields (url vs file_id).

​
format
FormatInput · object

Canvas format and dimensions. Controls the output size and layout type (e.g. slides, social media, custom).

​
model_tier
enum<string> | null

AI model tier: 'pro' (most capable), 'standard', or 'lite' (fastest). Defaults to automatic selection based on task complexity.

Available options:
pro,
standard,
lite
​
reference_canvas_ids
string[] | null

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

Prefixed cvs_ wire ID (Crockford base32 body). Path parameters additionally accept a bare UUID string for back-compat; JSON body fields require the prefixed form.

Pattern: ^cvs_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$
​
number_of_slides
integer | null

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.

Required range: x >= 1

Response

Successful Response

Canonical wire-format for every async design operation.

All consumers -- REST, webhooks, SSE, MCP -- serialize through Task.from_db() so the shape is always consistent.

​
id
string
required

Prefixed task_... identifier.

Pattern: ^task_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$
Example:

"task_01HT9WK8N3M2J4A5Z6P7Q8R9TV"

​
kind
enum<string>
required

Discriminator for the kind-specific result payload.

Available options:
design,
export,
remix,
brand_kit_extract
​
status
enum<string>
required

Current lifecycle status.

Available options:
queued,
running,
succeeded,
failed,
canceled,
expired
​
attempt
integer
required

Current attempt number (1-based).

​
max_attempts
integer
required

Maximum attempts before dead-lettering.

​
links
TaskLinks · object
required

HATEOAS links for this task.

​
created_at
string | null

ISO 8601 timestamp.

​
started_at
string | null

ISO 8601 timestamp.

​
completed_at
string | null

ISO 8601 timestamp.

​
progress
TaskProgress · object

Live progress for running tasks. Null when not applicable.

​
input
Input · object

Sanitized echo of the original request.

​
result
Result · object

Kind-specific result payload. Present only for succeeded tasks.

​
error
Error · object

Error info for failed tasks: {message, retryable}.

​
credits
CreditUsage · object

Credit usage. Present only for completed tasks when billing is enabled.

​
retry_after_ms
integer | null

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