Filmsquare HelpDocs

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.

Updated 5 min read.md

On this page
  1. Authentication
  2. Getting a key
  3. A personal key (any role)
  4. A workspace API key (producer and up)
  5. Roles
  6. A first session
  7. Conventions
  8. Errors you will meet
  9. Related

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 URLhttps://app.filmsquare.ai/v1
FormatJSON over HTTPS
AuthAuthorization: Bearer <API key or session token>
Referencehttps://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) #

  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:

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 #

TopicRule
Field namesResponses 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 rowsLeft out of lists unless includeArchived=true
DeletingRows are archived (POST …/{id}/archive), not deleted. Versions, picks, sign-offs and costs are never changed
IdempotencyGeneration requests take an Idempotency-Key header (or idempotencyKey in the body): the same key returns the existing generation
MoneyCosts 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"]}}}
StatusCodeWhendetails
400validation_errorThe body, the query or a path parameter does not match the schemaThe list of validation issues
400bad_request, invalid_valueThe route refuses the request, or the database cannot read a value (such as a malformed id)—
400url_not_allowedA webhook or import URL is not a public http(s) address—
401unauthenticatedNo token, or a revoked or expired one—
402out_of_creditsNot enough credits free to spend for this takeneeded, available (credits)
402plan_limitThe plan does not include this: a final on Free, a second production, storage, seats, packs without a planlimit (final, productions, storage, seats, packs), plan
402budget_exceededThe episode's budget (budgetCredits on the episode) would be passedepisodeId, budgetCredits, spent, inFlight, needed (credits)
403insufficient_roleYour role is below the route's minimumrequired, actual
403not_a_signerYou are not a signer of this department—
403role_exceeds_callerAn invitation or key with a role above your own—
403not_a_personManaging keys with a personal key or a Claude connection—
404not_foundThe row does not exist, or you may not see it—
409gate_closedA final before the gate is openepisode_id, waiting_on (departments, or placement for a shot in no episode)
409changed_sinceYou signed off a version that is no longer the current oneversion (the current one)
409already_signed_offThe step is already signed off—
409element_version_frozenA reference added to a version a take already used—
409conflictA row with these values already exists—
422foreign_key_violation, check_violation, not_null_violationA referenced row does not exist (or is in another workspace), or a database rule refused the valuesconstraint, 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}}}

This page as Markdown: /docs/api/overview.md