---
title: "OpenAPI reference"
description: "Where the Filmsquare OpenAPI 3.1 document lives, how to read it (operation ids, x-min-role, tags), and a map of the API by area."
url: https://www.filmsquare.ai/docs/api/openapi/
lang: en
section: api
updated: 2026-11-10
mcp: [find_actions]
---

# OpenAPI reference

The full reference of the API is one OpenAPI 3.1 document, generated from the routes themselves, so it is never
out of date:

```
https://app.filmsquare.ai/v1/openapi.json
```

It is public: no token needed.

```bash
curl -s https://app.filmsquare.ai/v1/openapi.json | jq '.paths | keys | length'
```

## Reading the document

| Field | Meaning |
| --- | --- |
| `paths` | Full paths, starting with `/v1`. Use them with the host `https://app.filmsquare.ai` |
| `operationId` | A stable name per route, such as `generateForShot`. The same name is the `action` your Claude runs with `run_action` |
| `summary` | One line on what the route does. It is also what `find_actions` searches |
| `x-min-role` | The lowest workspace role that may call it: `viewer` … `owner`, `authenticated` (any signed-in caller, no workspace) or `public` |
| `security` | `bearerAuth` (an API key `fsk_…` or a session token), or empty for public routes |
| `tags` | The area of the API, such as `shots`, `takes`, `elements`, `credits` |
| Error responses | Every route lists the shared `Error` schema: `{"error": {"code", "message", "details"}}` |

Import it in any OpenAPI tool (Postman, Insomnia, Bruno) or generate a typed client from it, for example with
`openapi-typescript`.

## The API by area

| Area | Examples (`operationId`) |
| --- | --- |
| Account and workspaces | `getMe`, `listWorkspaces`, `createWorkspace`, `listMembers`, `createInvitation`, `setMemberScope` |
| Productions and structure | `listProjects`, `createProject`, `createEpisode`, `createScene`, `createShot`, `addShotToEpisode`, `getEpisodeStructure` |
| Script and breakdown | `importScript`, `createScriptRevision`, `submitBreakdown`, `getEpisodeScript`, `listScriptRevisions` |
| Script tags | `listScriptTags`, `autoTagScript`, `createScriptTag`, `updateScriptTag`, `archiveScriptTag`, `createElementFromScriptTag` |
| Departments and sign-off | `listProductionSteps`, `updateProductionStep`, `addProductionStep`, `getEpisodeSteps`, `requestSignoff`, `decideSignoff`, `listWaitingOnMe`, `getAnimaticReel` |
| Takes and generations | `estimateShotGeneration`, `generateForShot`, `generateForScene`, `promoteGeneration`, `rerollTake`, `retryGeneration`, `cancelGeneration`, `listGenerations`, `getGeneration`, `selectTake`, `listTools`, `estimateTool`, `applyTool` |
| Elements | `createElement`, `createQuickElement`, `forkElementVersion`, `generateForElement`, `acceptElementTake`, `searchHandles` |
| Costume looks | `listEpisodeLooks`, `createElementLook`, `updateElementLook`, `archiveElementLook`, `setLookScene` |
| 3D blocking | `getEpisodeBlocking`, `pushBlockingFrame`, `pushBlockingFrames`, `listPrevisClips`, `addPrevisClips`, `countPrevisClip`, `archivePrevisClip`, `moveTake`, `moveAsset`, `findShotByCode`, `setShotExternalCodes`, `estimateBlockingStill`, `makeBlockingStill` |
| Files | `createUploadTicket`, `startMultipartUpload`, `signUploadPart`, `completeMultipartUpload`, `abortMultipartUpload`, `getMultipartUpload`, `completeUpload`, `importFromUrls`, `getAssetVersionUrl`, `getAssetVersionLineage`, `exportEpisodeManifest` |
| Review | `listThreads`, `createThread`, `addThreadMessage`, `carryThreadForward`, `getInbox`, `markInboxRead`, `getActivity` |
| Edits | `listEdits`, `createEdit`, `getEdit`, `addEditVersion` |
| The cut | `getEpisodeCut`, `setCutClipTrim`, `reorderEpisodeCut`, `reviseTake`, `createCutExport`, `listCutExports` |
| Continuity and routing | `getContinuitySheet`, `scanContinuity`, `recordContinuityCheck`, `getModelAcceptance` |
| Folders and canvases | `listFolders`, `createFolder`, `addFolderItems`, `getCanvas`, `applyCanvasOps`, `runCanvasNode` |
| Briefs and makers | `createBrief`, `offerAssignment`, `submitDelivery`, `markAssignmentPaid`, `getMakersOverview` |
| Costs and credits | `getEpisodeCosts`, `getCredits`, `listCreditEntries`, `getPricing`, `getPlan`, `listInvoices` |
| Integration | `createApiKey`, `revokeApiKey`, `createWebhook`, `updateWebhook`, `deleteWebhook` |

`GET /v1/pricing` (`getPricing`) is public: the credit price, the plans and the packs, live.

## What is not in the document

- The MCP endpoint `POST /v1/mcp`. See [Connect Claude](https://www.filmsquare.ai/docs/claude/connect/).
- The OAuth endpoints for Claude connections (`/oauth/*`, `/.well-known/oauth-*`).
- The realtime sockets for canvases and presence (`/v1/realtime/…`); they open with a short-lived ticket from
  `createCanvasSession` or `createProjectPresenceSession`.

## Search it in words

`find_actions` searches the same catalogue in set language ("pick take", "notes", "render"). You can use it from
your own Claude without reading the document at all. See [What Claude can do](https://www.filmsquare.ai/docs/claude/tools/).

## Related

- [API overview and keys](https://www.filmsquare.ai/docs/api/overview/)
- [Webhooks](https://www.filmsquare.ai/docs/api/webhooks/)
