6.0 API6.1 API overview and keys
API overview and keys
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.
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 |
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).
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) #
- In the studio, open the workspace menu at the top of the sidebar and choose Settings, then Claude.
- Choose Use a personal key instead, name it, and choose Create a personal key.
- 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:
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.
A first session #
# 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.
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 |
Errors you will meet #
Every error has the same shape:
{"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:
{"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
- OpenAPI reference
- What Claude can do: the same API through MCP