> ## 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. # Start Design Task > Start an AI design task. Returns immediately with a task ID for polling. ## OpenAPI ````yaml /openapi/moda-public-api.yaml post /tasks openapi: 3.1.0 info: title: Moda Public API description: > Programmatic access to Moda's canvas design platform. Create designs, export assets, manage brand kits, and run AI design tasks. ## Versioning Pin response shapes with a calendar-dated `Moda-Version` header (e.g. `2026-05-01`). **The pin is global** — it applies to every endpoint in the request, not just the one you adopted it for, so raising it to use a new endpoint also moves your other responses to that version's shapes. ### Migrating `2026-04-12` → `2026-05-01` - **Tasks** move from the flat `JobResponse` (`job_id`, `canvas_url`, `can_export`) to the canonical `Task` envelope. The export artifact is now under `result.export` as `{url, format, page_count}`; update any code that read the export URL from the old top-level fields. - **Multi-page PNG/JPEG exports are delivered as a single `.zip`** of per-page files (`page-1.png`, …), so `result.export.format` is `zip`. For one bundled document instead, request `format=pdf` or `pptx`; for a single image, pass `page_number`. version: 1.0.0 x-moda-api-version: '2026-05-01' servers: - url: https://api.moda.app/v1 description: Production security: [] tags: - name: canvases description: List, search, read, export, and share canvases - name: tasks description: Start and monitor AI design tasks - name: organizations description: List organizations and teams - name: credits description: Check credit balance and usage - name: brand-kits description: Manage brand kits - name: remix description: Duplicate and edit canvases - name: share-links description: Resolve share URLs to canvas identifiers - name: uploads description: Upload files for use as attachments - name: usage description: Aggregate API usage stats for the caller's team - name: embed description: Signed iframe embed sessions - name: web description: 'Metered web research: search and page reading' - name: websites description: >- Create, update, publish, screenshot, and manage hosted multi-page static sites - name: drive description: >- Organize the workspace: folders, the folder tree, and item move/rename/visibility/delete for folders, canvases, and files paths: /tasks: post: tags: - tasks summary: Start Design Task description: Start an AI design task. Returns immediately with a task ID for polling. operationId: startTask parameters: - $ref: '#/components/parameters/ModaVersion' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartTaskRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Task' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Permission denied for this scope. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: Conflict (idempotency / resource state). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: Request validation failed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: Internal error. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - API Key: [] components: parameters: ModaVersion: name: Moda-Version in: header required: false description: >- 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](/api-reference/versioning). Any unsupported value returns 400 `unsupported_version`. example: '2026-05-01' schema: type: string enum: - '2026-04-12' - '2026-05-01' default: '2026-05-01' example: '2026-05-01' schemas: StartTaskRequest: properties: prompt: type: string title: Prompt description: Natural-language description of the design task for the AI agent. conversation_id: anyOf: - type: string pattern: ^conv_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$ description: >- 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). Both are permanent, supported inputs. example: conv_01HT9WK8N3M2J4A5Z6P7Q8R9TV - type: 'null' title: Conversation Id description: >- Prefixed ``conv_`` ID of an existing conversation to resume. When provided, the AI agent has full context of all previous interactions in the conversation. Omit to start a new conversation. The conversation_id is returned in every job response. canvas_id: anyOf: - type: string pattern: ^cvs_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$ description: >- 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). Both are permanent, supported inputs. example: cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV - type: 'null' title: Canvas Id description: >- Prefixed ``cvs_`` ID of an existing canvas to edit. Omit to create a new canvas. When omitted and the applied brand kit has a saved slides theme canvas, that canvas's page layouts are used as the layout source for generated slides. template_canvas_id: anyOf: - type: string pattern: ^cvs_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$ description: >- 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). Both are permanent, supported inputs. example: cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV - type: 'null' title: Template Canvas Id description: >- Prefixed ``cvs_`` ID of a source canvas to remix. A new canvas is created in your team as a copy of the source and the agent runs against the copy. Accepts any canvas you can read from your team — the source does NOT need to be flagged as a template. When provided, the skill the agent runs is selected automatically: same brand kit as the source → content-only remix; different brand kit → full rebrand (colors, fonts, copy, images). Mutually exclusive with ``canvas_id``. canvas_name: anyOf: - type: string - type: 'null' title: Canvas Name description: >- Name for the new canvas. Used when creating (``canvas_id`` omitted) or when remixing via ``template_canvas_id`` (overrides the default ``Remix of ``). brand_kit_id: anyOf: - type: string pattern: ^bk_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$ description: >- 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). Both are permanent, supported inputs. example: bk_01HT9WK8N3M2J4A5Z6P7Q8R9TV - type: 'null' title: Brand Kit Id description: >- Prefixed ``bk_`` ID of a brand kit to apply. The agent uses these colors, fonts, and guidelines. If omitted, the resolution rule is: when ``canvas_id`` is supplied (or ``conversation_id`` is passed to resume an existing canvas) the canvas's existing brand kit is preserved (the team's default brand kit is used as a fallback only when the canvas has no kit of its own); when creating a new canvas the team's default brand kit applies, or the design runs unbranded if the team has no default. To run without any brand kit (overriding both the canvas's kit and the team default), set skip_brand_kit=true. skip_brand_kit: type: boolean title: Skip Brand Kit description: >- 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. default: false callback_url: anyOf: - type: string - type: 'null' title: Callback Url description: >- 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: anyOf: - type: string - type: 'null' title: Idempotency Key description: >- 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: anyOf: - items: anyOf: - $ref: '#/components/schemas/AttachmentInput' - $ref: '#/components/schemas/FileAttachment' type: array - type: 'null' title: Attachments description: >- 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: anyOf: - $ref: '#/components/schemas/FormatInput' - type: 'null' description: >- Canvas format and dimensions. Controls the output size and layout type (e.g. slides, social media, custom). model_tier: anyOf: - type: string enum: - pro - pro-fast - standard - lite - kimi-k2.5 - kimi-k2.6 - kimi-k3 - gpt-5.6 - type: 'null' title: Model Tier description: >- AI model tier: 'pro' (best for complex tasks), 'pro-fast' (the same quality as Pro with faster output and higher credit usage), 'standard', 'lite', 'kimi-k2.5' (Fireworks-hosted Kimi K2.5), 'kimi-k2.6' (Fireworks-hosted Kimi K2.6), 'kimi-k3' (Moonshot-hosted Kimi K3), or 'gpt-5.6' (OpenAI GPT-5.6 at high reasoning). Defaults to automatic selection based on task complexity. reference_canvas_ids: anyOf: - items: type: string pattern: ^cvs_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$ description: >- 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). Both are permanent, supported inputs. example: cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV type: array - type: 'null' title: Reference Canvas Ids description: >- 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_slides: anyOf: - type: integer minimum: 1 - type: 'null' title: Number Of Slides description: >- 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. export_on_complete: anyOf: - $ref: '#/components/schemas/ExportOnCompleteOption' - type: 'null' description: >- Auto-export preferences applied when the task finishes. The finished design is rendered to ``result.export`` (and the completion webhook), so a follow-up ``POST /v1/canvases/{id}/export`` for the same canvas hits the cache instead of re-rendering. Omit to use the canvas category default (``slides``→PPTX, ``pdf``→PDF, others→PNG); pass ``{enabled: false}`` to opt out of the auto-export entirely. Multi-page PNG/JPEG bundles into a ``.zip`` of per-page files; ``result.export.format`` reflects what was actually delivered (``png``, ``jpeg``, ``pdf``, ``pptx``, or ``zip``). additionalProperties: false type: object required: - prompt title: StartTaskRequest Task: properties: id: type: string pattern: ^task_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$ title: Id description: Prefixed ``task_...`` identifier. example: task_01HT9WK8N3M2J4A5Z6P7Q8R9TV kind: $ref: '#/components/schemas/TaskKind' status: $ref: '#/components/schemas/PublicTaskStatus' description: Current lifecycle status. created_at: anyOf: - type: string - type: 'null' title: Created At description: ISO 8601 timestamp. started_at: anyOf: - type: string - type: 'null' title: Started At description: ISO 8601 timestamp. completed_at: anyOf: - type: string - type: 'null' title: Completed At description: ISO 8601 timestamp. progress: anyOf: - $ref: '#/components/schemas/TaskProgress' - type: 'null' description: Live progress for running tasks. Null when not applicable. attempt: type: integer title: Attempt description: Current attempt number (1-based). max_attempts: type: integer title: Max Attempts description: Maximum attempts before dead-lettering. input: anyOf: - additionalProperties: true type: object - type: 'null' title: Input description: Sanitized echo of the original request. result: anyOf: - $ref: '#/components/schemas/TaskResult' - type: 'null' description: Result payload. Present only for succeeded tasks. error: anyOf: - additionalProperties: true type: object - type: 'null' title: Error description: 'Error info for failed tasks: ``{message, retryable}``.' credits: anyOf: - $ref: '#/components/schemas/CreditUsage' - type: 'null' description: >- Credit usage. Present only for completed tasks when billing is enabled. links: $ref: '#/components/schemas/TaskLinks' description: HATEOAS links for this task. retry_after_ms: anyOf: - type: integer - type: 'null' title: Retry After Ms description: >- Suggested milliseconds to wait before the next poll. Null for terminal tasks. type: object required: - id - kind - status - attempt - max_attempts - links title: Task description: |- 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. ErrorEnvelope: properties: type: $ref: '#/components/schemas/ErrorType' code: type: string title: Code description: >- Stable machine string keyed to doc_url. Never changes once published. message: type: string title: Message description: >- Human-readable message, for developers. Not localized, not user-facing. doc_url: type: string title: Doc Url description: Permalink to the docs page for this code. request_id: anyOf: - type: string - type: 'null' title: Request Id description: Correlator for logs/Sentry/audit. causes: anyOf: - items: $ref: '#/components/schemas/ErrorEnvelope' type: array - type: 'null' title: Causes description: Aggregated upstream failures (e.g. per-page export errors). details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Code-specific detail payload (e.g. validation field list). Callers should pass ``None`` rather than ``{}`` to omit the key from the response. retry_after_ms: anyOf: - type: integer - type: 'null' title: Retry After Ms description: Hint for rate-limited or transient errors. retryable: anyOf: - type: boolean - type: 'null' title: Retryable description: >- Explicit retryability for this code, from the error-code registry: ``false`` means retrying the same request cannot succeed (fix the input / resource first); ``true`` means the condition is transient and a retry (with backoff / after the blocker clears) can succeed. Omitted for codes whose retryability is context-dependent — do not derive it from ``type`` or the HTTP status when this field is present. type: object required: - type - code - message - doc_url title: ErrorEnvelope description: >- Canonical error payload, nested under the top-level ``{"error": ...}`` key. AttachmentInput: properties: url: type: string title: Url description: Public URL of the image or file. name: anyOf: - type: string - type: 'null' title: Name description: Display name for the attachment. type: type: string enum: - image - pdf - pptx - url title: Type description: 'Attachment type: ''image'', ''pdf'', ''pptx'', or ''url''.' default: image additionalProperties: false type: object required: - url title: AttachmentInput FileAttachment: properties: file_id: type: string pattern: ^file_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$ title: File Id description: Prefixed ``file_`` ID returned by ``POST /v1/uploads``. example: file_01HT9WK8N3M2J4A5Z6P7Q8R9TV role: type: string enum: - source - reference - asset - import title: Role description: >- How the agent should treat this file: 'source' = extract content from it; 'reference' = emulate its style without reproducing verbatim; 'asset' = use the file directly in outputs (hint only — directly-use behavior evolves with ENG-2549). 'import' = convert a PowerPoint (.pptx) deck into editable slides on the canvas, then design against it. Only valid for PPTX attachments; any other file type is rejected. example: source label: anyOf: - type: string - type: 'null' title: Label description: Optional human-facing label. example: Q2 strategy brief additionalProperties: false type: object required: - file_id - role title: FileAttachment description: >- Reference to a previously uploaded file by its prefixed ``file_`` id. Paired with ``AttachmentInput`` under ``StartTaskRequest.attachments`` via Pydantic smart-union. The caller uploads a file first via ``POST /v1/uploads`` (or the MCP upload-URL flow) and then passes the resulting ``file_id`` here with a ``role`` that tells the agent how to treat the file. FormatInput: properties: category: anyOf: - type: string enum: - slides - social - carousel - pdf - diagram - ui - animation - prints - web-ads - other - type: 'null' title: Category description: >- Format category: 'slides', 'social', 'carousel', 'pdf', 'diagram', 'ui', 'animation', 'prints', 'web-ads', or 'other'. Controls the layout approach. width: anyOf: - type: integer - type: 'null' title: Width description: >- Canvas width in pixels. Common: 1920x1080 (slides), 1080x1080 (social square), 1080x1920 (social story). height: anyOf: - type: integer - type: 'null' title: Height description: Canvas height in pixels. label: anyOf: - type: string - type: 'null' title: Label description: Human-readable format label (e.g. 'Instagram Story', '16:9 Slides'). dimensions: anyOf: - type: string enum: - square - linkedin - portrait - type: 'null' title: Dimensions description: >- Carousel dimensions preset. 'square' = 1080x1080, 'linkedin' = 1080x1350 LinkedIn landscape, 'portrait' = 1080x1920 Instagram story. Only used when ``category='carousel'``. page_count: anyOf: - type: integer minimum: 1 - type: 'null' title: Page Count description: >- Number of carousel pages to generate. When omitted, Moda picks a default target and clamps to your plan limit. Only used when ``category='carousel'``. type: object title: FormatInput ExportOnCompleteOption: properties: enabled: type: boolean title: Enabled description: >- When ``true`` (default), the design task auto-exports its finished canvas to ``result.export``. Set to ``false`` to skip the auto-export — useful when you only need the canvas reference and will request a different artifact later. default: true format: anyOf: - type: string enum: - png - jpeg - pdf - pptx - type: 'null' title: Format description: >- Output format for the auto-export. Omit to use the canvas category default (``slides``→``pptx``, ``pdf``→``pdf``, others→``png``). Multi-page PNG/JPEG exports are delivered as a ``.zip`` of per-page files; in that case ``result.export.format`` is ``zip`` while the per-page files inside use the requested raster format. pixel_ratio: anyOf: - type: integer maximum: 4 minimum: 1 - type: 'null' title: Pixel Ratio description: >- Render scale multiplier (1-4). Omit to use the category default (``social``/``carousel`` PNGs render at 1×; PDFs at 3×; everything else at 2×). Pinning this matches the value that ``POST /v1/canvases/{id}/export`` would compute for the same canvas, so a follow-up manual export reuses the cached artifact. additionalProperties: false type: object title: ExportOnCompleteOption description: >- Auto-export preferences carried alongside a ``start_design_task`` request. The agent-jobs completion hook (``app.services.exports.auto_export``) reads these to decide whether to render the finished design, in what format, and at what scale. Defaults follow the canvas category — typically the right choice — so most callers leave the field unset entirely. TaskKind: type: string enum: - design - export - remix - brand_kit_extract title: TaskKind description: Discriminator for the kind-specific ``result`` payload. PublicTaskStatus: type: string enum: - queued - running - succeeded - failed - canceled - expired title: PublicTaskStatus description: |- Frozen public status taxonomy. DB enum values are mapped at the API boundary -- never exposed directly. TaskProgress: properties: percent: anyOf: - type: integer - type: 'null' title: Percent description: Estimated completion percentage (0-100). step: anyOf: - type: string - type: 'null' title: Step description: Machine-readable step name the agent is executing. message: anyOf: - type: string - type: 'null' title: Message description: Human-readable progress message. type: object title: TaskProgress description: Live progress indicator for a running task. TaskResult: properties: canvas_id: anyOf: - type: string - type: 'null' title: Canvas Id description: Prefixed ``cvs_...`` id of the resulting canvas. canvas_url: anyOf: - type: string - type: 'null' title: Canvas Url description: URL to open the canvas in the Moda editor. canvas_name: anyOf: - type: string - type: 'null' title: Canvas Name description: Display name of the resulting canvas. conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: >- Prefixed ``conv_...`` id — pass to a later task to keep iterating with full context. source_canvas_id: anyOf: - type: string - type: 'null' title: Source Canvas Id description: >- Prefixed ``cvs_...`` id of the source canvas, for template-remix tasks. source_canvas_url: anyOf: - type: string - type: 'null' title: Source Canvas Url description: Editor URL of the source canvas, for template-remix tasks. theme_canvas_id: anyOf: - type: string - type: 'null' title: Theme Canvas Id description: >- Prefixed ``cvs_...`` id of the theme canvas attached to the resulting canvas, when a brand kit default theme was applied. Null when the deck is unthemed. export: anyOf: - $ref: '#/components/schemas/TaskExport' - type: 'null' description: >- The finished design, auto-exported and cached. Populated once the design task has rendered its result — use this artifact instead of calling the export endpoint again for the same canvas. additionalProperties: true type: object title: TaskResult description: >- Result payload of a design or remix task. Populated when ``status`` is ``succeeded``, and partially populated for some in-flight tasks (a remix surfaces its source canvas before the design task finishes). Extra keys are permitted so synchronous-completion payloads pass through without schema churn. CreditUsage: properties: credits_used: anyOf: - type: integer - type: 'null' title: Credits Used description: >- Number of credits consumed by this operation. Null if billing is not enabled or the job hasn't completed yet. credits_remaining: anyOf: - type: integer - type: 'null' title: Credits Remaining description: Credit balance after this operation. Null if billing is not enabled. type: object title: CreditUsage TaskLinks: properties: self: type: string title: Self description: Canonical URL of this task resource. events: anyOf: - type: string - type: 'null' title: Events description: >- Reserved for a future event-stream URL; currently always ``null``. Moda does not expose a task event stream — poll ``GET /v1/tasks/{id}`` using ``retry_after_ms`` instead. cancel: anyOf: - type: string - type: 'null' title: Cancel description: URL to POST a cancellation request. canvas: anyOf: - type: string - type: 'null' title: Canvas description: URL to open the canvas in the Moda editor. type: object required: - self title: TaskLinks description: HATEOAS-style links for navigating from a Task resource. ErrorType: type: string enum: - invalid_request - authentication - permission - not_found - conflict - rate_limited - idempotency_conflict - unprocessable - upstream_error - internal_error title: ErrorType description: Closed set of high-level categories SDKs branch on. TaskExport: properties: url: type: string title: Url description: Signed, time-limited URL to download the rendered file. format: type: string title: Format description: >- Delivered format — ``png``, ``jpeg``, ``pdf``, ``pptx``, or ``zip``. Multi-page PNG/JPEG exports are bundled into a ``.zip`` of per-page files (``page-1.png``, ``page-2.png``, …) since a single image container can't carry multiple pages. status: type: string title: Status description: Render status; ``completed`` when the file is ready at ``url``. page_count: type: integer title: Page Count description: Number of pages in the exported file. type: object required: - url - format - status - page_count title: TaskExport description: |- Rendered export of a finished design task. Present on ``result.export`` once a programmatic (MCP / API) design task completes — the design is auto-exported in the canvas's category-default format and cached. Read this artifact directly instead of issuing a separate ``POST /v1/canvases/{id}/export`` for the same canvas. securitySchemes: API Key: type: http description: API key from Settings > Developer > REST API scheme: bearer ````