# The event object

## Attributes

- `object` (string, required):
- `id` (string, required): Stable id of the event (evt_<seq>).
- `seq` (integer, required): Position in the feed; grows within your company (with gaps).
- `type` (string, required): Type of the event. Known types: film.created, film.status_changed, film.storyboard_ready, film.approved, film.approval_revoked, film.cancelled, film.deleted, film.progress, feedback.updated, storyboard.preview_ready, operation.completed. New types may be added.
- `occurred_at` (string (date-time), required): Time of the change (UTC).
- `film_id` (nullable string, required): Id of the film.
- `data` (object, required): Snapshot at the time of the event: status (after the event), previous_status, approval, and the person who triggered the event (requested_by, cancelled_by, approval.approved_by, approval.revoked_by; personal data).
  - `status` (nullable enum): Status of the film after the event. Values: `briefing`, `in_production`, `storyboard_ready`, `film_ready`, `approved`, `cancelled`.
  - `previous_status` (nullable string): Status before the event (null if the feed did not know the film yet).
  - `approval` (object): Snapshot of the approval at the time of the event (in film.approved complete, in film.approval_revoked only id and revision).
    - `id` (string, required): Id of the approval.
    - `revision` (nullable integer, required): Approved revision of the film.
    - `approved_at` (nullable string (date-time)): Time of the approval (UTC).
    - `sha256` (nullable string): SHA-256 of the approved file (hex).
    - `bytes` (nullable integer): Size of the approved file in bytes.
    - `duration_s` (nullable number): Duration in seconds.
    - `resolution` (nullable string): Resolution, e.g. 1920x1080.
    - `mime` (nullable string): Media type of the file.
    - `has_subtitles` (boolean): true if subtitles were frozen with this approval.
    - `approved_by` (nullable object): film.approved: who approved the film in mint. Personal data.
      - `kind` (enum, required): user: a mint user; api: an API access of your company. Values: `user`, `api`.
      - `name` (nullable string, required): Name of the user, or the name of the API access.
      - `email` (nullable string, required): E-mail address of the user (lower case), if known; always null for api.
    - `revoked_by` (nullable object): film.approval_revoked: who revoked the approval in mint. Personal data.
      - `kind` (enum, required): user: a mint user; api: an API access of your company. Values: `user`, `api`.
      - `name` (nullable string, required): Name of the user, or the name of the API access.
      - `email` (nullable string, required): E-mail address of the user (lower case), if known; always null for api.
  - `requested_by` (nullable object): film.created: the mint user from user_email of the order. Personal data.
    - `kind` (enum, required): user: a mint user; api: an API access of your company. Values: `user`, `api`.
    - `name` (nullable string, required): Name of the user, or the name of the API access.
    - `email` (nullable string, required): E-mail address of the user (lower case), if known; always null for api.
  - `cancelled_by` (nullable object): film.cancelled: the API access that cancelled the film (kind api). Personal data.
    - `kind` (enum, required): user: a mint user; api: an API access of your company. Values: `user`, `api`.
    - `name` (nullable string, required): Name of the user, or the name of the API access.
    - `email` (nullable string, required): E-mail address of the user (lower case), if known; always null for api.
