# Scopes

Every API access has its own scopes. A request with a key that lacks a scope returns `403 forbidden_scope`;
`details.required_scopes` names what is missing. Writing scopes include reading the same area.

| Scope | Allows |
|---|---|
| `catalog:read` | Read approved styles, brands and voices and active briefing templates of this company as compact lists. |
| `categories:read` | Read the category tree of this company, also by external key. |
| `categories:write` | Create and rename categories and subcategories and link them to an external key. Includes `categories:read`. |
| `films:read` | Read films, status and production progress. |
| `films:write` | Create films from a briefing, have them produced automatically up to the storyboard or the film, and cancel them. Includes `films:read`. |
| `files:read` | Download approved film files and subtitles. |
| `previews:read` | Download the storyboard version of a film as MP4, also before approval. |
| `previews:write` | Have a storyboard preview of a film created as MP4. Each new preview costs credits. Includes `previews:read`. |
| `events:read` | Read the continuous event feed of this company with a cursor (film objects in the feed only together with films:read). |
| `uploads:write` | Upload images and videos to use them in feedback and comments. |
| `feedback:write` | Send, cancel and retry feedback on scenes, and read and add comments on the finished film. Feedback changes the scenes like a message in the chat and may cost credits. |
| `films:revise` | Have open comments applied to the film; mint creates a new revision of the film from them (costs credits). Includes `films:read`. |

`GET /me` and `GET /openapi.json` need no scope. More scopes follow with later versions.

### Endpoints by scope

| Scope | Endpoints |
|---|---|
| `catalog:read` | `GET /brands`<br>`GET /styles`<br>`GET /templates`<br>`GET /voices` |
| `categories:read` | `GET /categories` |
| `categories:write` | `POST /categories`<br>`PATCH /categories/{id}` |
| `events:read` | `GET /events` |
| `feedback:write` | `GET /films/{id}/comments`<br>`POST /films/{id}/comments`<br>`POST /films/{id}/comments/apply`<br>`GET /films/{id}/feedback`<br>`POST /films/{id}/feedback`<br>`GET /films/{id}/feedback/{feedback_id}`<br>`POST /films/{id}/feedback/{feedback_id}/cancel`<br>`POST /films/{id}/feedback/{feedback_id}/retry` |
| `files:read` | `GET /films/{id}/file`<br>`GET /films/{id}/subtitles.srt` |
| `films:read` | `GET /films`<br>`GET /films/{id}`<br>`GET /films/{id}/progress`<br>`GET /films/{id}/storyboard-preview`<br>`POST /films/{id}/storyboard-preview`<br>`GET /films/{id}/storyboard-preview/file`<br>`GET /operations/{id}` |
| `films:revise` | `POST /films/{id}/comments/apply` |
| `films:write` | `POST /films`<br>`POST /films/{id}/cancel` |
| `previews:read` | `GET /films/{id}/storyboard-preview`<br>`GET /films/{id}/storyboard-preview/file` |
| `previews:write` | `POST /films/{id}/storyboard-preview` |
| `uploads:write` | `POST /uploads`<br>`GET /uploads/{id}` |
| no scope | `GET /me`<br>`GET /openapi.json` |

```json Missing scope (403)
{
  "error": {
    "code": "forbidden_scope",
    "message": "This API key does not have the scope films:write.",
    "request_id": "req_5b2e8f1a4c7d0e3b6a9f2c5d8e1b4a7c",
    "details": { "required_scopes": ["films:write"] }
  }
}
```