Enhance collection | Movie Knight Server

curl -X POST https://movieknight-server-7d8h.onrender.com/api/ai/enhance/66b0c1d2e3f4a5b6c7d8e9f0 \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "exclude_ids": [],
  "exclude_titles": []
}'

{
  "ok": true,
  "data": [
    {
      "id": 603,
      "title": "The Matrix",
      "reason": "Shares the cerebral, reality-bending tone of your collection.",
      "poster_path": "/p96dm7sCMn4VYAStA6siNz30G1r.jpg",
      "release_date": "1999-03-30",
      "vote_average": 8.2
    },
    {
      "id": 157336,
      "title": "Interstellar",
      "reason": "Big-idea science fiction with the same emotional weight.",
      "poster_path": "/gEU2QniE6E77NI6lCU6MxlNBvIx.jpg",
      "release_date": "2014-11-05",
      "vote_average": 8.4
    }
  ],
  "aiUsage": {
    "used": 1,
    "limit": 5,
    "remaining": 4
  }
}

What: Recommend up to 3 movies NOT already in the collection that fit its taste, each with a reason. Owner-only. Warms the movie cache with what it returns.

Auth: Bearer token required. Spends 1 daily AI action on success.

Path params: id (collection id).

Body (JSON, all optional):

Field	Type	Required	Description	Example
exclude_ids	array	no	TMDB ids already shown this session (hard filter).	`[603]`
exclude_titles	array	no	Titles already suggested this session (prompt avoidance, max 100).	`["The Matrix"]`

Returns: data = [{ id, title, poster_path, vote_average, release_date, reason }] + sibling aiUsage.

**What:** Recommend up to 3 movies NOT already in the collection that fit its taste, each with a reason. Owner-only. Warms the movie cache with what it returns. **Auth:** Bearer token required. Spends 1 daily AI action on success. **Path params:** `id` (collection id). **Body (JSON, all optional):** | Field | Type | Required | Description | Example | |---|---|---|---|---| | exclude_ids | array | no | TMDB ids already shown this session (hard filter). | `[603]` | | exclude_titles | array | no | Titles already suggested this session (prompt avoidance, max 100). | `["The Matrix"]` | **Returns:** `data = [{ id, title, poster_path, vote_average, release_date, reason }]` + sibling `aiUsage`.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

collectionIdstringRequired

Collection id.

Request

This endpoint expects an object.

exclude_idslist of integersOptional

exclude_titleslist of stringsOptional

Response

okboolean

datalist of objects

aiUsageobject

Errors

401

Unauthorized Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error

502

Bad Gateway Error

504

Gateway Timeout Error