---
title: "API overview and keys"
description: "The Filmsquare REST API: base URL, authentication with API keys or a session, how to make a key, conventions, and the errors you will meet."
url: https://www.filmsquare.ai/docs/api/overview/
lang: en
section: api
updated: 2026-11-10
---

# API overview and keys

Everything the studio does goes through one REST API, and you can use it too: the app, your own Claude and your
scripts all call the same routes, with the same roles and the same rules.

| | |
| --- | --- |
| Base URL | `https://app.filmsquare.ai/v1` |
| Format | JSON over HTTPS |
| Auth | `Authorization: Bearer <API key or session token>` |
| Reference | `https://app.filmsquare.ai/v1/openapi.json` (OpenAPI 3.1, public). See [OpenAPI reference](https://www.filmsquare.ai/docs/api/openapi/) |

## Authentication

Every route except a few public ones (`GET /v1/pricing`, `POST /v1/signup`, the webhook receivers) needs a bearer
token:

- **An API key**, starting with `fsk_`. A key belongs to one person (or agent user) in **one** workspace, and acts
  with the key's role, never more than that person's current role.
- **A session token** of a signed-in person (what the web app sends).

```bash
export FS=https://app.filmsquare.ai/v1
export FS_KEY=fsk_…   # your key

curl -s "$FS/me" -H "Authorization: Bearer $FS_KEY"
```

`GET /me` returns who you are, whether you came in with a key, and your workspaces. Every workspace route has the
workspace id in its path: `/v1/workspaces/{ws}/…`.

## Getting a key

### A personal key (any role)

1. In the studio, open the workspace menu at the top of the sidebar and choose **Settings**, then **Claude**.
2. Choose **Use a personal key instead**, name it, and choose **Create a personal key**.
3. Copy the key. It is shown once.

A personal key has your own role in that workspace. It is made for Claude Code, but works for any API call your role
allows, except managing keys.

### A workspace API key (producer and up)

A producer or owner, signed in, can make keys with a chosen role through the API:

```bash
curl -s -X POST "$FS/workspaces/$WS/api-keys" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name": "Render farm sync", "role": "maker"}'
```

The answer holds the full `key` once; Filmsquare keeps only its hash. A key's role can never be above your own. With
`userId` you can make a key for an agent user who is a member of the workspace.

`GET /workspaces/{ws}/api-keys` lists keys (prefix only); `POST /workspaces/{ws}/api-keys/{id}/revoke` revokes one.
Keys cannot make keys: these routes need a signed-in person or a workspace key, and refuse a personal key or a
Claude connection with `403 not_a_person`.

## Roles

Each route has a minimum role: `owner` > `producer` > `director` > `maker` > `reviewer` > `viewer`. A call below it
gets `403 insufficient_role` with `{"required": "director", "actual": "maker"}`. A row you may not see answers `404`,
the same as a row that does not exist. See [Crew, roles and access](https://www.filmsquare.ai/docs/working-together/crew-and-roles/).

## A first session

```bash
# Your productions
curl -s "$FS/workspaces/$WS/projects" -H "Authorization: Bearer $FS_KEY"

# An episode's steps and the finals gate
curl -s "$FS/workspaces/$WS/episodes/$EP/steps" -H "Authorization: Bearer $FS_KEY"

# Price a draft of a shot before making it
curl -s -X POST "$FS/workspaces/$WS/shots/$SHOT/estimate" \
  -H "Authorization: Bearer $FS_KEY" -H "content-type: application/json" \
  -d '{"kind": "video", "tier": "draft"}'

# Make it (the same Idempotency-Key never makes it twice)
curl -s -X POST "$FS/workspaces/$WS/shots/$SHOT/generations" \
  -H "Authorization: Bearer $FS_KEY" -H "content-type: application/json" \
  -H "Idempotency-Key: shot-$SHOT-draft-1" \
  -d '{"kind": "video", "tier": "draft"}'

# Follow it
curl -s "$FS/workspaces/$WS/generations?shotId=$SHOT&order=desc&limit=5" \
  -H "Authorization: Bearer $FS_KEY"
```

`kind` is `keyframe`, `video`, `dialogue`, `sfx` or `music`; `tier` is `draft` or `final`. No connected model
makes `sfx` or `music` yet: those takes come in as uploads (`createUploadTicket`, then `completeUpload` with a
target layer). Leave out `modelKey` and
Filmsquare routes to the capable model with the lowest cost per accepted take. Rather than polling, subscribe to
[webhooks](https://www.filmsquare.ai/docs/api/webhooks/).

## Conventions

| Topic | Rule |
| --- | --- |
| Field names | Responses in `snake_case`, request bodies in `camelCase` |
| Lists | `{"items": […], "next_cursor": "…"}`. Pass `cursor` for the next page; `limit` up to 200; `order` `asc` or `desc` |
| Archived rows | Left out of lists unless `includeArchived=true` |
| Deleting | Rows are archived (`POST …/{id}/archive`), not deleted. Versions, picks, sign-offs and costs are never changed |
| Idempotency | Generation requests take an `Idempotency-Key` header (or `idempotencyKey` in the body): the same key returns the existing generation |
| Money | Costs are in credits, each at the rate the work started on; what a credit costs in euros is in `GET /v1/pricing` and [Credits and what things cost](https://www.filmsquare.ai/docs/concepts/credits-and-costs/) |

## Errors you will meet

Every error has the same shape:

```json
{"error": {"code": "gate_closed", "message": "finals render once casting, sets, animatic are signed off",
  "details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}
```

| Status | Code | When | `details` |
| --- | --- | --- | --- |
| 400 | `validation_error` | The body, the query or a path parameter does not match the schema | The list of validation issues |
| 400 | `bad_request`, `invalid_value` | The route refuses the request, or the database cannot read a value (such as a malformed id) | — |
| 400 | `url_not_allowed` | A webhook or import URL is not a public http(s) address | — |
| 401 | `unauthenticated` | No token, or a revoked or expired one | — |
| 402 | `out_of_credits` | Not enough credits free to spend for this take | `needed`, `available` (credits) |
| 402 | `plan_limit` | The plan does not include this: a final on Free, a second production, storage, seats, packs without a plan | `limit` (`final`, `productions`, `storage`, `seats`, `packs`), `plan` |
| 402 | `budget_exceeded` | The episode's budget (`budgetCredits` on the episode) would be passed | `episodeId`, `budgetCredits`, `spent`, `inFlight`, `needed` (credits) |
| 403 | `insufficient_role` | Your role is below the route's minimum | `required`, `actual` |
| 403 | `not_a_signer` | You are not a signer of this department | — |
| 403 | `role_exceeds_caller` | An invitation or key with a role above your own | — |
| 403 | `not_a_person` | Managing keys with a personal key or a Claude connection | — |
| 404 | `not_found` | The row does not exist, or you may not see it | — |
| 409 | `gate_closed` | A final before the gate is open | `episode_id`, `waiting_on` (departments, or `placement` for a shot in no episode) |
| 409 | `changed_since` | You signed off a version that is no longer the current one | `version` (the current one) |
| 409 | `already_signed_off` | The step is already signed off | — |
| 409 | `element_version_frozen` | A reference added to a version a take already used | — |
| 409 | `conflict` | A row with these values already exists | — |
| 422 | `foreign_key_violation`, `check_violation`, `not_null_violation` | A referenced row does not exist (or is in another workspace), or a database rule refused the values | `constraint`, `table`, `detail` |

`402 out_of_credits` looks like this:

```json
{"error": {"code": "out_of_credits", "message": "this needs 14 credits and 3 are free to spend",
  "details": {"workspaceId": "…", "needed": 13.35, "available": 3.2}}}
```

## Related

- [Webhooks](https://www.filmsquare.ai/docs/api/webhooks/)
- [OpenAPI reference](https://www.filmsquare.ai/docs/api/openapi/)
- [What Claude can do](https://www.filmsquare.ai/docs/claude/tools/): the same API through MCP
