> ## 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. # List Tasks > List recent design tasks (cursor-paginated, newest first). Returns at most ``limit`` tasks per page (default 20, cap 100). ``total`` is the true count under the current ``canvas_id`` / ``status`` filters; iterate ``next_cursor`` while ``has_more`` is ``true``. ## OpenAPI ````yaml /openapi/moda-public-api.yaml get /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: get: tags: - tasks summary: List Tasks description: >- List recent design tasks (cursor-paginated, newest first). Returns at most ``limit`` tasks per page (default 20, cap 100). ``total`` is the true count under the current ``canvas_id`` / ``status`` filters; iterate ``next_cursor`` while ``has_more`` is ``true``. operationId: listTasks parameters: - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Opaque pagination cursor. Pass the ``next_cursor`` from the previous response. Omit on the first request. title: Cursor description: >- Opaque pagination cursor. Pass the ``next_cursor`` from the previous response. Omit on the first request. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Max tasks per page. Defaults to 20, caps at 100. default: 20 title: Limit description: Max tasks per page. Defaults to 20, caps at 100. - name: canvas_id in: query required: false schema: 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 - name: status in: query required: false schema: anyOf: - type: string - type: 'null' title: Status - $ref: '#/components/parameters/ModaVersion' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ListTasksResponse' '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: ListTasksResponse: properties: data: items: $ref: '#/components/schemas/Task' type: array title: Data description: Tasks in this page, newest first. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: >- Opaque cursor to pass as ``?cursor=`` on the next request. ``null`` means you've reached the end of the collection. returned: type: integer title: Returned description: >- Number of items in this page (always ``len(data)``; derived server-side). default: 0 has_more: type: boolean title: Has More description: >- ``true`` when more items exist beyond this page — keep requesting with ``next_cursor`` until this is ``false``. Never trust ``len(data) < limit`` alone. default: false limit: anyOf: - type: integer - type: 'null' title: Limit description: The effective page-size limit this response was computed with. total: anyOf: - type: integer - type: 'null' title: Total description: >- True total number of items in the collection (after filters), when the endpoint can count cheaply. ``null`` on log/search lanes — use ``has_more`` there. type: object required: - data title: ListTasksResponse description: >- Cursor-paginated tasks list response (ENG-2377). ``total`` is the true count of tasks visible to the key's owner under the current filters; ``returned`` / ``has_more`` are derived server-side. 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. 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. 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. 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. 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 ````