API
The studio, as an API.
Filmsquare's REST API is the same API the studio and a person's own Claude use, open to your scripts. JSON over HTTPS, one OpenAPI 3.1 document generated from the routes, a bearer key per person and workspace, and signed webhooks for when a take is ready.
curl -s "$FS/me" \
-H "Authorization: Bearer $FS_KEY"
WEBHOOK · POST /filmsquare/hook

S3-B5-05Seedance 2.5 · Final 1080p · 5 s · 105.30 credits · €5.27
BASE URL AND AUTH
One key, one role, one workspace
Every call sends Authorization: Bearer <token>: an API key starting with fsk_, or a signed-in session. Workspace routes carry the workspace in the path, /v1/workspaces/{ws}/….
https://app.filmsquare.ai/v1export FS=https://app.filmsquare.ai/v1
export FS_KEY=fsk_…
# Who you are, and your workspaces
curl -s "$FS/me" -H "Authorization: Bearer $FS_KEY"
# A draft take of a shot (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"}'ownerproducerdirectormakerreviewerviewer
Keys have no scopes. A key's power is its role in one workspace, never above the role of the person behind it.
| KEY | HOW |
|---|---|
| Personal key | Settings → Claude → Use a personal key instead. Your own role, shown once. |
| Workspace key | POST /workspaces/{ws}/api-keys with a name and a role, by a producer or owner. Shown once; only its hash is kept. |
| Revoke | POST /workspaces/{ws}/api-keys/{id}/revoke. The next call with it answers 401 api_key_revoked. |
OPENAPI 3.1
One name for a call and a job
GET https://app.filmsquare.ai/v1/openapi.json is public, OpenAPI 3.1, and generated from the routes themselves. Every route has an operationId, the same name Claude runs with run_action, so a call you script and a job you hand to Claude are one and the same. x-min-role names the lowest role that may call it. OpenAPI reference · MCP for Claude
"/workspaces/{ws}/shots/{id}/generations": {
"post": {
"operationId": "generateForShot",
"x-min-role": "maker",
…
}
}curl -s https://app.filmsquare.ai/v1/openapi.json | jq '.paths | keys | length'WEBHOOKS
Subscribe instead of polling
Producer and up; the whsec_ secret is shown once. Answer with a 2xx. On 5xx, 429 or a timeout Filmsquare retries with exponential backoff, from about 2 seconds up to 10 minutes between tries, up to 8 attempts. x-fs-delivery stays the same across retries. Webhooks
| EVENT | SENT WHEN |
|---|---|
generation.succeeded | A take finished rendering |
generation.failed | A render failed |
take.selected | A take was picked on a shot or scene |
asset_version.created | A render produced a new asset version |
["*"] | Every event |
curl -s -X POST "$FS/workspaces/$WS/webhooks" \
-H "Authorization: Bearer $FS_KEY" -H "content-type: application/json" \
-d '{"url": "https://example.com/filmsquare/hook", "events": ["generation.succeeded", "take.selected"]}'POST /filmsquare/hook
content-type: application/json
x-fs-signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with whsec_…>
x-fs-event: generation.succeeded
x-fs-delivery: generation.succeeded:9b2e…CONVENTIONS AND ERRORS
Every error has one shape
| TOPIC | RULE |
|---|---|
| Field names | Responses in snake_case, request bodies in camelCase. |
| Lists | Lists answer {"items": […], "next_cursor": "…"}. Pass cursor for the next page, limit up to 200, order asc or desc. |
| Idempotency | Take requests accept an Idempotency-Key header: the same key returns the same take. |
| Deleting | Rows are archived, never deleted. Versions, picks, sign-offs and costs never change. |
| Not visible | A row you may not see answers 404, the same as a row that does not exist. |
| STATUS | CODE | WHEN |
|---|---|---|
| 400 | validation_error | The body, query or a path parameter does not match the schema |
| 401 | unauthenticated | No token, or a revoked or expired one |
| 402 | out_of_credits | Not enough credits free for this take |
| 402 | plan_limit | The plan does not include it, such as a final on Free |
| 402 | budget_exceeded | The episode's budget in credits would be passed |
| 403 | insufficient_role | Your role is below the route's x-min-role |
| 403 | account_blocked | The account has been suspended; every request is refused |
| 404 | not_found | The row does not exist, or you may not see it |
| 409 | gate_closed | A final before the departments it waits on have signed off |
| 409 | workspace_paused | The workspace is paused: no new take or tool starts in it |
{"error": {"code": "gate_closed",
"message": "finals render once casting, sets, animatic are signed off",
"details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}GET /v1/pricing needs no key. It returns the price of a credit in euros, seat prices and the credits a seat brings, rollover, storage and credit packs: the numbers behind pricing.
curl -s https://app.filmsquare.ai/v1/pricingQuestions
Is the API the same one the studio uses?
Yes. The studio, a person's own Claude and your scripts call the same routes, with the same roles and the same rules.
Do API keys have scopes?
No. A key works in one workspace with one role, never above the role of the person who made it. The role is the scope.
Where is the reference?
The OpenAPI 3.1 document at https://app.filmsquare.ai/v1/openapi.json is public and generated from the routes, so it never falls behind them.
How do I know when a take is ready?
Subscribe a webhook to generation.succeeded. Deliveries are signed with x-fs-signature and retried on 5xx, 429 and timeouts.
Can a script render finals before sign-off?
No. A final before the gate is open answers 409 gate_closed, with the departments it is waiting on.
Is pricing readable without a key?
Yes. GET https://app.filmsquare.ai/v1/pricing is public and returns the credit price, seat prices, rollover and packs.