{ "openapi": "3.1.0", "info": { "title": "HexaScore API", "version": "1.0.0", "summary": "Notas da comunidade para jogos, filmes, séries e livros.", "description": "API REST somente leitura sobre o catálogo do HexaScore: cada item traz uma nota da comunidade de 0 a 100 e seis médias por categoria.\n\n- **Autenticação**: `Authorization: Bearer hx_live_…` — crie uma chave em `/profile/api`.\n- **Formato**: JSON, campos em `snake_case`, datas ISO 8601. Erros seguem a RFC 9457 (`application/problem+json`) com um `code` estável.\n- **Paginação**: por cursor — envie `next_cursor` de volta como `cursor`.\n- **Planos**: Free = 100 requisições no total, 10 itens por página, 1 req/s. Pro e Business têm cotas mensais, 100 itens por página e créditos pré-pagos.\n\nGuias: 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": "Produção" }, { "url": "/api/v1", "description": "Este deploy (a mesma API em /api/v1)" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Games", "description": "Jogos: listagem, detalhe e gêneros." }, { "name": "Movies", "description": "Filmes: listagem, detalhe e gêneros." }, { "name": "Series", "description": "Séries: listagem, detalhe e gêneros." }, { "name": "Books", "description": "Livros: listagem, detalhe e gêneros." }, { "name": "Search", "description": "Encontre itens por texto ou por um id de outra base de dados." }, { "name": "Account", "description": "Sua cota, créditos e limite de taxa." } ], "externalDocs": { "description": "Guias", "url": "https://hexascore.app/docs" }, "paths": { "/games": { "get": { "operationId": "listGames", "tags": [ "Games" ], "summary": "Listar jogos", "description": "Pagina os jogos com filtros. Categorias deste tipo: `gameplay`, `fun`, `sound`, `technical`, `visual`, `storytelling` — filtre com `min_`. Envie `next_cursor` de volta como `cursor` até ele ser `null`.", "parameters": [ { "name": "genre", "in": "query", "required": false, "description": "Gênero exato, como retornado pelo endpoint de gêneros.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "platform", "in": "query", "required": false, "description": "Nome exato da plataforma.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "year", "in": "query", "required": false, "description": "Ano de lançamento.", "schema": { "type": "integer", "minimum": 1800, "maximum": 2100 } }, { "name": "min_score", "in": "query", "required": false, "description": "Nota mínima da comunidade (oculta itens sem nota).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "max_score", "in": "query", "required": false, "description": "Nota máxima da comunidade (oculta itens sem nota).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_gameplay", "in": "query", "required": false, "description": "Média mínima de `gameplay` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_fun", "in": "query", "required": false, "description": "Média mínima de `fun` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_sound", "in": "query", "required": false, "description": "Média mínima de `sound` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_technical", "in": "query", "required": false, "description": "Média mínima de `technical` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_visual", "in": "query", "required": false, "description": "Média mínima de `visual` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_storytelling", "in": "query", "required": false, "description": "Média mínima de `storytelling` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Campo de ordenação; prefixe com `-` para ordem decrescente. Itens sem nota/sem data vêm sempre por último.", "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": "Tamanho da página, 1 a 100. Plano Free: até 10.", "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` da página anterior.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma dos títulos e sinopses (`en`, `pt-BR`, `es`). Usa inglês quando não houver tradução.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requisições no período de cota atual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes no período.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a cota reiniciar (`0` para a cota vitalícia do Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual a `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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": "Obter um jogo", "description": "Registro completo: metadados, nota da comunidade e médias por categoria (`gameplay`, `fun`, `sound`, `technical`, `visual`, `storytelling`), ids externos, trailers e a sinopse licenciada. Um id de outro tipo retorna 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id do item (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma dos títulos e sinopses (`en`, `pt-BR`, `es`). Usa inglês quando não houver tradução.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requisições no período de cota atual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes no período.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a cota reiniciar (`0` para a cota vitalícia do Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual a `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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 jogos", "description": "Todos os gêneros usados por este tipo, com a contagem de itens. Use `slug` como filtro `genre`.", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requisições no período de cota atual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes no período.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a cota reiniciar (`0` para a cota vitalícia do Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual a `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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 filmes", "description": "Pagina os filmes com filtros. Categorias deste tipo: `screenplay`, `acting`, `direction`, `cinematography`, `soundtrack`, `entertainment` — filtre com `min_`. Envie `next_cursor` de volta como `cursor` até ele ser `null`.", "parameters": [ { "name": "genre", "in": "query", "required": false, "description": "Gênero exato, como retornado pelo endpoint de gêneros.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "year", "in": "query", "required": false, "description": "Ano de lançamento.", "schema": { "type": "integer", "minimum": 1800, "maximum": 2100 } }, { "name": "min_score", "in": "query", "required": false, "description": "Nota mínima da comunidade (oculta itens sem nota).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "max_score", "in": "query", "required": false, "description": "Nota máxima da comunidade (oculta itens sem nota).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_screenplay", "in": "query", "required": false, "description": "Média mínima de `screenplay` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_acting", "in": "query", "required": false, "description": "Média mínima de `acting` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_direction", "in": "query", "required": false, "description": "Média mínima de `direction` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_cinematography", "in": "query", "required": false, "description": "Média mínima de `cinematography` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_soundtrack", "in": "query", "required": false, "description": "Média mínima de `soundtrack` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_entertainment", "in": "query", "required": false, "description": "Média mínima de `entertainment` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Campo de ordenação; prefixe com `-` para ordem decrescente. Itens sem nota/sem data vêm sempre por último.", "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": "Tamanho da página, 1 a 100. Plano Free: até 10.", "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` da página anterior.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma dos títulos e sinopses (`en`, `pt-BR`, `es`). Usa inglês quando não houver tradução.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requisições no período de cota atual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes no período.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a cota reiniciar (`0` para a cota vitalícia do Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual a `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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": "Obter um filme", "description": "Registro completo: metadados, nota da comunidade e médias por categoria (`screenplay`, `acting`, `direction`, `cinematography`, `soundtrack`, `entertainment`), ids externos, trailers e a sinopse licenciada. Um id de outro tipo retorna 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id do item (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma dos títulos e sinopses (`en`, `pt-BR`, `es`). Usa inglês quando não houver tradução.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requisições no período de cota atual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes no período.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a cota reiniciar (`0` para a cota vitalícia do Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual a `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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 filmes", "description": "Todos os gêneros usados por este tipo, com a contagem de itens. Use `slug` como filtro `genre`.", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requisições no período de cota atual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes no período.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a cota reiniciar (`0` para a cota vitalícia do Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual a `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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 séries", "description": "Pagina as séries com filtros. Categorias deste tipo: `screenplay`, `acting`, `characters`, `pacing`, `production`, `entertainment` — filtre com `min_`. Envie `next_cursor` de volta como `cursor` até ele ser `null`.", "parameters": [ { "name": "genre", "in": "query", "required": false, "description": "Gênero exato, como retornado pelo endpoint de gêneros.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "year", "in": "query", "required": false, "description": "Ano de lançamento.", "schema": { "type": "integer", "minimum": 1800, "maximum": 2100 } }, { "name": "min_score", "in": "query", "required": false, "description": "Nota mínima da comunidade (oculta itens sem nota).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "max_score", "in": "query", "required": false, "description": "Nota máxima da comunidade (oculta itens sem nota).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_screenplay", "in": "query", "required": false, "description": "Média mínima de `screenplay` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_acting", "in": "query", "required": false, "description": "Média mínima de `acting` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_characters", "in": "query", "required": false, "description": "Média mínima de `characters` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_pacing", "in": "query", "required": false, "description": "Média mínima de `pacing` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_production", "in": "query", "required": false, "description": "Média mínima de `production` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_entertainment", "in": "query", "required": false, "description": "Média mínima de `entertainment` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Campo de ordenação; prefixe com `-` para ordem decrescente. Itens sem nota/sem data vêm sempre por último.", "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": "Tamanho da página, 1 a 100. Plano Free: até 10.", "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` da página anterior.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma dos títulos e sinopses (`en`, `pt-BR`, `es`). Usa inglês quando não houver tradução.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requisições no período de cota atual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes no período.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a cota reiniciar (`0` para a cota vitalícia do Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual a `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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": "Obter uma série", "description": "Registro completo: metadados, nota da comunidade e médias por categoria (`screenplay`, `acting`, `characters`, `pacing`, `production`, `entertainment`), ids externos, trailers e a sinopse licenciada. Um id de outro tipo retorna 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id do item (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma dos títulos e sinopses (`en`, `pt-BR`, `es`). Usa inglês quando não houver tradução.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requisições no período de cota atual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes no período.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a cota reiniciar (`0` para a cota vitalícia do Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual a `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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 séries", "description": "Todos os gêneros usados por este tipo, com a contagem de itens. Use `slug` como filtro `genre`.", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requisições no período de cota atual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes no período.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a cota reiniciar (`0` para a cota vitalícia do Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual a `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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 livros", "description": "Pagina os livros com filtros. Categorias deste tipo: `plot`, `characters`, `writing`, `pacing`, `originality`, `impact` — filtre com `min_`. Envie `next_cursor` de volta como `cursor` até ele ser `null`.", "parameters": [ { "name": "genre", "in": "query", "required": false, "description": "Gênero exato, como retornado pelo endpoint de gêneros.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "year", "in": "query", "required": false, "description": "Ano de lançamento.", "schema": { "type": "integer", "minimum": 1800, "maximum": 2100 } }, { "name": "min_score", "in": "query", "required": false, "description": "Nota mínima da comunidade (oculta itens sem nota).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "max_score", "in": "query", "required": false, "description": "Nota máxima da comunidade (oculta itens sem nota).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_plot", "in": "query", "required": false, "description": "Média mínima de `plot` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_characters", "in": "query", "required": false, "description": "Média mínima de `characters` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_writing", "in": "query", "required": false, "description": "Média mínima de `writing` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_pacing", "in": "query", "required": false, "description": "Média mínima de `pacing` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_originality", "in": "query", "required": false, "description": "Média mínima de `originality` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "min_impact", "in": "query", "required": false, "description": "Média mínima de `impact` (0 a 100).", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Campo de ordenação; prefixe com `-` para ordem decrescente. Itens sem nota/sem data vêm sempre por último.", "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": "Tamanho da página, 1 a 100. Plano Free: até 10.", "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` da página anterior.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma dos títulos e sinopses (`en`, `pt-BR`, `es`). Usa inglês quando não houver tradução.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requisições no período de cota atual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes no período.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a cota reiniciar (`0` para a cota vitalícia do Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual a `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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": "Obter um livro", "description": "Registro completo: metadados, nota da comunidade e médias por categoria (`plot`, `characters`, `writing`, `pacing`, `originality`, `impact`), ids externos, trailers e a sinopse licenciada. Um id de outro tipo retorna 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id do item (UUID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma dos títulos e sinopses (`en`, `pt-BR`, `es`). Usa inglês quando não houver tradução.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requisições no período de cota atual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes no período.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a cota reiniciar (`0` para a cota vitalícia do Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual a `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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 livros", "description": "Todos os gêneros usados por este tipo, com a contagem de itens. Use `slug` como filtro `genre`.", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requisições no período de cota atual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes no período.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a cota reiniciar (`0` para a cota vitalícia do Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual a `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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 itens", "description": "Busca tolerante a erros de digitação em títulos e sinopses de todos os idiomas, com o melhor resultado primeiro (até 50 resultados).", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Texto a buscar; tolerante a erros de digitação.", "example": "zelda", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "type", "in": "query", "required": false, "description": "Restringe a um tipo (`game`, `movie`, `series`, `book`).", "schema": { "type": "string", "enum": [ "game", "movie", "series", "book" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Tamanho da página, 1 a 50. Plano Free: até 10.", "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma dos títulos e sinopses (`en`, `pt-BR`, `es`). Usa inglês quando não houver tradução.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requisições no período de cota atual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes no período.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a cota reiniciar (`0` para a cota vitalícia do Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual a `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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": "Encontra o item de um id do IMDb, Steam, IGDB, TMDB, ISBN-13, Open Library ou Wikidata. O id precisa ser exato (ex.: `tt0111161`, `Q42`).", "parameters": [ { "name": "source", "in": "query", "required": true, "description": "Base de dados à qual o id pertence.", "schema": { "type": "string", "enum": [ "imdb", "steam", "igdb", "tmdb", "isbn13", "openlibrary", "wikidata" ] } }, { "name": "id", "in": "query", "required": true, "description": "Id nessa base de dados.", "example": "tt0111161", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "locale", "in": "query", "required": false, "description": "Idioma dos títulos e sinopses (`en`, `pt-BR`, `es`). Usa inglês quando não houver tradução.", "schema": { "default": "en", "type": "string", "enum": [ "en", "pt-BR", "es" ] } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requisições no período de cota atual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes no período.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a cota reiniciar (`0` para a cota vitalícia do Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual a `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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": "Obter uso", "description": "Plano, cota usada no período atual, créditos pré-pagos e limite de taxa. Conta como uma requisição.", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requisições no período de cota atual.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requisições restantes no período.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a cota reiniciar (`0` para a cota vitalícia do Free).", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Igual a `RateLimit-Remaining`.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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 estável do item.", "examples": [ "0190a1b2-0000-7000-8000-000000000001" ] }, "type": { "type": "string", "enum": [ "game", "movie", "series", "book" ], "description": "Tipo do item. Os endpoints de listagem usam o caminho no plural (`/games`, `/movies`, `/series`, `/books`)." }, "slug": { "type": "string", "description": "Nome seguro para URL, único por tipo.", "examples": [ "the-legend-of-zelda" ] }, "title": { "type": "string", "description": "Título no idioma pedido; em inglês quando não houver tradução." }, "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": "Primeiro lançamento (AAAA-MM-DD)." }, "year": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "score": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "Nota da comunidade de 0 a 100 (média das seis categorias). `null` até o item ter 5 avaliações.", "examples": [ 87 ] }, "categories": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "description": "Média por categoria, 0 a 100, `null` com menos de 5 avaliações. Chaves 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 avaliações da comunidade." }, "genres": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Plataformas (só jogos; vazio nos outros tipos)." }, "cover_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "url": { "type": "string", "format": "uri", "description": "Página pública do item no site, no idioma pedido." } }, "required": [ "id", "type", "slug", "title", "release_date", "year", "score", "categories", "rating_count", "genres", "platforms", "cover_url", "url" ], "additionalProperties": false, "description": "Item resumido usado em listagens e resultados de busca." }, "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 estável do item.", "examples": [ "0190a1b2-0000-7000-8000-000000000001" ] }, "type": { "type": "string", "enum": [ "game", "movie", "series", "book" ], "description": "Tipo do item. Os endpoints de listagem usam o caminho no plural (`/games`, `/movies`, `/series`, `/books`)." }, "slug": { "type": "string", "description": "Nome seguro para URL, único por tipo.", "examples": [ "the-legend-of-zelda" ] }, "title": { "type": "string", "description": "Título no idioma pedido; em inglês quando não houver tradução." }, "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": "Primeiro lançamento (AAAA-MM-DD)." }, "year": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "score": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "Nota da comunidade de 0 a 100 (média das seis categorias). `null` até o item ter 5 avaliações.", "examples": [ 87 ] }, "categories": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "description": "Média por categoria, 0 a 100, `null` com menos de 5 avaliações. Chaves 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 avaliações da comunidade." }, "genres": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Plataformas (só jogos; vazio nos outros tipos)." }, "cover_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "url": { "type": "string", "format": "uri", "description": "Página pública do item no site, no idioma pedido." }, "locale": { "type": "string", "enum": [ "en", "pt-BR", "es" ] }, "translation_fallback": { "type": "boolean", "description": "Verdadeiro quando o idioma pedido não tinha título ou sinopse e o inglês foi usado." }, "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 do item em outras bases de dados. Só os ids conhecidos aparecem.", "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 do YouTube; incorpore como `https://www.youtube-nocookie.com/embed/{youtube_id}`." }, "creators": { "type": "array", "items": { "type": "string" }, "description": "Desenvolvedores, diretores, showrunners ou 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": "Só jogos; `null` nos outros 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": "Item completo: metadados, notas, ids externos, trailers e sinopse." }, "Synopsis": { "type": "object", "properties": { "text": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "pt-BR", "es" ], "description": "Idioma em que o texto está escrito." }, "license": { "description": "Licença do texto (ex.: `CC BY-SA 4.0`). Dê a atribuição ao exibir a sinopse.", "type": [ "string", "null" ] }, "source_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "De onde o texto vem (para atribuição)." } }, "required": [ "text", "locale", "license", "source_url" ], "additionalProperties": false, "description": "Sinopse com a licença que você deve respeitar ao exibi-la." }, "TimeToBeat": { "type": "object", "properties": { "main": { "type": "object", "properties": { "median_hours": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Mediana de horas relatada por quem zerou o jogo (1 casa decimal). `null` com menos de 3 relatos.", "examples": [ 42.5 ] }, "reports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Número de jogadores que relataram 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 relatada por quem zerou o jogo (1 casa decimal). `null` com menos de 3 relatos.", "examples": [ 42.5 ] }, "reports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Número de jogadores que relataram 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 relatada por quem zerou o jogo (1 casa decimal). `null` com menos de 3 relatos.", "examples": [ 42.5 ] }, "reports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Número de jogadores que relataram este estilo." } }, "required": [ "median_hours", "reports" ], "additionalProperties": false } }, "required": [ "main", "extras", "completionist" ], "additionalProperties": false, "description": "Tempo para zerar por estilo de jogo, informado pela comunidade: história 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": "Envie como `cursor` para obter a próxima página. `null` na última página.", "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "additionalProperties": false, "description": "Uma página de itens." }, "SearchResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ItemSummary" } } }, "required": [ "data" ], "additionalProperties": false, "description": "Melhores resultados primeiro. A busca não é paginada." }, "GenreList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "Valor exato a passar em `genre`.", "examples": [ "Adventure" ] }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Itens deste tipo com o gênero." } }, "required": [ "slug", "count" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false, "description": "Gêneros de um tipo, os mais comuns primeiro." }, "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` no Free (100 requisições no total); `month` nos planos pagos (mês civil em 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 reinício; `null` para cotas vitalícias." } }, "required": [ "limit", "used", "remaining", "period", "resets_at" ], "additionalProperties": false }, "credits": { "type": "object", "properties": { "balance": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Requisições pré-pagas usadas depois que a cota acaba (planos pagos)." } }, "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": "Cota, créditos e limite de taxa da conta da chave. Esta chamada conta como uma requisição." }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "format": "uri", "description": "Link para a documentação deste erro." }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "detail": { "type": "string", "description": "O que deu errado e como corrigir." }, "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "payment_required", "forbidden", "not_found", "rate_limited", "internal_error", "service_unavailable" ], "description": "Código de erro estável, legível por máquina." }, "request_id": { "type": "string", "description": "Informe-o ao entrar em contato com o suporte." }, "errors": { "description": "Parâmetros inválidos (só em `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": "Detalhes de problema RFC 9457 (`application/problem+json`)." } }, "responses": { "BadRequest": { "description": "Parâmetro de query ou cursor inválido, ou `limit` acima do tamanho de página do seu plano.", "headers": { "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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": "Chave de API ausente, malformada, desconhecida ou revogada.", "headers": { "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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": "Cota (e créditos, nos planos pagos) esgotada. Faça upgrade ou compre créditos.", "headers": { "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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": "A conta dona da chave está suspensa.", "headers": { "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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": "Item, tipo ou rota inexistente.", "headers": { "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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": "Requisições demais por segundo. Aguarde `Retry-After` segundos.", "headers": { "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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": "Erro inesperado. A requisição não foi descontada da sua cota.", "headers": { "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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": "Temporariamente indisponível. Tente de novo após `Retry-After` segundos.", "headers": { "X-Request-Id": { "description": "Id desta requisição; informe-o ao suporte.", "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": "Chave de API de /profile/api, enviada como `Authorization: Bearer hx_live_…`." } } } }