---
title: "Create a board"
method: POST
path: "/boards"
tags: ["Boards"]
---

# Create a board

`POST /boards`

## Request

- Base URL: `https://api.mockflow.com/v1`
- URL: `https://api.mockflow.com/v1/boards`
- Auth: HTTP bearer

A new board in a space, or in the default space when `spaceId` is omitted. Basic makes three
boards, trashed ones included; the cap answers 402. With `prompt`, Mida fills the new board
in the background and the response carries the Job to poll.

## Headers

- `Idempotency-Key` string

## 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}.
  - `title` string, required
  - `spaceId` string: Omit for the default space.
  - `prompt` string: Have Mida build the board from this. Needs the ai:generate scope and a Plus or Max plan.
  - `outputTypes` ItemType[]
  - `skill` string: A skill id from GET /skills to apply to the prompt.
  - `withImages` boolean

## Response `201`

Created.

- object
  - `id` string
  - `title` string
  - `spaceId` string, nullable: The design space, or null for the default space.
  - `url` string, uri: Opens the board in the editor.
  - `publicUrl` string, uri, nullable: The public viewer link, when the public link is on.
  - `role` 'owner' | 'admin' | 'editor' | 'reviewer': The product's roles. Owner is the workspace that holds the board or space and cannot be granted or transferred. Admin can rename and share, editor can edit, reviewer can view, export and add comment items. There is no viewer role and no pending state.
  - `locked` boolean: Locked boards are read only for everyone.
  - `position` integer, nullable: Manual order inside the space, lowest first.
  - `createdBy` string
  - `createdAt` string, date-time
  - `updatedAt` string, date-time
  - `deletedAt` string, date-time, nullable: Set while the board is in the trash.
  - `job` 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)