{ "openapi": "3.1.0", "info": { "title": "HexaScore API", "version": "1.0.0", "summary": "Puntuaciones de la comunidad para juegos, películas, series y libros.", "description": "API REST de solo lectura sobre el catálogo de HexaScore: cada elemento tiene una puntuación de la comunidad de 0 a 100 y seis promedios por categoría.\n\n- **Autenticación**: `Authorization: Bearer hx_live_…` — crea una clave en `/profile/api`.\n- **Formato**: JSON, campos en `snake_case`, fechas ISO 8601. Los errores siguen la RFC 9457 (`application/problem+json`) con un `code` estable.\n- **Paginación**: por cursor — envía `next_cursor` de vuelta como `cursor`.\n- **Planes**: Free = 100 solicitudes en total, 10 elementos por página, 1 req/s. Pro y Business tienen cuotas mensuales, 100 elementos por página y créditos prepagados.\n\nGuías: https://hexascore.app/docs", "contact": { "name": "HexaScore", "url": "https://hexascore.app/docs" }, "license": { "name": "Proprietary", "url": "https://hexascore.app/terms" } }, "servers": [ { "url": "https://api.hexascore.app/v1", "description": "Producción" }, { "url": "/api/v1", "description": "Este despliegue (la misma API en /api/v1)" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Games", "description": "Juegos: listado, detalle y géneros." }, { "name": "Movies", "description": "Películas: listado, detalle y géneros." }, { "name": "Series", "description": "Series: listado, detalle y géneros." }, { "name": "Books", "description": "Libros: listado, detalle y géneros." }, { "name": "Search", "description": "Encuentra elementos por texto o por un id de otra base de datos." }, { "name": "Account", "description": "Tu cuota, créditos y límite de tasa." } ], "externalDocs": { "description": "Guías", "url": "https://hexascore.app/docs" }, "paths": { "/games": { "get": { "operationId": "listGames", "tags": [ "Games" ], "summary": "Listar juegos", "description": "Pagina los juegos con filtros. Categorías de este tipo: `gameplay`, `fun`, `sound`, `technical`, `visual`, `storytelling` — filtra con `min_`. Envía `next_cursor` de vuelta como `cursor` hasta que sea `null`.", "parameters": [ { "name": "genre", "in": "query", "required": false, "description": "Género exacto, tal como lo devuelve el endpoint de géneros.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "platform", "in": "query", "required": false, "description": "Nombre exacto de la plataforma.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "year", "in": "query", "required": false, "description": "Año de lanzamiento.", "schema": { "type": "integer", "minimum": 1800, "maximum": 2100 } }, { "name": "min_score", "in": "query", "required": false, "description": "Puntuación mínima de la comunidad (oculta los elementos sin puntuación).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "max_score", "in": "query", "required": false, "description": "Puntuación máxima de la comunidad (oculta los elementos sin puntuación).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_gameplay", "in": "query", "required": false, "description": "Promedio mínimo de `gameplay` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_fun", "in": "query", "required": false, "description": "Promedio mínimo de `fun` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_sound", "in": "query", "required": false, "description": "Promedio mínimo de `sound` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_technical", "in": "query", "required": false, "description": "Promedio mínimo de `technical` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_visual", "in": "query", "required": false, "description": "Promedio mínimo de `visual` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_storytelling", "in": "query", "required": false, "description": "Promedio mínimo de `storytelling` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Campo de ordenación; antepón `-` para orden descendente. Los elementos sin puntuación o sin fecha siempre van al final.", "schema": { "default": "-popularity", "x-enum-varnames": [ "POPULARITY_DESC", "POPULARITY", "SCORE_DESC", "SCORE", "RELEASE_DATE_DESC", "RELEASE_DATE", "RATING_COUNT_DESC", "RATING_COUNT" ], "type": "string", "enum": [ "-popularity", "popularity", "-score", "score", "-release_date", "release_date", "-rating_count", "rating_count" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Tamaño de página, de 1 a 100. Plan Free: hasta 10.", "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` de la página anterior.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma de los títulos y sinopsis (`en`, `pt-BR`, `es`). Recurre al inglés si falta.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Solicitudes en el periodo de cuota actual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes restantes en el periodo.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta que se reinicie la cuota (`0` para la cuota vitalicia de Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual que `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/games/{id}": { "get": { "operationId": "getGame", "tags": [ "Games" ], "summary": "Obtener un juego", "description": "Registro completo: metadatos, puntuación de la comunidad y promedios por categoría (`gameplay`, `fun`, `sound`, `technical`, `visual`, `storytelling`), ids externos, tráilers y la sinopsis con licencia. Un id de otro tipo devuelve 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id del elemento (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma de los títulos y sinopsis (`en`, `pt-BR`, `es`). Recurre al inglés si falta.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Solicitudes en el periodo de cuota actual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes restantes en el periodo.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta que se reinicie la cuota (`0` para la cuota vitalicia de Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual que `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemDetail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/games/genres": { "get": { "operationId": "listGameGenres", "tags": [ "Games" ], "summary": "Listar géneros de juegos", "description": "Todos los géneros usados por este tipo, con su número de elementos. Usa `slug` como filtro `genre`.", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Solicitudes en el periodo de cuota actual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes restantes en el periodo.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta que se reinicie la cuota (`0` para la cuota vitalicia de Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual que `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenreList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/movies": { "get": { "operationId": "listMovies", "tags": [ "Movies" ], "summary": "Listar películas", "description": "Pagina las películas con filtros. Categorías de este tipo: `screenplay`, `acting`, `direction`, `cinematography`, `soundtrack`, `entertainment` — filtra con `min_`. Envía `next_cursor` de vuelta como `cursor` hasta que sea `null`.", "parameters": [ { "name": "genre", "in": "query", "required": false, "description": "Género exacto, tal como lo devuelve el endpoint de géneros.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "year", "in": "query", "required": false, "description": "Año de lanzamiento.", "schema": { "type": "integer", "minimum": 1800, "maximum": 2100 } }, { "name": "min_score", "in": "query", "required": false, "description": "Puntuación mínima de la comunidad (oculta los elementos sin puntuación).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "max_score", "in": "query", "required": false, "description": "Puntuación máxima de la comunidad (oculta los elementos sin puntuación).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_screenplay", "in": "query", "required": false, "description": "Promedio mínimo de `screenplay` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_acting", "in": "query", "required": false, "description": "Promedio mínimo de `acting` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_direction", "in": "query", "required": false, "description": "Promedio mínimo de `direction` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_cinematography", "in": "query", "required": false, "description": "Promedio mínimo de `cinematography` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_soundtrack", "in": "query", "required": false, "description": "Promedio mínimo de `soundtrack` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_entertainment", "in": "query", "required": false, "description": "Promedio mínimo de `entertainment` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Campo de ordenación; antepón `-` para orden descendente. Los elementos sin puntuación o sin fecha siempre van al final.", "schema": { "default": "-popularity", "x-enum-varnames": [ "POPULARITY_DESC", "POPULARITY", "SCORE_DESC", "SCORE", "RELEASE_DATE_DESC", "RELEASE_DATE", "RATING_COUNT_DESC", "RATING_COUNT" ], "type": "string", "enum": [ "-popularity", "popularity", "-score", "score", "-release_date", "release_date", "-rating_count", "rating_count" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Tamaño de página, de 1 a 100. Plan Free: hasta 10.", "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` de la página anterior.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma de los títulos y sinopsis (`en`, `pt-BR`, `es`). Recurre al inglés si falta.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Solicitudes en el periodo de cuota actual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes restantes en el periodo.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta que se reinicie la cuota (`0` para la cuota vitalicia de Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual que `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/movies/{id}": { "get": { "operationId": "getMovie", "tags": [ "Movies" ], "summary": "Obtener una película", "description": "Registro completo: metadatos, puntuación de la comunidad y promedios por categoría (`screenplay`, `acting`, `direction`, `cinematography`, `soundtrack`, `entertainment`), ids externos, tráilers y la sinopsis con licencia. Un id de otro tipo devuelve 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id del elemento (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma de los títulos y sinopsis (`en`, `pt-BR`, `es`). Recurre al inglés si falta.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Solicitudes en el periodo de cuota actual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes restantes en el periodo.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta que se reinicie la cuota (`0` para la cuota vitalicia de Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual que `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemDetail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/movies/genres": { "get": { "operationId": "listMovieGenres", "tags": [ "Movies" ], "summary": "Listar géneros de películas", "description": "Todos los géneros usados por este tipo, con su número de elementos. Usa `slug` como filtro `genre`.", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Solicitudes en el periodo de cuota actual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes restantes en el periodo.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta que se reinicie la cuota (`0` para la cuota vitalicia de Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual que `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenreList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/series": { "get": { "operationId": "listSeries", "tags": [ "Series" ], "summary": "Listar series", "description": "Pagina las series con filtros. Categorías de este tipo: `screenplay`, `acting`, `characters`, `pacing`, `production`, `entertainment` — filtra con `min_`. Envía `next_cursor` de vuelta como `cursor` hasta que sea `null`.", "parameters": [ { "name": "genre", "in": "query", "required": false, "description": "Género exacto, tal como lo devuelve el endpoint de géneros.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "year", "in": "query", "required": false, "description": "Año de lanzamiento.", "schema": { "type": "integer", "minimum": 1800, "maximum": 2100 } }, { "name": "min_score", "in": "query", "required": false, "description": "Puntuación mínima de la comunidad (oculta los elementos sin puntuación).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "max_score", "in": "query", "required": false, "description": "Puntuación máxima de la comunidad (oculta los elementos sin puntuación).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_screenplay", "in": "query", "required": false, "description": "Promedio mínimo de `screenplay` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_acting", "in": "query", "required": false, "description": "Promedio mínimo de `acting` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_characters", "in": "query", "required": false, "description": "Promedio mínimo de `characters` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_pacing", "in": "query", "required": false, "description": "Promedio mínimo de `pacing` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_production", "in": "query", "required": false, "description": "Promedio mínimo de `production` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_entertainment", "in": "query", "required": false, "description": "Promedio mínimo de `entertainment` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Campo de ordenación; antepón `-` para orden descendente. Los elementos sin puntuación o sin fecha siempre van al final.", "schema": { "default": "-popularity", "x-enum-varnames": [ "POPULARITY_DESC", "POPULARITY", "SCORE_DESC", "SCORE", "RELEASE_DATE_DESC", "RELEASE_DATE", "RATING_COUNT_DESC", "RATING_COUNT" ], "type": "string", "enum": [ "-popularity", "popularity", "-score", "score", "-release_date", "release_date", "-rating_count", "rating_count" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Tamaño de página, de 1 a 100. Plan Free: hasta 10.", "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` de la página anterior.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma de los títulos y sinopsis (`en`, `pt-BR`, `es`). Recurre al inglés si falta.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Solicitudes en el periodo de cuota actual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes restantes en el periodo.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta que se reinicie la cuota (`0` para la cuota vitalicia de Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual que `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/series/{id}": { "get": { "operationId": "getSeries", "tags": [ "Series" ], "summary": "Obtener una serie", "description": "Registro completo: metadatos, puntuación de la comunidad y promedios por categoría (`screenplay`, `acting`, `characters`, `pacing`, `production`, `entertainment`), ids externos, tráilers y la sinopsis con licencia. Un id de otro tipo devuelve 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id del elemento (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma de los títulos y sinopsis (`en`, `pt-BR`, `es`). Recurre al inglés si falta.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Solicitudes en el periodo de cuota actual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes restantes en el periodo.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta que se reinicie la cuota (`0` para la cuota vitalicia de Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual que `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemDetail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/series/genres": { "get": { "operationId": "listSeriesGenres", "tags": [ "Series" ], "summary": "Listar géneros de series", "description": "Todos los géneros usados por este tipo, con su número de elementos. Usa `slug` como filtro `genre`.", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Solicitudes en el periodo de cuota actual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes restantes en el periodo.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta que se reinicie la cuota (`0` para la cuota vitalicia de Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual que `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenreList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/books": { "get": { "operationId": "listBooks", "tags": [ "Books" ], "summary": "Listar libros", "description": "Pagina los libros con filtros. Categorías de este tipo: `plot`, `characters`, `writing`, `pacing`, `originality`, `impact` — filtra con `min_`. Envía `next_cursor` de vuelta como `cursor` hasta que sea `null`.", "parameters": [ { "name": "genre", "in": "query", "required": false, "description": "Género exacto, tal como lo devuelve el endpoint de géneros.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "year", "in": "query", "required": false, "description": "Año de lanzamiento.", "schema": { "type": "integer", "minimum": 1800, "maximum": 2100 } }, { "name": "min_score", "in": "query", "required": false, "description": "Puntuación mínima de la comunidad (oculta los elementos sin puntuación).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "max_score", "in": "query", "required": false, "description": "Puntuación máxima de la comunidad (oculta los elementos sin puntuación).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_plot", "in": "query", "required": false, "description": "Promedio mínimo de `plot` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_characters", "in": "query", "required": false, "description": "Promedio mínimo de `characters` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_writing", "in": "query", "required": false, "description": "Promedio mínimo de `writing` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_pacing", "in": "query", "required": false, "description": "Promedio mínimo de `pacing` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_originality", "in": "query", "required": false, "description": "Promedio mínimo de `originality` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_impact", "in": "query", "required": false, "description": "Promedio mínimo de `impact` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Campo de ordenación; antepón `-` para orden descendente. Los elementos sin puntuación o sin fecha siempre van al final.", "schema": { "default": "-popularity", "x-enum-varnames": [ "POPULARITY_DESC", "POPULARITY", "SCORE_DESC", "SCORE", "RELEASE_DATE_DESC", "RELEASE_DATE", "RATING_COUNT_DESC", "RATING_COUNT" ], "type": "string", "enum": [ "-popularity", "popularity", "-score", "score", "-release_date", "release_date", "-rating_count", "rating_count" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Tamaño de página, de 1 a 100. Plan Free: hasta 10.", "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` de la página anterior.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma de los títulos y sinopsis (`en`, `pt-BR`, `es`). Recurre al inglés si falta.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Solicitudes en el periodo de cuota actual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes restantes en el periodo.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta que se reinicie la cuota (`0` para la cuota vitalicia de Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual que `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/books/{id}": { "get": { "operationId": "getBook", "tags": [ "Books" ], "summary": "Obtener un libro", "description": "Registro completo: metadatos, puntuación de la comunidad y promedios por categoría (`plot`, `characters`, `writing`, `pacing`, `originality`, `impact`), ids externos, tráilers y la sinopsis con licencia. Un id de otro tipo devuelve 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id del elemento (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma de los títulos y sinopsis (`en`, `pt-BR`, `es`). Recurre al inglés si falta.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Solicitudes en el periodo de cuota actual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes restantes en el periodo.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta que se reinicie la cuota (`0` para la cuota vitalicia de Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual que `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemDetail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/books/genres": { "get": { "operationId": "listBookGenres", "tags": [ "Books" ], "summary": "Listar géneros de libros", "description": "Todos los géneros usados por este tipo, con su número de elementos. Usa `slug` como filtro `genre`.", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Solicitudes en el periodo de cuota actual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes restantes en el periodo.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta que se reinicie la cuota (`0` para la cuota vitalicia de Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual que `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenreList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/search": { "get": { "operationId": "searchItems", "tags": [ "Search" ], "summary": "Buscar elementos", "description": "Búsqueda tolerante a errores tipográficos en títulos y sinopsis de todos los idiomas, con la mejor coincidencia primero (hasta 50 resultados).", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Texto a buscar; tolerante a errores tipográficos.", "example": "zelda", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "type", "in": "query", "required": false, "description": "Restringe a un tipo (`game`, `movie`, `series`, `book`).", "schema": { "type": "string", "enum": [ "game", "movie", "series", "book" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Tamaño de página, de 1 a 50. Plan Free: hasta 10.", "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma de los títulos y sinopsis (`en`, `pt-BR`, `es`). Recurre al inglés si falta.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Solicitudes en el periodo de cuota actual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes restantes en el periodo.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta que se reinicie la cuota (`0` para la cuota vitalicia de Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual que `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/lookup": { "get": { "operationId": "lookupItem", "tags": [ "Search" ], "summary": "Buscar por id externo", "description": "Encuentra el elemento de un id de IMDb, Steam, IGDB, TMDB, ISBN-13, Open Library o Wikidata. El id debe coincidir exactamente (p. ej., `tt0111161`, `Q42`).", "parameters": [ { "name": "source", "in": "query", "required": true, "description": "Base de datos a la que pertenece el id.", "schema": { "type": "string", "enum": [ "imdb", "steam", "igdb", "tmdb", "isbn13", "openlibrary", "wikidata" ] } }, { "name": "id", "in": "query", "required": true, "description": "Id en esa base de datos.", "example": "tt0111161", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma de los títulos y sinopsis (`en`, `pt-BR`, `es`). Recurre al inglés si falta.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Solicitudes en el periodo de cuota actual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes restantes en el periodo.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta que se reinicie la cuota (`0` para la cuota vitalicia de Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual que `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemDetail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/me/usage": { "get": { "operationId": "getUsage", "tags": [ "Account" ], "summary": "Obtener uso", "description": "Plan, cuota usada en el periodo actual, créditos prepagados y límite de tasa. Cuenta como una solicitud.", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Solicitudes en el periodo de cuota actual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Solicitudes restantes en el periodo.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos hasta que se reinicie la cuota (`0` para la cuota vitalicia de Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual que `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } }, "components": { "schemas": { "ItemSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id estable del elemento.", "examples": [ "0190a1b2-0000-7000-8000-000000000001" ] }, "type": { "type": "string", "enum": [ "game", "movie", "series", "book" ], "description": "Tipo de elemento. Los endpoints de listado usan la ruta en plural (`/games`, `/movies`, `/series`, `/books`)." }, "slug": { "type": "string", "description": "Nombre apto para URL, único por tipo.", "examples": [ "the-legend-of-zelda" ] }, "title": { "type": "string", "description": "Título en el idioma solicitado; en inglés si falta." }, "release_date": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ], "description": "Primer lanzamiento (AAAA-MM-DD)." }, "year": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "score": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "Puntuación de la comunidad de 0 a 100 (media de las seis categorías). `null` hasta que el elemento tenga 5 valoraciones.", "examples": [ 87 ] }, "categories": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "description": "Promedio por categoría, de 0 a 100, `null` con menos de 5 valoraciones. Claves por tipo — `game`: `gameplay`, `fun`, `sound`, `technical`, `visual`, `storytelling`; `movie`: `screenplay`, `acting`, `direction`, `cinematography`, `soundtrack`, `entertainment`; `series`: `screenplay`, `acting`, `characters`, `pacing`, `production`, `entertainment`; `book`: `plot`, `characters`, `writing`, `pacing`, `originality`, `impact`.", "examples": [ { "gameplay": 90, "fun": 88, "sound": 85, "technical": 84, "visual": 89, "storytelling": 86 } ] }, "rating_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Número de valoraciones de la comunidad." }, "genres": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Plataformas (solo juegos; vacío en los demás tipos)." }, "cover_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "url": { "type": "string", "format": "uri", "description": "Página pública del elemento en el sitio, en el idioma solicitado." } }, "required": [ "id", "type", "slug", "title", "release_date", "year", "score", "categories", "rating_count", "genres", "platforms", "cover_url", "url" ], "additionalProperties": false, "description": "Elemento resumido usado en listados y resultados de búsqueda." }, "ItemDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id estable del elemento.", "examples": [ "0190a1b2-0000-7000-8000-000000000001" ] }, "type": { "type": "string", "enum": [ "game", "movie", "series", "book" ], "description": "Tipo de elemento. Los endpoints de listado usan la ruta en plural (`/games`, `/movies`, `/series`, `/books`)." }, "slug": { "type": "string", "description": "Nombre apto para URL, único por tipo.", "examples": [ "the-legend-of-zelda" ] }, "title": { "type": "string", "description": "Título en el idioma solicitado; en inglés si falta." }, "release_date": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ], "description": "Primer lanzamiento (AAAA-MM-DD)." }, "year": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "score": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "Puntuación de la comunidad de 0 a 100 (media de las seis categorías). `null` hasta que el elemento tenga 5 valoraciones.", "examples": [ 87 ] }, "categories": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "description": "Promedio por categoría, de 0 a 100, `null` con menos de 5 valoraciones. Claves por tipo — `game`: `gameplay`, `fun`, `sound`, `technical`, `visual`, `storytelling`; `movie`: `screenplay`, `acting`, `direction`, `cinematography`, `soundtrack`, `entertainment`; `series`: `screenplay`, `acting`, `characters`, `pacing`, `production`, `entertainment`; `book`: `plot`, `characters`, `writing`, `pacing`, `originality`, `impact`.", "examples": [ { "gameplay": 90, "fun": 88, "sound": 85, "technical": 84, "visual": 89, "storytelling": 86 } ] }, "rating_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Número de valoraciones de la comunidad." }, "genres": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Plataformas (solo juegos; vacío en los demás tipos)." }, "cover_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "url": { "type": "string", "format": "uri", "description": "Página pública del elemento en el sitio, en el idioma solicitado." }, "locale": { "type": "string", "enum": [ "en", "pt-BR", "es" ] }, "translation_fallback": { "type": "boolean", "description": "Verdadero cuando el idioma solicitado no tenía título o sinopsis y se usó el inglés." }, "synopsis": { "anyOf": [ { "$ref": "#/components/schemas/Synopsis" }, { "type": "null" } ] }, "external_ids": { "type": "object", "properties": { "wikidata": { "type": "string" }, "imdb": { "type": "string" }, "igdb": { "type": "string" }, "steam": { "type": "string" }, "tmdb": { "type": "string" }, "isbn13": { "type": "string" }, "openlibrary": { "type": "string" }, "hltb": { "type": "string" }, "goodreads": { "type": "string" }, "metacritic": { "type": "string" }, "rottentomatoes": { "type": "string" }, "epic": { "type": "string" }, "gog": { "type": "string" }, "skoob": { "type": "string" } }, "required": [ "wikidata" ], "additionalProperties": false, "description": "Identificadores del elemento en otras bases de datos. Solo aparecen los ids conocidos.", "examples": [ { "wikidata": "Q12345", "igdb": "the-legend-of-zelda", "steam": "123456" } ] }, "trailers": { "type": "array", "items": { "type": "object", "properties": { "youtube_id": { "type": "string" }, "title": { "type": [ "string", "null" ] } }, "required": [ "youtube_id", "title" ], "additionalProperties": false }, "description": "Ids de vídeos de YouTube; insértalos como `https://www.youtube-nocookie.com/embed/{youtube_id}`." }, "creators": { "type": "array", "items": { "type": "string" }, "description": "Desarrolladores, directores, showrunners o autores." }, "countries": { "type": "array", "items": { "type": "string" } }, "runtime_minutes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "pages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seasons": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "episodes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "time_to_beat": { "anyOf": [ { "$ref": "#/components/schemas/TimeToBeat" }, { "type": "null" } ], "description": "Solo juegos; `null` en los demás tipos." } }, "required": [ "id", "type", "slug", "title", "release_date", "year", "score", "categories", "rating_count", "genres", "platforms", "cover_url", "url", "locale", "translation_fallback", "synopsis", "external_ids", "trailers", "creators", "countries", "runtime_minutes", "pages", "seasons", "episodes", "time_to_beat" ], "additionalProperties": false, "description": "Elemento completo: metadatos, puntuaciones, ids externos, tráilers y sinopsis." }, "Synopsis": { "type": "object", "properties": { "text": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "pt-BR", "es" ], "description": "Idioma en que está escrito el texto." }, "license": { "description": "Licencia del texto (p. ej., `CC BY-SA 4.0`). Atribúyela cuando muestres la sinopsis.", "type": [ "string", "null" ] }, "source_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "De dónde procede el texto (para la atribución)." } }, "required": [ "text", "locale", "license", "source_url" ], "additionalProperties": false, "description": "Sinopsis con la licencia que debes respetar al mostrarla." }, "TimeToBeat": { "type": "object", "properties": { "main": { "type": "object", "properties": { "median_hours": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Mediana de horas indicada por quienes completaron el juego (1 decimal). `null` con menos de 3 reportes.", "examples": [ 42.5 ] }, "reports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Número de jugadores que reportaron este estilo." } }, "required": [ "median_hours", "reports" ], "additionalProperties": false }, "extras": { "type": "object", "properties": { "median_hours": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Mediana de horas indicada por quienes completaron el juego (1 decimal). `null` con menos de 3 reportes.", "examples": [ 42.5 ] }, "reports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Número de jugadores que reportaron este estilo." } }, "required": [ "median_hours", "reports" ], "additionalProperties": false }, "completionist": { "type": "object", "properties": { "median_hours": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Mediana de horas indicada por quienes completaron el juego (1 decimal). `null` con menos de 3 reportes.", "examples": [ 42.5 ] }, "reports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Número de jugadores que reportaron este estilo." } }, "required": [ "median_hours", "reports" ], "additionalProperties": false } }, "required": [ "main", "extras", "completionist" ], "additionalProperties": false, "description": "Tiempo para completar por estilo de juego, aportado por la comunidad: historia principal, principal + extras, completista.", "examples": [ { "main": { "median_hours": 42.5, "reports": 12 }, "extras": { "median_hours": 61, "reports": 7 }, "completionist": { "median_hours": null, "reports": 2 } } ] }, "ItemList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ItemSummary" } }, "next_cursor": { "description": "Envíalo como `cursor` para obtener la página siguiente. `null` en la última página.", "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "additionalProperties": false, "description": "Una página de elementos." }, "SearchResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ItemSummary" } } }, "required": [ "data" ], "additionalProperties": false, "description": "Mejores coincidencias primero. La búsqueda no está paginada." }, "GenreList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "Valor exacto que se pasa en `genre`.", "examples": [ "Adventure" ] }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Elementos de este tipo con el género." } }, "required": [ "slug", "count" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false, "description": "Géneros de un tipo, los más comunes primero." }, "Usage": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "free", "pro", "business" ] }, "quota": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "used": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "remaining": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "period": { "type": "string", "enum": [ "lifetime", "month" ], "description": "`lifetime` en Free (100 solicitudes en total); `month` en los planes de pago (mes natural en UTC)." }, "resets_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "Próximo reinicio; `null` para cuotas vitalicias." } }, "required": [ "limit", "used", "remaining", "period", "resets_at" ], "additionalProperties": false }, "credits": { "type": "object", "properties": { "balance": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Solicitudes prepagadas que se usan cuando se agota la cuota (planes de pago)." } }, "required": [ "balance" ], "additionalProperties": false }, "rate_limit": { "type": "object", "properties": { "requests_per_second": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "requests_per_second" ], "additionalProperties": false } }, "required": [ "plan", "quota", "credits", "rate_limit" ], "additionalProperties": false, "description": "Cuota, créditos y límite de tasa de la cuenta de la clave. Esta llamada cuenta como una solicitud." }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "format": "uri", "description": "Enlace a la documentación de este error." }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "detail": { "type": "string", "description": "Qué salió mal y cómo corregirlo." }, "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "payment_required", "forbidden", "not_found", "rate_limited", "internal_error", "service_unavailable" ], "description": "Código de error estable y legible por máquina." }, "request_id": { "type": "string", "description": "Indícalo al contactar con el soporte." }, "errors": { "description": "Parámetros no válidos (solo en `bad_request`).", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } }, "plan": { "type": "string", "enum": [ "free", "pro", "business" ] }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ], "additionalProperties": false, "description": "Detalles de problema RFC 9457 (`application/problem+json`)." } }, "responses": { "BadRequest": { "description": "Parámetro de query o cursor no válido, o un `limit` mayor que el tamaño de página de tu plan.", "headers": { "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hexascore.app/docs/errors#bad_request", "title": "Invalid request", "status": 400, "detail": "Invalid query parameter, cursor, or a `limit` above your plan's page size.", "code": "bad_request", "request_id": "5f0c8d3e-4b7a-4f43-9a51-2a8c4f3f9b10" } } } }, "Unauthorized": { "description": "Clave de API ausente, mal formada, desconocida o revocada.", "headers": { "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hexascore.app/docs/errors#unauthorized", "title": "Missing or invalid API key", "status": 401, "detail": "Missing, malformed, unknown or revoked API key.", "code": "unauthorized", "request_id": "5f0c8d3e-4b7a-4f43-9a51-2a8c4f3f9b10" } } } }, "PaymentRequired": { "description": "Cuota (y créditos, en los planes de pago) agotada. Mejora tu plan o compra créditos.", "headers": { "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hexascore.app/docs/errors#payment_required", "title": "Quota exhausted", "status": 402, "detail": "Quota (and credits, on paid plans) exhausted. Upgrade or buy credits.", "code": "payment_required", "request_id": "5f0c8d3e-4b7a-4f43-9a51-2a8c4f3f9b10" } } } }, "Forbidden": { "description": "La cuenta propietaria de la clave está suspendida.", "headers": { "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hexascore.app/docs/errors#forbidden", "title": "Forbidden", "status": 403, "detail": "The account that owns the key is suspended.", "code": "forbidden", "request_id": "5f0c8d3e-4b7a-4f43-9a51-2a8c4f3f9b10" } } } }, "NotFound": { "description": "No existe ese elemento, tipo o ruta.", "headers": { "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hexascore.app/docs/errors#not_found", "title": "Not found", "status": 404, "detail": "No such item, type or route.", "code": "not_found", "request_id": "5f0c8d3e-4b7a-4f43-9a51-2a8c4f3f9b10" } } } }, "RateLimited": { "description": "Demasiadas solicitudes por segundo. Espera `Retry-After` segundos.", "headers": { "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Segundos de espera.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hexascore.app/docs/errors#rate_limited", "title": "Too many requests", "status": 429, "detail": "Too many requests per second. Wait `Retry-After` seconds.", "code": "rate_limited", "request_id": "5f0c8d3e-4b7a-4f43-9a51-2a8c4f3f9b10" } } } }, "InternalError": { "description": "Error inesperado. La solicitud no se descontó de tu cuota.", "headers": { "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hexascore.app/docs/errors#internal_error", "title": "Internal error", "status": 500, "detail": "Unexpected error. The request was not counted against your quota.", "code": "internal_error", "request_id": "5f0c8d3e-4b7a-4f43-9a51-2a8c4f3f9b10" } } } }, "ServiceUnavailable": { "description": "No disponible temporalmente. Reintenta después de `Retry-After` segundos.", "headers": { "X-Request-Id": { "description": "Id de esta solicitud; indícalo al soporte.", "schema": { "type": "string" } }, "Retry-After": { "description": "Segundos de espera.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://hexascore.app/docs/errors#service_unavailable", "title": "Service unavailable", "status": 503, "detail": "Temporarily unavailable. Retry after `Retry-After` seconds.", "code": "service_unavailable", "request_id": "5f0c8d3e-4b7a-4f43-9a51-2a8c4f3f9b10" } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "hx_live_<32 chars>", "description": "Clave de API de /profile/api, enviada como `Authorization: Bearer hx_live_…`." } } } }