API de Watch Order para desarrolladores

Autenticación

Ninguna. Todos los endpoints de abajo son públicos y de solo lectura. Las respuestas se guardan en la caché del CDN: no hagas más de una petición por segundo y guarda las respuestas en tu lado cuando puedas.

Endpoints

GET /api/franchises — todas las franquicias, con id, nombre, descripción, cantidad de títulos y órdenes disponibles.

GET /api/franchises/{id}?order={orderId} — una franquicia con sus continuidades, órdenes, rutas y los títulos del orden pedido (por defecto, el de estreno).

GET /api/titles/{id} — un título: tipo, estreno, duración, temporadas, sinopsis, póster, ids de TMDB e IMDb y sus franquicias.

GET /api/upcoming?franchise={ids} — estrenos, temporadas y episodios nuevos de los próximos 365 días.

GET /api/providers?tmdbId=&type=movie|tv&region= — dónde ver un título en un país (datos de JustWatch vía TMDB).

GET /api/credits?tmdbId=&type=movie|tv — reparto principal.

GET /api/health — estado del servicio.

Todos aceptan lang=es|en donde hay textos (por defecto, inglés).

Ejemplos

El orden cronológico del MCU, en español:

curl 'https://watchlist.wxlter.dev/api/franchises/marvel?order=chronological&lang=es'

Errores

Los errores responden JSON con el status HTTP correcto: error (el mensaje), code (invalid_request, not_found, rate_limited, upstream_error, internal_error…), status, hint (cómo corregir la petición) y docs. Un endpoint que no existe responde 404 en JSON.

{"error": "No existe la franquicia \"marvl\"", "code": "not_found", "status": 404, "hint": "List valid ids with GET /api/franchises.", "docs": "/developers#errors"}

Para agentes de IA

/llms.txt resume la app y cuándo usarla. Todas las páginas públicas (portada, franquicias, títulos, rutas, FAQ y guía) responden Markdown si pides Accept: text/markdown, y una ruta que no existe responde 404.

Atribución y uso

Los datos de títulos vienen de TMDB y los de «dónde ver», de JustWatch: si los muestras, atribúyelos. Los órdenes, las rutas y la importancia de cada título son de Watch Order; enlaza a la página de la franquicia cuando los uses. El uso está sujeto a los términos.