---
title: "API-overzicht en sleutels"
description: "De Filmsquare REST API: basis-URL, authenticatie met API-sleutels of een sessie, hoe je een sleutel maakt, conventies en de fouten die je tegenkomt."
url: https://www.filmsquare.ai/docs/nl/api/overview/
lang: nl
section: api
updated: 2026-11-10
---

# API-overzicht en sleutels

Alles wat de studio doet, gaat via één REST API, en jij kunt hem ook gebruiken: de app, je eigen Claude en je
scripts roepen dezelfde routes aan, met dezelfde rollen en dezelfde regels.

| | |
| --- | --- |
| Basis-URL | `https://app.filmsquare.ai/v1` |
| Formaat | JSON over HTTPS |
| Auth | `Authorization: Bearer <API key or session token>` |
| Referentie | `https://app.filmsquare.ai/v1/openapi.json` (OpenAPI 3.1, openbaar). Zie [OpenAPI-referentie](https://www.filmsquare.ai/docs/nl/api/openapi/) |

## Authenticatie

Elke route behalve een paar openbare (`GET /v1/pricing`, `POST /v1/signup`, de webhookontvangers) vraagt een bearer
token:

- **Een API-sleutel**, beginnend met `fsk_`. Een sleutel hoort bij één persoon (of agentgebruiker) in **één** workspace en handelt
  met de rol van de sleutel, nooit meer dan de huidige rol van die persoon.
- **Een sessietoken** van een ingelogd persoon (wat de webapp stuurt).

```bash
export FS=https://app.filmsquare.ai/v1
export FS_KEY=fsk_…   # your key

curl -s "$FS/me" -H "Authorization: Bearer $FS_KEY"
```

`GET /me` geeft terug wie je bent, of je met een sleutel binnenkwam en wat je workspaces zijn. Elke workspaceroute heeft
de workspace-id in zijn pad: `/v1/workspaces/{ws}/…`.

## Een sleutel krijgen

### Een persoonlijke sleutel (elke rol)

1. Open in de studio het workspacemenu bovenaan de zijbalk en kies **Settings** en daarna **Claude**.
2. Kies **Use a personal key instead**, geef hem een naam en kies **Create a personal key**.
3. Kopieer de sleutel. Hij wordt één keer getoond.

Een persoonlijke sleutel heeft je eigen rol in die workspace. Hij is gemaakt voor Claude Code, maar werkt voor elke API-aanroep die je rol
toestaat, behalve sleutels beheren.

### Een workspace-API-sleutel (producent en hoger)

Een producent of eigenaar kan, ingelogd, via de API sleutels maken met een gekozen rol:

```bash
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"}'
```

Het antwoord bevat de volledige `key` één keer; Filmsquare bewaart alleen de hash. De rol van een sleutel kan nooit boven de jouwe liggen. Met
`userId` kun je een sleutel maken voor een agentgebruiker die lid is van de workspace.

`GET /workspaces/{ws}/api-keys` toont sleutels (alleen het voorvoegsel); `POST /workspaces/{ws}/api-keys/{id}/revoke` trekt er een in.
Sleutels kunnen geen sleutels maken: deze routes vragen een ingelogd persoon of een workspacesleutel, en weigeren een persoonlijke sleutel of een
Claude-koppeling met `403 not_a_person`.

## Rollen

Elke route heeft een minimale rol: `owner` > `producer` > `director` > `maker` > `reviewer` > `viewer`. Een aanroep eronder
krijgt `403 insufficient_role` met `{"required": "director", "actual": "maker"}`. Een rij die je niet mag zien, antwoordt `404`,
net als een rij die niet bestaat. Zie [Crew, rollen en toegang](https://www.filmsquare.ai/docs/nl/working-together/crew-and-roles/).

## Een eerste sessie

```bash
# 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` of `music`; `tier` is `draft` of `final`. Geen gekoppeld model
maakt al `sfx` of `music`: die takes komen binnen als uploads (`createUploadTicket`, dan `completeUpload` met een
doellaag). Laat `modelKey` weg en
Filmsquare routeert naar het geschikte model met de laagste kosten per geaccepteerde take. Abonneer je liever op
[webhooks](https://www.filmsquare.ai/docs/nl/api/webhooks/) dan te pollen.

## Conventies

| Onderwerp | Regel |
| --- | --- |
| Veldnamen | Antwoorden in `snake_case`, request bodies in `camelCase` |
| Lijsten | `{"items": […], "next_cursor": "…"}`. Geef `cursor` mee voor de volgende pagina; `limit` tot 200; `order` `asc` of `desc` |
| Gearchiveerde rijen | Weggelaten uit lijsten tenzij `includeArchived=true` |
| Verwijderen | Rijen worden gearchiveerd (`POST …/{id}/archive`), niet verwijderd. Versies, gekozen takes, akkoorden en kosten veranderen nooit |
| Idempotentie | Generatieverzoeken nemen een `Idempotency-Key`-header (of `idempotencyKey` in de body): dezelfde sleutel geeft de bestaande generatie terug |
| Geld | Kosten zijn in credits, elk tegen het tarief waarop het werk begon; wat een credit in euro kost staat in `GET /v1/pricing` en [Credits en wat dingen kosten](https://www.filmsquare.ai/docs/nl/concepts/credits-and-costs/) |

## Fouten die je tegenkomt

Elke fout heeft dezelfde vorm:

```json
{"error": {"code": "gate_closed", "message": "finals render once casting, sets, animatic are signed off",
  "details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}
```

| Status | Code | Wanneer | `details` |
| --- | --- | --- | --- |
| 400 | `validation_error` | De body, de query of een padparameter past niet bij het schema | De lijst met validatieproblemen |
| 400 | `bad_request`, `invalid_value` | De route weigert het verzoek, of de database kan een waarde niet lezen (zoals een misvormde id) | — |
| 400 | `url_not_allowed` | Een webhook- of import-URL is geen openbaar http(s)-adres | — |
| 401 | `unauthenticated` | Geen token, of een ingetrokken of verlopen token | — |
| 402 | `out_of_credits` | Niet genoeg credits vrij te besteden voor deze take | `needed`, `available` (credits) |
| 402 | `plan_limit` | Het abonnement omvat dit niet: een final op Free, een tweede productie, opslag, seats, pakketten zonder abonnement | `limit` (`final`, `productions`, `storage`, `seats`, `packs`), `plan` |
| 402 | `budget_exceeded` | Het budget van de aflevering (`budgetCredits` op de aflevering) zou worden overschreden | `episodeId`, `budgetCredits`, `spent`, `inFlight`, `needed` (credits) |
| 403 | `insufficient_role` | Je rol ligt onder het minimum van de route | `required`, `actual` |
| 403 | `not_a_signer` | Je bent geen aftekenaar van dit departement | — |
| 403 | `role_exceeds_caller` | Een uitnodiging of sleutel met een rol boven de jouwe | — |
| 403 | `not_a_person` | Sleutels beheren met een persoonlijke sleutel of een Claude-koppeling | — |
| 404 | `not_found` | De rij bestaat niet, of je mag hem niet zien | — |
| 409 | `gate_closed` | Een final voordat er groen licht is | `episode_id`, `waiting_on` (departementen, of `placement` voor een shot in geen enkele aflevering) |
| 409 | `changed_since` | Je tekende een versie af die niet meer de huidige is | `version` (de huidige) |
| 409 | `already_signed_off` | De stap is al afgetekend | — |
| 409 | `element_version_frozen` | Een referentie toegevoegd aan een versie die een take al gebruikte | — |
| 409 | `conflict` | Er bestaat al een rij met deze waarden | — |
| 422 | `foreign_key_violation`, `check_violation`, `not_null_violation` | Een verwezen rij bestaat niet (of zit in een andere workspace), of een databaseregel weigerde de waarden | `constraint`, `table`, `detail` |

`402 out_of_credits` ziet er zo uit:

```json
{"error": {"code": "out_of_credits", "message": "this needs 14 credits and 3 are free to spend",
  "details": {"workspaceId": "…", "needed": 13.35, "available": 3.2}}}
```

## Gerelateerd

- [Webhooks](https://www.filmsquare.ai/docs/nl/api/webhooks/)
- [OpenAPI-referentie](https://www.filmsquare.ai/docs/nl/api/openapi/)
- [Wat Claude kan doen](https://www.filmsquare.ai/docs/nl/claude/tools/): dezelfde API via MCP
