---
title: "Convert an item to another type"
method: POST
path: "/boards/{boardId}/items/{itemId}/convert"
tags: ["Items"]
---

# Convert an item to another type

`POST /boards/{boardId}/items/{itemId}/convert`

## Request

- Base URL: `https://api.mockflow.com/v1`
- URL: `https://api.mockflow.com/v1/boards/{boardId}/items/{itemId}/convert`
- Auth: HTTP bearer

Mida rebuilds the item's content as the target type and, once the new item has landed, deletes the source unless `keepSource` is true. See `convertibleTo` on GET /item-types/{type} for sensible targets.

## Request body

- object
  - `callbackUrl` string, uri: Optional. When the job this request starts finishes or fails, a short body is POSTed here once: `{ eventId, status, boardId, boardUrl, imageUrl }`, where status is `succeeded` or `failed` and imageUrl is a picture of what the job drew, or null. Signed with the workspace's callback secret (GET /webhooks/callback-secret). https to a public host. The full job is on GET /jobs/{jobId}.
  - `to` 'artifact' | 'audio' | 'calendar' | 'chart' | 'checklist' | 'cloud_architecture' | 'code_block' | 'comment' | 'connector' | 'customer_journey' | 'data_simulator' | 'database_diagram' | 'design' | 'floorplan' | 'flowchart' | 'gantt' | 'image' | 'kanban' | 'knowledge_graph' | 'map' | 'map_regions' | 'markdown' | 'mindmap' | 'model_3d' | 'mood_frame' | 'poll' | 'prototype' | 'reaction' | 'section' | 'shape' | 'spinning_wheel' | 'spreadsheet' | 'sticky_note' | 'storyboard' | 'strategy_map' | 'swimlane' | 'table' | 'text' | 'timeline' | 'tree_diagram' | 'upvote_ideas' | 'video' | 'whiteboard' | 'whiteboard_frame' | 'wireframe', required: Item types, generated from the MockFlow component registry. Primitive types are drawn by the editor; frame types are rich components whose `data` schema is the same one the MCP `render_*` tool accepts.
  - `keepSource` boolean

## Response `202`

Conversion started. The Job's result carries the new item id and `convertedFrom`.

- Job
  - `id` string
  - `kind` 'item.create' | 'item.update' | 'item.delete' | 'item.batch' | 'item.record' | 'ai.generate' | 'ai.modify' | 'skill.apply' | 'board.export'
  - `status` 'queued' | 'running' | 'succeeded' | 'failed'
  - `progress` integer
  - `message` string: Human readable progress, for example "Placing kanban".
  - `result` object, nullable
    - `itemIds` string[]
    - `updated` string[]
    - `deleted` string[]
    - `creditsUsed` integer
    - `boardTitle` string, nullable
    - `skill` string, nullable
    - `convertedFrom` string
    - `sourceDeleted` boolean
    - `target` 'board' | 'frame' | 'item': board.export. What was drawn.
    - `format` 'png' | 'mp4': board.export.
    - `scale` 1 | 2: board.export.
    - `imageUrl` string, uri: board.export. The PNG. Anyone with this URL can open it.
    - `width` integer: board.export. The image's width in pixels.
    - `height` integer: board.export. The image's height in pixels.
    - `videoUrl` string, uri: board.export with format mp4. The MP4. Anyone with this URL can open it.
    - `fps` integer: board.export with format mp4.
    - `duration` number: board.export with format mp4. Seconds.
    - `bytes` integer: board.export with format mp4. The file's size.
  - `error` Error (unresolved $ref)
  - `createdAt` string, date-time
  - `finishedAt` string, date-time, nullable
  - `callbackUrl` string, nullable: Where the job's result is POSTed
  - `callback` object, nullable: The newest delivery to callbackUrl, once the job has finished. Null until then, and when there is no callbackUrl.
    - `url` string
    - `deliveryId` string
    - `status` 'pending' | 'retrying' | 'succeeded' | 'failed' | 'cancelled'
    - `attempts` integer
    - `responseStatus` integer, nullable
    - `error` string, nullable
    - `deliveredAt` string, date-time, nullable
    - `nextRetryAt` string, date-time, nullable

## Other responses

- `402`: The workspace plan does not allow this, or AI credits are exhausted.
- `429`: Too many requests.

---

[API](https://skmtc.dev/mockflow/apis/mockflow-boards-api.md) - [All operations](https://skmtc.dev/mockflow/apis/mockflow-boards-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mockflow/apis/mockflow-boards-api/revisions/1a890390518c?raw)