---
title: "OpenAPI 레퍼런스"
description: "Filmsquare OpenAPI 3.1 문서가 어디 있는지, 어떻게 읽는지(operation id, x-min-role, 태그), 영역별 API 지도를 알려 드려요."
url: https://www.filmsquare.ai/docs/ko/api/openapi/
lang: ko
section: api
updated: 2026-11-10
mcp: [find_actions]
---

# OpenAPI 레퍼런스

API의 전체 레퍼런스는 경로 자체에서 생성한 OpenAPI 3.1 문서 하나라서 항상 최신이에요.

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

공개 문서라서 토큰이 필요 없어요.

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

## 문서 읽는 법

| 필드 | 뜻 |
| --- | --- |
| `paths` | `/v1`로 시작하는 전체 경로. 호스트 `https://app.filmsquare.ai`와 함께 써요 |
| `operationId` | 경로마다 고정된 이름. 예: `generateForShot`. 같은 이름이 내 Claude가 `run_action`으로 실행하는 `action`이에요 |
| `summary` | 경로가 하는 일을 한 줄로. `find_actions`가 검색하는 대상이기도 해요 |
| `x-min-role` | 호출할 수 있는 가장 낮은 워크스페이스 역할: `viewer` … `owner`, `authenticated`(워크스페이스 없는, 로그인한 모든 호출자), `public` |
| `security` | `bearerAuth`(API 키 `fsk_…` 또는 세션 토큰), 공개 경로는 비어 있어요 |
| `tags` | API의 영역. 예: `shots`, `takes`, `elements`, `credits` |
| 오류 응답 | 모든 경로가 공통 `Error` 스키마를 나열해요: `{"error": {"code", "message", "details"}}` |

OpenAPI 툴(Postman, Insomnia, Bruno)에서 가져오거나, `openapi-typescript` 같은 걸로 타입이 있는 클라이언트를 생성할 수 있어요.

## 영역별 API

| 영역 | 예시(`operationId`) |
| --- | --- |
| 계정과 워크스페이스 | `getMe`, `listWorkspaces`, `createWorkspace`, `listMembers`, `createInvitation`, `setMemberScope` |
| 작품과 구조 | `listProjects`, `createProject`, `createEpisode`, `createScene`, `createShot`, `addShotToEpisode`, `getEpisodeStructure` |
| 시나리오와 브레이크다운 | `importScript`, `createScriptRevision`, `submitBreakdown`, `getEpisodeScript`, `listScriptRevisions` |
| 시나리오 태그 | `listScriptTags`, `autoTagScript`, `createScriptTag`, `updateScriptTag`, `archiveScriptTag`, `createElementFromScriptTag` |
| 팀과 컨펌 | `listProductionSteps`, `updateProductionStep`, `addProductionStep`, `getEpisodeSteps`, `requestSignoff`, `decideSignoff`, `listWaitingOnMe`, `getAnimaticReel` |
| 테이크와 생성 | `estimateShotGeneration`, `generateForShot`, `generateForScene`, `promoteGeneration`, `rerollTake`, `retryGeneration`, `cancelGeneration`, `listGenerations`, `getGeneration`, `selectTake`, `listTools`, `estimateTool`, `applyTool` |
| 요소 | `createElement`, `createQuickElement`, `forkElementVersion`, `generateForElement`, `acceptElementTake`, `searchHandles` |
| 의상 룩 | `listEpisodeLooks`, `createElementLook`, `updateElementLook`, `archiveElementLook`, `setLookScene` |
| 3D 동선 | `getEpisodeBlocking`, `pushBlockingFrame`, `pushBlockingFrames`, `listPrevisClips`, `addPrevisClips`, `countPrevisClip`, `archivePrevisClip`, `moveTake`, `moveAsset`, `findShotByCode`, `setShotExternalCodes`, `estimateBlockingStill`, `makeBlockingStill` |
| 파일 | `createUploadTicket`, `startMultipartUpload`, `signUploadPart`, `completeMultipartUpload`, `abortMultipartUpload`, `getMultipartUpload`, `completeUpload`, `importFromUrls`, `getAssetVersionUrl`, `getAssetVersionLineage`, `exportEpisodeManifest` |
| 리뷰 | `listThreads`, `createThread`, `addThreadMessage`, `carryThreadForward`, `getInbox`, `markInboxRead`, `getActivity` |
| 편집 버전 | `listEdits`, `createEdit`, `getEdit`, `addEditVersion` |
| 편집본 | `getEpisodeCut`, `setCutClipTrim`, `reorderEpisodeCut`, `reviseTake`, `createCutExport`, `listCutExports` |
| 연결과 라우팅 | `getContinuitySheet`, `scanContinuity`, `recordContinuityCheck`, `getModelAcceptance` |
| 폴더와 캔버스 | `listFolders`, `createFolder`, `addFolderItems`, `getCanvas`, `applyCanvasOps`, `runCanvasNode` |
| 브리프와 작업자 | `createBrief`, `offerAssignment`, `submitDelivery`, `markAssignmentPaid`, `getMakersOverview` |
| 비용과 크레딧 | `getEpisodeCosts`, `getCredits`, `listCreditEntries`, `getPricing`, `getPlan`, `listInvoices` |
| 연동 | `createApiKey`, `revokeApiKey`, `createWebhook`, `updateWebhook`, `deleteWebhook` |

`GET /v1/pricing`(`getPricing`)은 공개예요. 크레딧 가격, 요금제, 팩을 실시간으로 보여 줘요.

## 문서에 없는 것

- MCP 엔드포인트 `POST /v1/mcp`. [Claude 연결](https://www.filmsquare.ai/docs/ko/claude/connect/)을 보세요.
- Claude 연결용 OAuth 엔드포인트(`/oauth/*`, `/.well-known/oauth-*`).
- 캔버스와 접속 표시용 실시간 소켓(`/v1/realtime/…`). `createCanvasSession`이나 `createProjectPresenceSession`이 주는 단기 티켓으로 열려요.

## 말로 검색하기

`find_actions`는 같은 카탈로그를 현장 용어(“pick take”, “notes”, “render”)로 검색해요. 문서를 읽지 않고도 내 Claude에서 쓸 수 있어요. [Claude가 할 수 있는 일](https://www.filmsquare.ai/docs/ko/claude/tools/)을 보세요.

## 관련 문서

- [API 개요와 키](https://www.filmsquare.ai/docs/ko/api/overview/)
- [웹훅](https://www.filmsquare.ai/docs/ko/api/webhooks/)
