davidkk/movies

Movies API – Latest merged list (cache; agent-ready)

When to use

• User wants current movie listings (Maoyan + TMDB merged cache), “what’s playing”, “top movies”, “movie list from this site”.
• This endpoint does not live-fetch TMDB/Maoyan per request — safe to call when a cached list is enough.
• Do not call for plot-only questions that need a different tool, or unrelated domains.
• Do not overuse: unrelated chat → do not call.

Hard boundaries (must check before call)

• This module returns cached merged list only; do not imply real-time box-office/live upstream fetch per request.
• If a title is not in data.movies, state “not in current cache” instead of fabricating entries.

Pre-check (before tool call)

• Confirm user request is compatible with cached list retrieval.
• Confirm optional filters (e.g. year/top-N) can be derived from returned movie fields.

Fallback (when not suitable)

• If user requires real-time upstream freshness, explain that this endpoint is cache-backed.
• If no rows are returned, explicitly report empty cache state rather than guessing.

Retry policy

• Retry once on transient 500/5xx.
• Do not loop retries for persistent empty cache or unsupported filter requests.

Multi-turn / Missing parameters

• No query or body required for GET /api/movies. If the user wants one specific title not in the list, answer from the returned list or say it is not in the cached set — do not invent movies.

Parameters

• None for GET /api/movies.

Steps

0. Conversation cache: If GET /api/movies already returned 200 in this conversation and the user asks again without needing fresher data, reuse data.
1. Call GET /api/movies.
2. Check HTTP status and envelope { code, message, data }.
3. Extract data.movies, data.cachedAt (ms timestamp when cache updated).
4. Format a compact list or top N titles with scores/sources as the user asked.

Request

GET /api/movies — read-only; does not trigger upstream writes.

Response

Envelope: HTTP 200 with { code: 0, message: "ok", data: { movies, cachedAt } }.

• data.movies — array of merged movie objects (may be empty if cache has no rows yet). Do not invent titles not present in this array.
• data.cachedAt — number (typically Unix ms) when the list was last updated in cache — useful to mention if the user asks how fresh the list is.

Typical fields on each item (subset may be missing; use only what exists): name, score, sources, poster/image URLs, links — prefer quoting fields from the payload over guessing.

Provider mix: Maoyan + TMDB merge may mean partial sources; missing optional fields are normal, not an error.

Say to the user (one line)

• Summarize a few titles or filter by user criteria from returned items only.

Output language

• User’s language for commentary; keep titles as returned.

Idempotency & cache (conversation)

• Reuse prior 200 body in the same conversation when appropriate.

Examples

• User: “List trending movies from the API” → GET /api/movies → summarize data.movies (verify live).
• User: “Top 5 by score” → same GET → sort/filter client-side from data.movies.
• User: “What’s the CNY rate?” → Do not call this API.

Agent rules

Single GET; follow Steps; do not call external TMDB/Maoyan if this list suffices.

Error handling (HTTP)

| Status | Agent behavior | | ------- | --------------------------------------------------------------------------------------------- | | 200 | Success — data.movies may be []; explain “no cached list” instead of fabricating films. | | 500 | Server error — report briefly; one retry later is OK; do not spam retries. | | 4xx | Rare — do not blind retry; pass through message from JSON if present. |