Filmsquare

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"
Send a requestGET /v1/me

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}/….

BASE URL
https://app.filmsquare.ai/v1
FIRST CALLS
export 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"}'
  1. owner
  2. producer
  3. director
  4. maker
  5. reviewer
  6. viewer

Keys have no scopes. A key's power is its role in one workspace, never above the role of the person behind it.

KEYHOW
Personal keySettings → Claude → Use a personal key instead. Your own role, shown once.
Workspace keyPOST /workspaces/{ws}/api-keys with a name and a role, by a producer or owner. Shown once; only its hash is kept.
RevokePOST /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

ONE OPERATION
"/workspaces/{ws}/shots/{id}/generations": {
  "post": {
    "operationId": "generateForShot",
    "x-min-role": "maker",
    …
  }
}
TERMINAL
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

EVENTSENT WHEN
generation.succeededA take finished rendering
generation.failedA render failed
take.selectedA take was picked on a shot or scene
asset_version.createdA render produced a new asset version
["*"]Every event
SUBSCRIBE
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"]}'
A DELIVERY
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

TOPICRULE
Field namesResponses in snake_case, request bodies in camelCase.
ListsLists answer {"items": […], "next_cursor": "…"}. Pass cursor for the next page, limit up to 200, order asc or desc.
IdempotencyTake requests accept an Idempotency-Key header: the same key returns the same take.
DeletingRows are archived, never deleted. Versions, picks, sign-offs and costs never change.
Not visibleA row you may not see answers 404, the same as a row that does not exist.
STATUSCODEWHEN
400validation_errorThe body, query or a path parameter does not match the schema
401unauthenticatedNo token, or a revoked or expired one
402out_of_creditsNot enough credits free for this take
402plan_limitThe plan does not include it, such as a final on Free
402budget_exceededThe episode's budget in credits would be passed
403insufficient_roleYour role is below the route's x-min-role
403account_blockedThe account has been suspended; every request is refused
404not_foundThe row does not exist, or you may not see it
409gate_closedA final before the departments it waits on have signed off
409workspace_pausedThe workspace is paused: no new take or tool starts in it
EVERY ERROR HAS ONE SHAPE
{"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.

TERMINAL
curl -s https://app.filmsquare.ai/v1/pricing

Questions

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.