# Create Boards in an Organization

Use this guide to add new boards inside an existing Playbook organization.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

1. **Access token**: A valid Playbook API token with permissions to manage boards, sent as a Bearer token.
2. **Organization Slug** (`slug`): The URL-friendly identifier for your organization (e.g., `coolclient-ltd`).

## Endpoint & Authentication[​](#endpoint--authentication "Direct link to Endpoint & Authentication")

```
POST /v1/{slug}/boards

Authorization: Bearer YOUR_TOKEN

Content-Type: application/json
```

## Request Payload[​](#request-payload "Direct link to Request Payload")

| Field                     | Type   | Required | Description                                     |
| ------------------------- | ------ | -------- | ----------------------------------------------- |
| title                     | string | yes      | Name of the new board.                          |
| description               | string | no       | Optional description for it.                    |
| parent\_collection\_token | string | no       | Token of a parent board, to create a sub-board. |

### Sample Request — Top-Level Board[​](#sample-request--top-level-board "Direct link to Sample Request — Top-Level Board")

```
curl -X POST https://api.playbook.com/v1/coolclient-ltd/boards \

  -H "Authorization: Bearer YOUR_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "title": "Marketing Assets",

    "description": "Images and banners for marketing"

}'
```

### Sample Request — Sub-Board[​](#sample-request--sub-board "Direct link to Sample Request — Sub-Board")

```
curl -X POST https://api.playbook.com/v1/coolclient-ltd/boards \

  -H "Authorization: Bearer YOUR_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "title": "Social Media",

    "parent_collection_token": "marketing-assets"

}'
```

## Sample Response[​](#sample-response "Direct link to Sample Response")

```
HTTP/1.1 200 OK

Content-Type: application/json



{

  "data": {

    "id": 124,

    "token": "social-media",

    "title": "Social Media",

    "created_at": "2023-07-10T12:34:56Z",

    "updated_at": "2023-07-10T12:34:56Z",

    "parent_id": 123

  }

}
```

## Move a Board Under Another Board[​](#move-a-board-under-another-board "Direct link to Move a Board Under Another Board")

Send the new parent's token to the update endpoint. The board moves with everything inside it.

```
curl -X PATCH https://api.playbook.com/v1/coolclient-ltd/boards/social-media \

  -H "Authorization: Bearer YOUR_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "collection": { "parent_collection_token": "campaign-2026" }

}'
```

The parent is always given by its **token** in `parent_collection_token`. `parent_id` is not accepted on create or update — it is the numeric id the API *returns*, and sending it is refused rather than ignored (see below).

## Building a Folder Tree[​](#building-a-folder-tree "Direct link to Building a Folder Tree")

There is no single "create this tree" call: create each board with its parent's token, top-down, using the `token` each response returns. To hand a finished folder to someone who should drop files into it, share it with `enable_uploads` — see [Accepting Uploads on a Shared Link](/docs/guides/sharing_and_publishing.md#accepting-uploads-on-a-shared-link).

## Error Handling[​](#error-handling "Direct link to Error Handling")

* `401 Unauthorized`: Missing or invalid token.
* `422 Unprocessable Entity`: Validation errors (e.g., missing title), or an attribute the endpoint does not accept. Only `title`, `description` and `parent_collection_token` are accepted; anything else — `parent_id` included — returns `422` with code `unknown_parameter` and nothing is created or changed.
* `404 Not Found`: The specified `slug` or `parent_collection_token` does not exist.

## Next Steps[​](#next-steps "Direct link to Next Steps")

* Use the new `token` from the response when uploading assets into this board.