Boords API

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

See also: API and webhooks, an overview of what teams automate with Boords.

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
• Create and edit scripts. Create, update and duplicate scripts, and save versions
• 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
• Manage the Asset Library. Upload, organise and delete the team's shared images and folders (see Asset Library)
• Set up webhooks. Get notified when a storyboard or script changes status, or when work made through the API changes (see Webhooks)

Using Claude or ChatGPT? You don't need an API key. Connect Boords to your AI app instead and sign in with your Boords account. The API is for your own scripts, pipelines and integrations.

Prerequisites

To use the Boords API, you'll need:

• A paid Boords plan (see pricing)
• An API key created in your team settings

Creating an API key

API keys are managed in Settings → Team → API. You'll need an Owner or Admin role to create them.

To create a key:

1. Go to Settings → Team → API
2. Click Create API key
3. Give your key a name (e.g. "Zapier", "CI Pipeline", "Custom Integration")
4. Optionally, set an expiry date. Leave it blank for a key that doesn't expire
5. Copy the key. It's only shown once

API keys start with bap_ and are tied to your user account. Any actions performed with your key use your permissions and appear as your activity.

Key security

• Store keys securely. Treat them like passwords
• Use descriptive names. Name each key after what it's for
• Replace keys when you need to. Keys can't be rotated. Create a new key, switch your integration to it, then delete the old one
• Delete unused keys. If you no longer need a key, delete it from the same settings page

Authentication

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

X-API-KEY: bap_your_key_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 scripts, and each storyboard has frames. Comments are attached to individual frames. Library assets and their folders hang directly off the team at /v1/teams/{team_id}/library_assets and /v1/teams/{team_id}/library_asset_folders.

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, which is useful if you need to update those fields later.

Fields generated this way are text fields. To use date, dropdown or checkbox fields, create the storyboard with typed frame_fields first and then add the frames, or change a field's type later with a storyboard update. Changing a text field's type through the API doesn't convert its values. Text that isn't a valid option, date or checkbox value is hidden until the field is switched back to text, so send those values again after the switch (as option labels for a dropdown). In the Boords editor, Convert to Dropdown turns existing text into options.

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

Work with date, dropdown and checkbox fields

Each field in a storyboard's frame_fields has a type: text, date, dropdown or checkbox. Dropdown fields also include multi_select and their options, each with an id, label and color. Built-in fields such as reference are always text.

When you write a frame's field_data:

• Send dates as YYYY-MM-DD.
• Send a dropdown option by its label (any case) or its id. For a multi-select dropdown, send an array or a comma-separated list.
• Send checkboxes as true or false.

An unknown dropdown option returns a 422 that lists the valid options. Writing a value never creates a new option.

Frame responses also include field_display, readable text for date, dropdown and checkbox fields, such as 3 Nov 2026, Wide or Yes. frame.* webhooks carry it too.

For the field types and value formats, see the API reference.

Work with statuses

Storyboards and scripts share one set of statuses. Your team sets them up in Team settings, and each one belongs to one of five categories:

Storyboard and script responses include status, the category, and custom_status, your team's status as { "id", "name" }.

To change a status with PATCH /v1/storyboards/{id}, POST /v1/scripts or PATCH /v1/scripts/{id}:

• Send status to move the item to that category's default status. You can send the value, the label (In review) or an older label (Review Needed). Send null, "" or "draft" for Draft.
• Send status_id to pick one of your team's statuses. Get the ids from GET /v1/teams/{team_id}/statuses. An id that isn't one of the team's statuses returns a 422. If you send status too, it must name the same category.
• If you send an item's current category, it keeps its team status. Sending a GET response back unchanged never moves it.

New versions start at Draft. Duplicates keep their status.

To see status history, read the team activity feed with GET /v1/teams/{team_id}/events. Status change events include status_change, with the status the item moved from and to, each as { "category", "id", "name" }. The name is the status name at the time of the change, so later renames don't alter it. status_change is null for other events and for status changes made before custom statuses.

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. Status changes as they happen. Set up webhooks to hear straight away when a storyboard or script changes status, for example when a storyboard moves to Approved. Storyboards send storyboard.updated and scripts send script.updated. Most edits made in the web app don't send webhooks, so keep using updated_since to pick those up.

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 API key. Response headers tell you where you stand:

If you receive a 429 response, wait until the time in X-RateLimit-Reset before retrying.

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.