Picker (Let AI Choose) | Movie Knight Server

curl -X POST https://movieknight-server-7d8h.onrender.com/api/ai/picker \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "prompt": "a tense thriller for tonight",
  "collectionId": "{{collectionId}}",
  "count": 2
}'

{
  "ok": true,
  "data": [
    {
      "id": 27205,
      "title": "Inception",
      "reason": "A layered heist thriller that keeps the tension high from start to finish.",
      "poster_path": "/oYuLEt3zVCKq57qu2F8dT7NIa6f.jpg",
      "releaseYear": 2010,
      "release_date": "2010-07-15",
      "vote_average": 8.369
    },
    {
      "id": 550,
      "title": "Fight Club",
      "reason": "Dark, twist-driven, and gripping right up to the final scene.",
      "poster_path": "/pB8BM7pdSp6B6Ih7QZ4DrQ3PmJK.jpg",
      "releaseYear": 1999,
      "release_date": "1999-10-15",
      "vote_average": 8.438
    }
  ],
  "aiUsage": {
    "used": 1,
    "limit": 5,
    "remaining": 4
  }
}

What: Pick movies FROM the caller’s own collection that best match a prompt, each with a one-line reason. Owner-only.

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

Body (JSON):

Field	Type	Required	Description	Example
collectionId	string	yes	The caller’s collection id.	`66b0c1d2e3f4a5b6c7d8e9f0`
prompt	string	yes	Natural-language ask.	`a tense thriller for tonight`
count	integer	no	How many to return. Clamped to 1-3 and to the collection size; invalid = 1.	`2`
exclude_ids	array	no	TMDB ids currently on screen (Smart Reroll soft filter).	`[550]`

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

**What:** Pick movies FROM the caller's own collection that best match a prompt, each with a one-line reason. Owner-only. **Auth:** Bearer token required. Spends 1 daily AI action on success. **Body (JSON):** | Field | Type | Required | Description | Example | |---|---|---|---|---| | collectionId | string | yes | The caller's collection id. | `66b0c1d2e3f4a5b6c7d8e9f0` | | prompt | string | yes | Natural-language ask. | `a tense thriller for tonight` | | count | integer | no | How many to return. Clamped to 1-3 and to the collection size; invalid = 1. | `2` | | exclude_ids | array | no | TMDB ids currently on screen (Smart Reroll soft filter). | `[550]` | **Returns:** `data = [{ id, title, poster_path, vote_average, release_date, releaseYear, reason }]` + sibling `aiUsage`.

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.

promptstringRequired

collectionIdstringRequired

countintegerOptional

exclude_idslist of integersOptional

Response

okboolean

datalist of objects

aiUsageobject

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error

502

Bad Gateway Error

504

Gateway Timeout Error

What: Pick movies FROM the caller’s own collection that best match a prompt, each with a one-line reason. Owner-only.

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

Body (JSON):

Field	Type	Required	Description	Example
collectionId	string	yes	The caller’s collection id.	`66b0c1d2e3f4a5b6c7d8e9f0`
prompt	string	yes	Natural-language ask.	`a tense thriller for tonight`
count	integer	no	How many to return. Clamped to 1-3 and to the collection size; invalid = 1.	`2`
exclude_ids	array	no	TMDB ids currently on screen (Smart Reroll soft filter).	`[550]`

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