- `film` (nullable film object): The current film (as GET /films/{id}, without revisions); null if it was deleted. Only present with the scope films:read.
  - `object` (string, required):
  - `id` (string, required): Id of the film in mint.
  - `title` (string, required): Title as it is in mint now (people can change it there).
  - `status` (enum, required): briefing: created in mint, nothing is running (for example with automation: none). in_production: mint is planning or producing the storyboard (or the film). storyboard_ready: the storyboard is ready for review in mint. With automation: storyboard the film stops here until a person continues in mint. film_ready: the film is rendered and waits for approval by a person in mint. approved: a person approved the film in mint. cancelled: the film was cancelled. New values may be added within v1. Values: `briefing`, `in_production`, `storyboard_ready`, `film_ready`, `approved`, `cancelled`.
  - `stage` (nullable enum, required): Detailed stage as shown in the mint project list, or null if unknown. New values may be added within v1. Values: `briefing`, `style`, `voice`, `ready_to_plan`, `planning`, `storyboard_in_progress`, `storyboard_review`, `film_rendering`, `film_ready`, `approved`, `paused`, `error`, `cancelled`.
  - `attention_required` (boolean, required): true if a person needs to act in mint (see notice).
  - `notice` (nullable object, required): Why a person needs to act in mint, or null. Codes: production_paused (“Production is paused in mint. Someone needs to resume it.”), production_failed (“Production failed in mint. Someone needs to check it.”), planning_failed (“Planning the storyboard failed in mint. Someone needs to check it.”), automation_failed (“The automatic storyboard could not be completed. Someone needs to continue in mint.”), insufficient_credits (“The company does not have enough credits. Someone needs to add credits and continue in mint.”), automation_disabled (“Automatic production is currently switched off. Someone needs to continue in mint.”).
    - `code` (enum, required):  Values: `production_paused`, `production_failed`, `planning_failed`, `automation_failed`, `insufficient_credits`, `automation_disabled`.
    - `message` (string, required): Short English text (may change).
  - `source` (enum, required): api: ordered through the API; app: reserved for projects created in mint (not returned in v1). Values: `api`, `app`.
  - `automation` (nullable enum, required): none: mint only creates the film with its briefing; people continue in mint. storyboard (default): mint plans and produces the storyboard automatically and stops at storyboard_ready for review. film: mint also renders the film without stopping at the storyboard (status film_ready). The film is always approved by a person in mint, never by the API. Values: `none`, `storyboard`, `film`.
  - `video_key` (nullable string, required): Your key of the video, as sent.
  - `version` (nullable string, required): Version of the video, canonical (1.0.0 is returned as 1.0).
  - `previous_version_id` (nullable string, required): Id of the film with the next lower version of the same video_key, or null.
  - `is_latest_approved_version` (boolean, required): true only if this film is approved and no higher, approved and not cancelled version of the same video_key exists.
  - `language` (nullable enum, required): Language of the film. Values: `de`, `en`, `fr`, `es`, `it`, `pt`, `nl`, `pl`, `cs`, `sk`, `hu`, `ro`, `hr`, `sl`, `sv`, `da`, `no`, `fi`, `tr`, `id`, `vi`, `el`, `uk`, `ru`, `bg`.
  - `template` (nullable string, required): Key of the template used when the film was created.
  - `settings` (object, required): Effective settings of the film in mint. Values that are not set (or that mint cannot express in the API) are null.
    - `format` (nullable enum, required): Aspect ratio. Values: `16x9`, `9x16`, `1x1`.
    - `style_id` (nullable string, required): Id of the style (see GET /styles).
    - `style_revision` (nullable integer, required): Revision of the style the film uses.
    - `brand_id` (nullable string, required): Effective brand (see GET /brands); null = no brand.
    - `voice_id` (nullable string, required): Voice of the narration (may also be a voice from the mint voice library); null = none set yet.
    - `voice_name` (nullable string, required): Name of the voice.
    - `narration_mode` (nullable enum, required): verbatim (default): narration_text is spoken word for word. smooth: mint polishes the language of narration_text and keeps its content. free: narration_text is the briefing; mint writes the narration freely (use target_duration_s for the length). Values: `verbatim`, `smooth`, `free`.
    - `tempo` (nullable enum, required): Pace of the film. Values: `presenting`, `lively`, `kinetic`.
    - `freedom` (nullable enum, required): Creative freedom in percent. Values: `0`, `25`, `40`, `65`, `100`.
    - `video_share` (nullable enum, required): Share of moving video clips in percent. Values: `0`, `25`, `50`, `75`, `100`.
    - `target_duration_s` (nullable integer, required): Target duration in seconds (in steps of 6 seconds).
  - `category` (nullable object, required): Category of the film in mint (see GET /categories), or null.
    - `object` (string):
    - `id` (string, required): Id of the category.
    - `name` (string, required):
    - `external_key` (nullable string, required): Key of the connected system, if set.
    - `parent` (nullable object, required): Top-level category of a subcategory; null for a top-level category.
      - `id` (string, required):
      - `name` (string, required):
      - `external_key` (nullable string, required):
  - `requested_by` (nullable object, required): The mint user from user_email of the request (a Person with kind user). This user is responsible for the film in mint and is notified when the storyboard is ready. Personal data.
    - `kind` (enum, required): Always user. Values: `user`.
    - `email` (string, required): E-mail address (lower case).
    - `name` (nullable string, required): Name of the user at the time the film was created.
  - `metadata` (object, required): Your metadata, as sent. mint never uses it for the film. Key order is kept in POST /films (first response), GET /films and GET /films/{id}; a replayed response may order keys differently.
  - `approval` (nullable object, required): The active approval of the film (only the approved original version is the film), or null.
    - `revision` (integer, required): Approved revision of the film.
    - `approved_at` (string (date-time), required): Time of the approval (UTC).
    - `sha256` (nullable string, required): SHA-256 of the approved file (hex).
    - `bytes` (nullable integer, required): Size of the approved file in bytes.
    - `duration_s` (nullable number, required): Duration in seconds.
    - `resolution` (nullable string, required): Resolution, e.g. 1920x1080.
    - `mime` (nullable string, required): Media type of the file, e.g. video/mp4.
    - `has_subtitles` (boolean, required): true if subtitles were frozen with this approval (subtitles_url).
    - `approved_by` (nullable object, required): Who approved the film in mint (kind user, name and e-mail; email is null for approvals before 9 November 2026). Personal data.
      - `kind` (enum, required): user: a mint user; api: an API access of your company. Values: `user`, `api`.
      - `name` (nullable string, required): Name of the user, or the name of the API access.
      - `email` (nullable string, required): E-mail address of the user (lower case), if known; always null for api.
  - `cancelled_at` (nullable string (date-time), required): Time of the cancellation (UTC), or null.
  - `created_at` (string (date-time), required): Creation time (UTC).
  - `updated_at` (string (date-time), required): Last change (UTC).
  - `app_url` (nullable string, required): Link to the film in mint (for people with access), or null.
  - `file_url` (nullable string, required): Path of the approved file (GET /films/{id}/file, relative to the host of the API), or null without an active approval.
  - `subtitles_url` (nullable string, required): Path of the subtitles of the approval (GET /films/{id}/subtitles.srt), or null if the approval has none.
  - `revisions` (array of objects): Rendered revisions of the film, newest last (only in GET /films/{id}, without file links).
    - `revision` (integer, required): Number of the rendered revision.
    - `status` (enum, required): rendering, ready or failed. Values: `rendering`, `ready`, `failed`.
    - `created_at` (nullable string (date-time), required): Start of the render (UTC).
    - `finished_at` (nullable string (date-time), required): End of the render (UTC), null while rendering.
    - `duration_s` (nullable number, required): Duration in seconds.
    - `resolution` (nullable string, required): Resolution, e.g. 1920x1080.

