# Send feedback on scenes of the storyboard

`POST https://api.cream-ai.de/api/v1/films/{id}/feedback`

Sends feedback on scenes of the storyboard, like a message in the mint chat. mint plans and applies each entry on its own; it never asks back but decides on the most plausible reading. Approving the film stays with a person in mint. Each entry names a scene (`scene`), a time in the film (`at_s`) or both. With `preview_id` the time refers to that storyboard preview; without it, to the current timeline of the film. Several entries for the same scene are applied one after the other in the order of `entries`. The entries are queued (`status: queued`) and handed over as soon as the scene is free. Poll `GET /films/{id}/feedback/{feedback_id}` or listen for `feedback.updated` events. Credits: planning and rendering cost credits according to the mint price list, booked on the company in the name of the user from `user_email` of the order. A redraw of a scene at a fixed price only happens with `allow_redraw: true`. If the company does not have enough credits, the response is `402 insufficient_credits` and nothing is created. Attachments are upload ids of your company (`POST /uploads`). The request is all or nothing: if one entry is invalid, no entry is created (`field` names the entry, e.g. `entries[1].message`). The batch stays bound to its Idempotency-Key: the same key with the same request returns the same entries (also after 24 hours), with another request `422 idempotency_mismatch`. Rejections with a passing reason (`storyboard_not_ready`, `insufficient_credits`) are not stored under the key: a retry with the same key runs again. A film cancelled through the API (`status: cancelled`) takes no more feedback: `409 film_cancelled`. Its feedback can still be read and cancelled.

Scopes: `feedback:write`

## Parameters

- `id` (path, required): Id of the film (id from POST /films or GET /films).
- `Idempotency-Key` (header, required): Unique key of this write request (1–128 visible ASCII characters, e.g. a UUID). Retries with the same key return the stored response.

## Request body

- `preview_id` (string): Storyboard preview the times (at_s) refer to. It must belong to the current storyboard of the film.
- `entries` (array of objects, required):
  - `scene` (integer): Number of the scene in the current storyboard.
  - `at_s` (number): Time in the film (or in the preview from preview_id) in seconds; it selects the scene at that time.
  - `kind` (enum): What the feedback is about. timing and voice are not supported (400 feedback_kind_unsupported). Values: `text`, `image`, `layout`, `general`.
  - `message` (string, required): The feedback in your words (3 to 20000 characters after trimming; at most 100000 characters per request).
  - `region` (object): Area of the frame as fractions of width and height (0..1, origin top left). It is cut to the frame.
    - `x` (number, required):
    - `y` (number, required):
    - `w` (number, required): Width; the area must be greater than 0.
    - `h` (number, required): Height; the area must be greater than 0.
  - `point` (object): Point in the frame as fractions of width and height (0..1, origin top left).
    - `x` (number, required):
    - `y` (number, required):
  - `attachments` (array of strings): Upload ids of your company (at most 4 per entry, 20 different per request). Unknown or foreign uploads: 400 upload_not_found; expired: 410 upload_expired.
  - `allow_redraw` (boolean): true: mint may redraw the scene at a fixed price if the change needs it. Otherwise such an entry fails with redraw_required.
  - `external_ref` (string): Your own reference (e.g. a ticket id); returned unchanged and in feedback.updated events.

## Returns

- 202: The entries were queued (or the entries of this Idempotency-Key are returned again).

## Errors

- 400: Invalid request (invalid_request, invalid_json, invalid_cursor, idempotency_key_required, invalid_idempotency_key, parent_not_found, max_depth_exceeded, narration_too_long, user_not_in_company, template_not_found, category_not_found, feedback_kind_unsupported, upload_not_found).
- 401: Missing, malformed, revoked or expired API key (unauthorized).
- 402: The company does not have enough credits (insufficient_credits). Nothing was created; not stored under the Idempotency-Key.
- 403: Not allowed (forbidden_scope, ip_not_allowed, company_inactive, api_not_enabled).
- 404: The film was not found, or the preview from preview_id was not found (not_found, field: preview_id).
- 409: The film was cancelled through the API (film_cancelled), no storyboard yet (storyboard_not_ready), the timeline no longer matches (timeline_outdated, details.reason: preview_from_previous_storyboard or scene_boundaries_changed), too many open entries for this film (feedback_queue_full, details.open, details.limit), or a request with this Idempotency-Key is still running (idempotency_in_progress).
- 410: An attachment has expired (upload_expired, field names it). Upload the file again.
- 413: Request body too large (payload_too_large).
- 415: Request body is not JSON (unsupported_media_type).
- 422: Idempotency-Key reused with a different request (idempotency_mismatch, details.batch_id), or a scene or time is not in the current storyboard (scene_not_found, field names the entry).
- 429: Too many requests (rate_limited).
- 500: Internal error (internal). Quote the request id when you contact support.
- 503: Temporarily unavailable (service_unavailable). Retry later (after Retry-After seconds, if sent).

## Example request

```sh
curl -X POST "https://api.cream-ai.de/api/v1/films/k7m2xq9v4t8n1b5r3c6d0wza/feedback" \
  -H "Authorization: Bearer $MINT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "preview_id": "pv_8c1e4a7d2b5f9e3c6a0d1b4e7f2a5c8d",
    "entries": [
      {
        "scene": 4,
        "kind": "text",
        "message": "Please write \"customer groups\" instead of \"target groups\" in the headline.",
        "external_ref": "lms-review-8812"
      }
    ]
  }'
```

## Example response (202)

```json
{
  "object": "feedback_batch",
  "id": "fbb_6e1c8a3f5d2b9e4a7c0f1d6b3e8a5c2f",
  "film_id": "k7m2xq9v4t8n1b5r3c6d0wza",
  "data": [
    {
      "object": "feedback",
      "id": "fb_2a7d4c9e1b6f3a8d5c0e7b2f4a9d1c6e",
      "batch_id": "fbb_6e1c8a3f5d2b9e4a7c0f1d6b3e8a5c2f",
      "film_id": "k7m2xq9v4t8n1b5r3c6d0wza",
      "scene": 4,
      "at_s": null,
      "scene_offset_s": null,
      "preview_id": "pv_8c1e4a7d2b5f9e3c6a0d1b4e7f2a5c8d",
      "storyboard_version": 1,
      "kind": "text",
      "message": "Please write \"customer groups\" instead of \"target groups\" in the headline.",
      "region": null,
      "point": null,
      "attachments": [],
      "allow_redraw": false,
      "external_ref": "lms-review-8812",
      "status": "queued",
      "stage": null,
      "queue_reason": null,
      "warnings": [],
      "result": null,
      "failure": null,
      "sender": {
        "kind": "user",
        "name": "Anna Schmidt",
        "email": "anna.schmidt@example.edu"
      },
      "created_at": "2026-11-10T08:31:02Z",
      "updated_at": "2026-11-10T08:31:02Z"
    }
  ]
}
```