Boords API

The Boords API gives you programmatic access to your projects, storyboards, frames, and comments — so you can build custom integrations, automate workflows, and keep your tools in sync.

The Boords API is currently in Beta. The core functionality is stable, but some details may change as we refine the experience.

For the full endpoint reference, visit the API documentation.

What you can do with the API

The API lets you:

• Create and manage projects — organise your work programmatically
• Build storyboards from scripts — import structured content and generate storyboards with frames in a single request
• Read and update frames — access frame content, images, and field data
• Upload images to frames — use your own images, or generate them with any external tool (like Midjourney, DALL·E, or your own pipeline) and attach them to frames via URL or base64
• Manage comments — create, update, and resolve comments on frames
• Handle team members — invite users, update roles, and manage project access
• Set up webhooks — get notified when things change in your Boords workspace

Use with AI agents — The Boords API works great with AI-powered tools like Claude and Cowork. Give your AI assistant an API token and it can create projects, import scripts, update frames, and manage your storyboards on your behalf — all through natural conversation.

Prerequisites

To use the Boords API, you'll need:

• A paid Boords plan — see pricing
• An API token generated from your team settings

Creating an API token

API tokens are managed in Settings → Team → API. You'll need an Admin or Manager role to create tokens.

To create a token:

1. Go to Settings → Team → API
2. Click Create token
3. Give your token a name (e.g. "Zapier", "CI Pipeline", "Custom Integration")
4. Choose an expiry period
5. Copy the token — it's only shown once

Tokens start with bap_ and are tied to your user account. Any actions performed with your token use your permissions and appear as your activity.

Token security

• Store tokens securely — treat them like passwords
• Use descriptive names — so you know what each token is for
• Rotate tokens regularly — you can rotate a token at any time, which revokes the old one and issues a new one
• Revoke unused tokens — if you no longer need a token, revoke it from the same settings page

Authentication

Include your API token in the X-API-KEY header with every request:

X-API-KEY: bap_your_token_here

You can also include an optional X-API-CLIENT header to identify your integration:

X-API-CLIENT: my-custom-tool

This helps you track which integration made which changes in your activity log.

Core concepts

Base URL

All API requests use the base URL:

https://app.boords.com/v1

Resource hierarchy

Boords organises content in a hierarchy:

Teams → Projects → Storyboards → Frames → Comments

Each team has projects, each project has storyboards, and each storyboard has frames. Comments are attached to individual frames.

Identifiers

Teams, projects, and storyboards use short text identifiers (like t3n4xk or p4k9az). Frames and comments use numeric IDs. You'll find these identifiers in API responses and can use them in subsequent requests.

Response format

All API responses use a consistent JSON envelope:

For a single resource:

{ "data": { "id": "p4k9az", "type": "project", "attributes": { ... } } }

For a list of resources:

{ "data": [ ... ], "meta": { "next_cursor": "..." } }

Pagination

List endpoints return results in pages. Use the limit parameter (up to 100, default 25) and the cursor parameter to step through results. When meta.next_cursor is present in the response, there are more results available — pass it as the cursor parameter in your next request.

Filtering

Most list endpoints support an updated_since parameter (ISO 8601 timestamp) to fetch only resources that have changed since a specific time. This is useful for building sync workflows.

Roles and permissions

What you can do via the API depends on your team role:

For more detail on team roles, see Team users and roles.

Common workflows

Import a script as a storyboard

You can create a storyboard with pre-populated frames in a single API call. Send a POST request to /v1/storyboards with a frames array, and Boords will create the storyboard and all frames at once.

Each frame in the array can include a label (which becomes the frame's reference field) and any number of custom fields like action, sound, or dialogue. Boords automatically generates field definitions from your data.

The response includes a field_key_map in the meta object, which maps your original field names to the generated field IDs — useful if you need to update those fields later.

For the full request and response format, see the Create Storyboard endpoint in the API reference.

Sync storyboard data to an external tool

To keep an external tool in sync with your Boords workspace:

1. Initial sync — List all projects, storyboards, and frames using the list endpoints. Use the cursor parameter to page through large collections.
2. Incremental updates — On subsequent syncs, use the updated_since parameter with the timestamp of your last sync. This returns only resources that have changed, keeping your requests efficient.
3. Webhook-driven sync — For real-time updates, set up webhooks to receive notifications whenever content changes. This avoids the need for polling entirely.

Use external images in your storyboards

The API lets you attach any image to a frame — whether it's a photo, a render from your 3D pipeline, or an AI-generated image from a tool like Midjourney or DALL·E.

Use the frame image endpoint to upload an image by URL or base64 data. Boords automatically processes the image to generate the right sizes for your storyboard's aspect ratio.

This means you can build fully automated pipelines: generate images with your tool of choice, then push them straight into your Boords storyboard via the API.

For the full request format, see the API documentation.

Rate limits

The API allows 120 requests per minute per token. Response headers tell you where you stand:

If you're building a sync workflow, use updated_since filtering and webhooks to reduce the number of requests you need to make.

Error handling

When something goes wrong, the API returns a consistent error format:

{
  "error": {
    "code": "forbidden",
    "message": "You do not have access to this resource."
  }
}

Common status codes:

For the full error reference, see the API documentation.