Uploading Assets to Playbook

You can add assets to Playbook either by pointing at a public URL or by using a two-step signed-upload flow.

Prerequisites

1. Access Token (access_token): OAuth2 token with asset-upload permission.
2. Organization Slug (slug): Your org's identifier (e.g., coolclient-ltd).
3. Board Token (board_token): (Optional) Where to place the asset. If omitted, asset goes to a default location (Uploaded today board). You can fetch board tokens using the boards endpoint.

---

Direct Upload from Public URL

Endpoint

POST /api/v1/{slug}/assets
Authorization: Bearer <access_token>
Content-Type: application/json

Request Body

Field	Type	Required	Description
uri	string	yes	Publicly accessible URL to fetch the file.
filename	string	yes	Desired filename in Playbook (e.g., image.jpg).
title	string	no	Display name for the asset.
description	string	no	Optional description or notes.
board_token	string	no	Token of the target board.
as_link	boolean	no	If true, asset is stored as an external link without processing.

Sample Request

curl -X POST https://api.playbook.com/api/v1/coolclient-ltd/assets \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "https://example.com/photo.jpg",
    "filename": "photo.jpg",
    "title": "User Photo",
    "collection_token": "homepage-assets"
}'

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": 101,
    "token": "assetToken123",
    "display_url": "https://cdn.playbook.com/photo.jpg",
    "media_type": "image/jpeg",
    "collection_token": "boardToken123",
    ...
  }
}

---

Two-Step Upload Flow (Prepare & Complete)

Use this flow when you want to upload large files or have more control over the upload process.

Step 1: Request Upload Credentials

Endpoint

POST /api/v1/{slug}/assets/upload_prepare
Authorization: Bearer <access_token>
Content-Type: application/json

Request Body

Field	Type	Required	Description
title	string	yes	File name or display label.
media_type	string	yes	MIME type (e.g., video/mp4).
size	integer	yes	File byte size.

Sample Request

curl -X POST https://api.playbook.com/api/v1/coolclient-ltd/assets/upload_prepare \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{
    "title": "Vacation Video",
    "media_type": "video/mp4",
    "size": 52428800
}'

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "upload_url": "https://storage.googleapis.com/playbook-uploads/...",
    "signed_gcs_id": "abc123def456",
    "file_extension": "mp4"
  }
}

Step 2: Upload the File to Storage

Use the upload_url (usually a pre-signed PUT URL) to send your file directly to storage.

curl -X PUT "https://storage.googleapis.com/playbook-uploads/..." \
  -H "Content-Type: video/mp4" \
  --data-binary @/path/to/Vacation.mp4

Step 3: Complete the Upload

Endpoint

POST /api/v1/{slug}/assets/upload_complete
Authorization: Bearer <access_token>
Content-Type: application/json

Request Body

Field	Type	Required	Description
signed_gcs_id	string	yes	ID returned from the prepare step.
title	string	no	(Optional) override title.
description	string	no	(Optional) asset description.
media_type	string	yes	Same MIME type as the prepare call.
size	integer	yes	Byte size (same as prepare).
board_token	string	no	Target board token.

Sample Request

curl -X POST https://be.playbook.com/api/v1/coolclient-ltd/assets/upload_complete \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "signed_gcs_id": "abc123def456",
    "title": "Vacation Video",
    "media_type": "video/mp4",
    "size": 52428800,
    "collection_token": "video-collection"
}'

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "token": "vacation-video-mp4",
    "display_url": "https://cdn.playbook.com/vacation-video.mp4",
    "media_type": "video/mp4"
  }
}

---

Error Handling

• 400 Bad Request: Missing or malformed JSON fields.
• 401 Unauthorized: Invalid or missing access_token.
• 422 Unprocessable Entity: File size/type mismatch or expired upload URL.

---

Tips

• For very large files, monitor your upload progress and retry on failures.
• Clean up or retry failed signed_gcs_ids by re-calling the prepare step.
• Track asset token for later operations like update or delete.

---