---
title: "Riferimento OpenAPI"
description: "Dove sta il documento OpenAPI 3.1 di Filmsquare, come leggerlo (operation id, x-min-role, tag) e una mappa dell'API per area."
url: https://www.filmsquare.ai/docs/it/api/openapi/
lang: it
section: api
updated: 2026-11-10
mcp: [find_actions]
---

# Riferimento OpenAPI

Il riferimento completo dell'API è un unico documento OpenAPI 3.1, generato dalle rotte stesse, quindi non è mai
indietro:

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

È pubblico: non serve nessun token.

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

## Leggere il documento

| Campo | Significato |
| --- | --- |
| `paths` | Percorsi completi, che iniziano con `/v1`. Usali con l'host `https://app.filmsquare.ai` |
| `operationId` | Un nome stabile per rotta, come `generateForShot`. Lo stesso nome è l'`action` che il tuo Claude esegue con `run_action` |
| `summary` | Una riga su cosa fa la rotta. È anche ciò che cerca `find_actions` |
| `x-min-role` | Il ruolo più basso dello spazio di lavoro che può chiamarla: `viewer` … `owner`, `authenticated` (qualsiasi chiamante con l'accesso effettuato, senza spazio di lavoro) o `public` |
| `security` | `bearerAuth` (una chiave API `fsk_…` o un token di sessione), oppure vuoto per le rotte pubbliche |
| `tags` | L'area dell'API, come `shots`, `takes`, `elements`, `credits` |
| Risposte di errore | Ogni rotta elenca lo schema `Error` condiviso: `{"error": {"code", "message", "details"}}` |

Importalo in qualsiasi strumento OpenAPI (Postman, Insomnia, Bruno) oppure genera da esso un client tipizzato, per
esempio con `openapi-typescript`.

## L'API per area

| Area | Esempi (`operationId`) |
| --- | --- |
| Account e spazi di lavoro | `getMe`, `listWorkspaces`, `createWorkspace`, `listMembers`, `createInvitation`, `setMemberScope` |
| Produzioni e struttura | `listProjects`, `createProject`, `createEpisode`, `createScene`, `createShot`, `addShotToEpisode`, `getEpisodeStructure` |
| Sceneggiatura e spoglio | `importScript`, `createScriptRevision`, `submitBreakdown`, `getEpisodeScript`, `listScriptRevisions` |
| Tag della sceneggiatura | `listScriptTags`, `autoTagScript`, `createScriptTag`, `updateScriptTag`, `archiveScriptTag`, `createElementFromScriptTag` |
| Reparti e approvazione | `listProductionSteps`, `updateProductionStep`, `addProductionStep`, `getEpisodeSteps`, `requestSignoff`, `decideSignoff`, `listWaitingOnMe`, `getAnimaticReel` |
| Ciak e generazioni | `estimateShotGeneration`, `generateForShot`, `generateForScene`, `promoteGeneration`, `rerollTake`, `retryGeneration`, `cancelGeneration`, `listGenerations`, `getGeneration`, `selectTake`, `listTools`, `estimateTool`, `applyTool` |
| Elementi | `createElement`, `createQuickElement`, `forkElementVersion`, `generateForElement`, `acceptElementTake`, `searchHandles` |
| Look dei costumi | `listEpisodeLooks`, `createElementLook`, `updateElementLook`, `archiveElementLook`, `setLookScene` |
| Blocking 3D | `getEpisodeBlocking`, `pushBlockingFrame`, `pushBlockingFrames`, `listPrevisClips`, `addPrevisClips`, `countPrevisClip`, `archivePrevisClip`, `moveTake`, `moveAsset`, `findShotByCode`, `setShotExternalCodes`, `estimateBlockingStill`, `makeBlockingStill` |
| File | `createUploadTicket`, `startMultipartUpload`, `signUploadPart`, `completeMultipartUpload`, `abortMultipartUpload`, `getMultipartUpload`, `completeUpload`, `importFromUrls`, `getAssetVersionUrl`, `getAssetVersionLineage`, `exportEpisodeManifest` |
| Revisione | `listThreads`, `createThread`, `addThreadMessage`, `carryThreadForward`, `getInbox`, `markInboxRead`, `getActivity` |
| Versioni di montaggio | `listEdits`, `createEdit`, `getEdit`, `addEditVersion` |
| Il montaggio | `getEpisodeCut`, `setCutClipTrim`, `reorderEpisodeCut`, `reviseTake`, `createCutExport`, `listCutExports` |
| Continuità e routing | `getContinuitySheet`, `scanContinuity`, `recordContinuityCheck`, `getModelAcceptance` |
| Cartelle e canvas | `listFolders`, `createFolder`, `addFolderItems`, `getCanvas`, `applyCanvasOps`, `runCanvasNode` |
| Brief e maker | `createBrief`, `offerAssignment`, `submitDelivery`, `markAssignmentPaid`, `getMakersOverview` |
| Costi e crediti | `getEpisodeCosts`, `getCredits`, `listCreditEntries`, `getPricing`, `getPlan`, `listInvoices` |
| Integrazione | `createApiKey`, `revokeApiKey`, `createWebhook`, `updateWebhook`, `deleteWebhook` |

`GET /v1/pricing` (`getPricing`) è pubblico: il prezzo del credito, i piani e i pacchetti, in tempo reale.

## Cosa non c'è nel documento

- L'endpoint MCP `POST /v1/mcp`. Vedi [Collega Claude](https://www.filmsquare.ai/docs/it/claude/connect/).
- Gli endpoint OAuth per le connessioni Claude (`/oauth/*`, `/.well-known/oauth-*`).
- I socket realtime per canvas e presenza (`/v1/realtime/…`); si aprono con un ticket di breve durata da
  `createCanvasSession` o `createProjectPresenceSession`.

## Cercalo a parole

`find_actions` cerca nello stesso catalogo con il linguaggio del set («pick take», «notes», «render»). Puoi usarlo
dal tuo Claude senza leggere affatto il documento. Vedi [Cosa può fare Claude](https://www.filmsquare.ai/docs/it/claude/tools/).

## Correlati

- [Panoramica dell'API e chiavi](https://www.filmsquare.ai/docs/it/api/overview/)
- [Webhook](https://www.filmsquare.ai/docs/it/api/webhooks/)