## Example

```json
{
  "object": "event",
  "id": "evt_10482",
  "seq": 10482,
  "type": "film.approved",
  "occurred_at": "2026-11-11T14:30:00Z",
  "film_id": "k7m2xq9v4t8n1b5r3c6d0wza",
  "data": {
    "status": "approved",
    "previous_status": "film_ready",
    "approval": {
      "id": "apr_20931",
      "revision": 2,
      "approved_at": "2026-11-11T14:30:00Z",
      "sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
      "bytes": 48213377,
      "duration_s": 184.6,
      "resolution": "1920x1080",
      "mime": "video/mp4",
      "has_subtitles": true,
      "approved_by": {
        "kind": "user",
        "name": "Anna Schmidt",
        "email": "anna.schmidt@example.edu"
      },
      "revoked_by": null
    },
    "requested_by": {
      "kind": "user",
      "name": "Anna Schmidt",
      "email": "anna.schmidt@example.edu"
    },
    "cancelled_by": null
  },
  "film": {
    "object": "film",
    "id": "k7m2xq9v4t8n1b5r3c6d0wza",
    "title": "Lesson 3: Market segmentation",
    "status": "approved",
    "stage": "approved",
    "attention_required": false,
    "notice": null,
    "source": "api",
    "automation": "storyboard",
    "video_key": "MKT101-lesson-03",
    "version": "1.0",
    "previous_version_id": null,
    "is_latest_approved_version": true,
    "language": "de",
    "template": "lesson-standard",
    "settings": {
      "format": "16x9",
      "style_id": "b6ed57e1-2c4f-4b8a-9d3e-6f1a0c2b7e45",
      "style_revision": 4,
      "brand_id": "brand-northwind-x7k2p9",
      "voice_id": "Xb7hH8MSUJpSbSDYk0k2",
      "voice_name": "Clara",
      "narration_mode": "verbatim",
      "tempo": "presenting",
      "freedom": 40,
      "video_share": 25,
      "target_duration_s": 180
    },
    "category": {
      "object": "category",
      "id": "rz3p8w1d6c0b",
      "name": "MKT101 Marketing basics",
      "external_key": "MKT101",
      "parent": {
        "id": "mk7t2q9x4v1n",
        "name": "Marketing",
        "external_key": "MKT"
      }
    },
    "requested_by": {
      "kind": "user",
      "email": "anna.schmidt@example.edu",
      "name": "Anna Schmidt"
    },
    "metadata": {
      "course_id": "MKT101",
      "lesson": 3
    },
    "approval": {
      "revision": 2,
      "approved_at": "2026-11-11T14:30:00Z",
      "sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
      "bytes": 48213377,
      "duration_s": 184.6,
      "resolution": "1920x1080",
      "mime": "video/mp4",
      "has_subtitles": true,
      "approved_by": {
        "kind": "user",
        "name": "Anna Schmidt",
        "email": "anna.schmidt@example.edu"
      }
    },
    "cancelled_at": null,
    "created_at": "2026-11-10T08:00:00Z",
    "updated_at": "2026-11-11T14:30:00Z",
    "app_url": "https://app.cream-ai.de/editorial/k7m2xq9v4t8n1b5r3c6d0wza",
    "file_url": "https://api.cream-ai.de/api/v1/films/k7m2xq9v4t8n1b5r3c6d0wza/file",
    "subtitles_url": "https://api.cream-ai.de/api/v1/films/k7m2xq9v4t8n1b5r3c6d0wza/subtitles.srt"
  }
}
```