---
title: "Referência OpenAPI"
description: "Onde fica o documento OpenAPI 3.1 do Filmsquare, como lê-lo (operation ids, x-min-role, tags) e um mapa da API por área."
url: https://www.filmsquare.ai/docs/pt-br/api/openapi/
lang: pt-BR
section: api
updated: 2026-11-10
mcp: [find_actions]
---

# Referência OpenAPI

A referência completa da API é um só documento OpenAPI 3.1, gerado das próprias rotas, então nunca fica
desatualizado:

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

Ele é público: não precisa de token.

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

## Ler o documento

| Campo | Significado |
| --- | --- |
| `paths` | Caminhos completos, começando com `/v1`. Use-os com o host `https://app.filmsquare.ai` |
| `operationId` | Um nome estável por rota, como `generateForShot`. O mesmo nome é a `action` que o seu Claude executa com `run_action` |
| `summary` | Uma linha sobre o que a rota faz. É também o que o `find_actions` busca |
| `x-min-role` | A função mais baixa do espaço de trabalho que pode chamá-la: `viewer` … `owner`, `authenticated` (qualquer chamador conectado, sem espaço de trabalho) ou `public` |
| `security` | `bearerAuth` (uma chave de API `fsk_…` ou um token de sessão), ou vazio para rotas públicas |
| `tags` | A área da API, como `shots`, `takes`, `elements`, `credits` |
| Respostas de erro | Toda rota lista o schema compartilhado `Error`: `{"error": {"code", "message", "details"}}` |

Importe-o em qualquer ferramenta OpenAPI (Postman, Insomnia, Bruno) ou gere um cliente tipado a partir dele, por exemplo com
`openapi-typescript`.

## A API por área

| Área | Exemplos (`operationId`) |
| --- | --- |
| Conta e espaços de trabalho | `getMe`, `listWorkspaces`, `createWorkspace`, `listMembers`, `createInvitation`, `setMemberScope` |
| Produções e estrutura | `listProjects`, `createProject`, `createEpisode`, `createScene`, `createShot`, `addShotToEpisode`, `getEpisodeStructure` |
| Roteiro e decupagem | `importScript`, `createScriptRevision`, `submitBreakdown`, `getEpisodeScript`, `listScriptRevisions` |
| Marcações do roteiro | `listScriptTags`, `autoTagScript`, `createScriptTag`, `updateScriptTag`, `archiveScriptTag`, `createElementFromScriptTag` |
| Departamentos e aprovação | `listProductionSteps`, `updateProductionStep`, `addProductionStep`, `getEpisodeSteps`, `requestSignoff`, `decideSignoff`, `listWaitingOnMe`, `getAnimaticReel` |
| Takes e gerações | `estimateShotGeneration`, `generateForShot`, `generateForScene`, `promoteGeneration`, `rerollTake`, `retryGeneration`, `cancelGeneration`, `listGenerations`, `getGeneration`, `selectTake`, `listTools`, `estimateTool`, `applyTool` |
| Elementos | `createElement`, `createQuickElement`, `forkElementVersion`, `generateForElement`, `acceptElementTake`, `searchHandles` |
| Looks de figurino | `listEpisodeLooks`, `createElementLook`, `updateElementLook`, `archiveElementLook`, `setLookScene` |
| Marcação em 3D | `getEpisodeBlocking`, `pushBlockingFrame`, `pushBlockingFrames`, `listPrevisClips`, `addPrevisClips`, `countPrevisClip`, `archivePrevisClip`, `moveTake`, `moveAsset`, `findShotByCode`, `setShotExternalCodes`, `estimateBlockingStill`, `makeBlockingStill` |
| Arquivos | `createUploadTicket`, `startMultipartUpload`, `signUploadPart`, `completeMultipartUpload`, `abortMultipartUpload`, `getMultipartUpload`, `completeUpload`, `importFromUrls`, `getAssetVersionUrl`, `getAssetVersionLineage`, `exportEpisodeManifest` |
| Revisão | `listThreads`, `createThread`, `addThreadMessage`, `carryThreadForward`, `getInbox`, `markInboxRead`, `getActivity` |
| Montagens | `listEdits`, `createEdit`, `getEdit`, `addEditVersion` |
| O corte | `getEpisodeCut`, `setCutClipTrim`, `reorderEpisodeCut`, `reviseTake`, `createCutExport`, `listCutExports` |
| Continuidade e roteamento | `getContinuitySheet`, `scanContinuity`, `recordContinuityCheck`, `getModelAcceptance` |
| Pastas e canvases | `listFolders`, `createFolder`, `addFolderItems`, `getCanvas`, `applyCanvasOps`, `runCanvasNode` |
| Briefings e artistas | `createBrief`, `offerAssignment`, `submitDelivery`, `markAssignmentPaid`, `getMakersOverview` |
| Custos e créditos | `getEpisodeCosts`, `getCredits`, `listCreditEntries`, `getPricing`, `getPlan`, `listInvoices` |
| Integração | `createApiKey`, `revokeApiKey`, `createWebhook`, `updateWebhook`, `deleteWebhook` |

`GET /v1/pricing` (`getPricing`) é público: o preço do crédito, as assinaturas e os pacotes, ao vivo.

## O que não está no documento

- O endpoint MCP `POST /v1/mcp`. Veja [Conectar o Claude](https://www.filmsquare.ai/docs/pt-br/claude/connect/).
- Os endpoints OAuth das conexões do Claude (`/oauth/*`, `/.well-known/oauth-*`).
- Os sockets em tempo real de canvases e presença (`/v1/realtime/…`); eles abrem com um ticket de curta duração de
  `createCanvasSession` ou `createProjectPresenceSession`.

## Busque em palavras

`find_actions` busca o mesmo catálogo em linguagem de set ("pick take", "notes", "render"). Você pode usá-lo pelo
seu próprio Claude sem ler o documento. Veja [O que o Claude faz](https://www.filmsquare.ai/docs/pt-br/claude/tools/).

## Relacionados

- [Visão geral da API e chaves](https://www.filmsquare.ai/docs/pt-br/api/overview/)
- [Webhooks](https://www.filmsquare.ai/docs/pt-br/api/webhooks/)
