Create Boards in an Organization

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

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

POST /v1/{slug}/boards
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

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

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

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

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

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

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.

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

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