---
title: "Generate on a board with a skill"
method: POST
path: "/boards/{boardId}/skills/{skillId}/apply"
tags: ["Skills"]
---

# Generate on a board with a skill

`POST /boards/{boardId}/skills/{skillId}/apply`

## Request

- Base URL: `https://api.mockflow.com/v1`
- URL: `https://api.mockflow.com/v1/boards/{boardId}/skills/{skillId}/apply`
- Auth: HTTP bearer

Runs a generation with the skill's instructions appended to the prompt and its output type forced, as the editor does when a skill is active.

## 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}.
  - `prompt` string, required
  - `withImages` boolean

## Response `202`

Generation started.

- 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)