# Create a board

> POST /boards

Source: https://mockflow.com/developers/reference/boards/create-board

**POST** `https://api.mockflow.com/v1/boards`  
Scopes: `boards:write`

**curl**

```bash
curl https://api.mockflow.com/v1/boards \
  -X POST \
  -H "Authorization: Bearer $MOCKFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Q4 launch",
  "prompt": "Plan the launch of our mobile app with a timeline, a kanban and a risk mind map."
}'
```

**JavaScript**

```javascript
const response = await fetch("https://api.mockflow.com/v1/boards", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MOCKFLOW_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "title": "Q4 launch",
  "prompt": "Plan the launch of our mobile app with a timeline, a kanban and a risk mind map."
})
});

const data = await response.json();
```

**Python**

```python
import os, requests

response = requests.post(
    "https://api.mockflow.com/v1/boards",
    headers={"Authorization": f"Bearer {os.environ['MOCKFLOW_API_KEY']}"},
    json={
  "title": "Q4 launch",
  "prompt": "Plan the launch of our mobile app with a timeline, a kanban and a risk mind map."
},
)

response.raise_for_status()
data = response.json()
```

**201**

```json
{
  "id": "brd_3f9e2a",
  "title": "Q4 Launch Planning",
  "spaceId": "spc_92kd",
  "url": "https://app.mockflow.com/board/3f9e2a",
  "publicUrl": "https://app.mockflow.com/board/brd_3f9e2a",
  "role": "owner"
}
```

**402**

```json
{
  "error": {
    "code": "plan_limit",
    "message": "AI credits exhausted. 0 of 2000 remaining this month.",
    "upgradeUrl": "https://mockflow.com/pricing"
  },
  "requestId": "req_01ja"
}
```

**429**

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "docsUrl": "https://mockflow.com/developers/concepts/errors#rate_limited"
  },
  "requestId": "req_45d49816999bac40"
}
```

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.

### Authorization

- `Authorization` (string, required): `Bearer <key>`. The key needs `boards:write` scope. Create and manage keys in the [developer console](/developers/console/); what each scope unlocks is on the [scopes page](/developers/concepts/scopes).

### Headers

- `Idempotency-Key` (string): A unique key per logical request. Replays within 24 hours return the original response.

### Body

- `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` (enum<string>[])
- `skill` (string): A skill id from GET /skills to apply to the prompt.
- `withImages` (boolean)

### Response

- `id` (string)
- `title` (string)
- `spaceId` (string | null): The design space, or null for the default space.
- `url` (string): Opens the board in the editor.
- `publicUrl` (string | null): The public viewer link, when the public link is on.
- `role` (enum<string>): 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. One of `owner`, `admin`, `editor` or `reviewer`.
- `locked` (boolean): Locked boards are read only for everyone.
- `position` (integer | null): Manual order inside the space, lowest first.
- `createdBy` (string)
- `createdAt` (string)
- `updatedAt` (string)
- `deletedAt` (string | null): Set while the board is in the trash.
- `job` (Job): - `id` (string)
  - `kind` (enum<string>): One of `item.create`, `item.update`, `item.delete`, `item.batch`, `ai.generate`, `ai.modify` or `skill.apply`.
  - `status` (enum<string>): One of `queued`, `running`, `succeeded` or `failed`.
  - `progress` (integer)
  - `message` (string): Human readable progress, for example "Placing kanban".
  - `result` (object | null)
  - `error` (error)
  - `createdAt` (string)
  - `finishedAt` (string | null)

### Errors

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