{"openapi":"3.1.0","info":{"title":"Aperta Play — API pública","version":"1.0.0","description":"Leia e grave o que a pessoa assiste: histórico, \"Quero assistir\", notas e o \"assistindo agora\" de players. Grátis. Autentique com um token pessoal (criado em /desenvolvedores) ou com OAuth 2.0 + PKCE. Os títulos são os da TMDB (tmdb_id); quem não tem o id pode mandar o do IMDb/TVDB ou o nome.","contact":{"name":"Aperta Play","url":"https://www.apertaplay.com/desenvolvedores"}},"servers":[{"url":"https://www.apertaplay.com/api/v1"}],"security":[{"token":[]},{"oauth":[]}],"components":{"securitySchemes":{"token":{"type":"http","scheme":"bearer","description":"Token pessoal \"ap_…\" (escopo leitura, ou leitura e escrita), no cabeçalho Authorization: Bearer."},"oauth":{"type":"oauth2","description":"Para apps de terceiros: Authorization Code com PKCE (S256). Apps públicos não têm segredo.","flows":{"authorizationCode":{"authorizationUrl":"https://www.apertaplay.com/oauth/autorizar","tokenUrl":"https://www.apertaplay.com/api/oauth/token","scopes":{"leitura":"Ler o histórico, a lista e as notas.","escrita":"Gravar histórico, lista, notas e scrobble."}}}}},"schemas":{"Erro":{"type":"object","required":["erro","mensagem"],"properties":{"erro":{"type":"string","description":"Código do erro (ex.: titulo_invalido, nao_encontrado)."},"mensagem":{"type":"string","description":"Explicação em português."}}},"ItemBusca":{"type":"object","properties":{"tipo":{"type":"string","enum":["movie","tv"],"description":"movie (filme) ou tv (série)."},"tmdb_id":{"type":"integer","minimum":1,"description":"Id do título na TMDB."},"titulo":{"type":"string"},"ano":{"type":["integer","null"]},"poster":{"type":["string","null"],"description":"Caminho da imagem na TMDB (https://image.tmdb.org/t/p/w500{poster})."}}},"ItemHistorico":{"type":"object","required":["tipo","tmdb_id","assistido_em"],"properties":{"tipo":{"type":"string","enum":["movie","tv"],"description":"movie (filme) ou tv (série)."},"tmdb_id":{"type":"integer","minimum":1,"description":"Id do título na TMDB."},"temporada":{"type":"integer","minimum":0,"maximum":500},"episodio":{"type":"integer","minimum":1,"maximum":5000},"assistido_em":{"type":"string","format":"date-time"}}},"Alvo":{"type":"object","required":["tipo"],"description":"O título: tmdb_id, ou (sem ele) imdb_id, tvdb_id ou o nome. Episódio: temporada e episodio.","properties":{"tipo":{"type":"string","enum":["movie","tv"],"description":"movie (filme) ou tv (série)."},"tmdb_id":{"type":"integer","minimum":1,"description":"Id do título na TMDB."},"temporada":{"type":"integer","minimum":0,"maximum":500},"episodio":{"type":"integer","minimum":1,"maximum":5000},"imdb_id":{"type":"string","pattern":"^tt\\d{5,10}$","description":"Sem tmdb_id: id do IMDb do filme ou do episódio."},"tvdb_id":{"type":"integer","minimum":1,"description":"Sem tmdb_id: id do TVDB do episódio."},"titulo":{"type":"string","maxLength":200,"description":"Sem ids: nome do filme."},"ano":{"type":"integer","minimum":1874,"maximum":2100,"description":"Ano do filme (ajuda a achar pelo nome)."},"serie":{"type":"string","maxLength":200,"description":"Sem ids: nome da série (com temporada e episodio)."}}}}},"paths":{"/eu":{"get":{"summary":"Quem é o dono do token","security":[{"token":[]},{"oauth":["leitura"]}],"responses":{"200":{"description":"Conta e escopos.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"usuario":{"type":["string","null"],"description":"@nome público, se houver."},"escopos":{"type":"array","items":{"type":"string","enum":["leitura","escrita"]}}}}}}},"401":{"description":"Token ausente, inválido ou revogado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/busca":{"get":{"summary":"Acha o tmdb_id de um filme ou série pelo nome","security":[{"token":[]},{"oauth":["leitura"]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":100}}],"responses":{"200":{"description":"Até 10 resultados.","content":{"application/json":{"schema":{"type":"object","properties":{"itens":{"type":"array","items":{"$ref":"#/components/schemas/ItemBusca"}}}}}}},"400":{"description":"Pedido inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Token ausente, inválido ou revogado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"502":{"description":"A TMDB não respondeu; tente de novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/historico":{"get":{"summary":"Histórico, do mais recente ao mais antigo (100 por página)","security":[{"token":[]},{"oauth":["leitura"]}],"parameters":[{"name":"pagina","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Uma página do histórico.","content":{"application/json":{"schema":{"type":"object","properties":{"pagina":{"type":"integer"},"tem_mais":{"type":"boolean"},"itens":{"type":"array","items":{"$ref":"#/components/schemas/ItemHistorico"}}}}}}},"401":{"description":"Token ausente, inválido ou revogado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}},"post":{"summary":"Registra que assistiu (filme ou episódio)","security":[{"token":[]},{"oauth":["escrita"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Alvo"},{"type":"object","properties":{"assistido_em":{"type":"string","format":"date-time","description":"Padrão: agora."}}}]},"examples":{"filme":{"value":{"tipo":"movie","tmdb_id":550}},"episodio":{"value":{"tipo":"tv","tmdb_id":1396,"temporada":1,"episodio":2}},"porImdb":{"value":{"tipo":"movie","imdb_id":"tt0137523"}}}}}},"responses":{"200":{"description":"Já estava gravado.","content":{"application/json":{"schema":{"type":"object","properties":{"gravado":{"type":"boolean"}}}}}},"201":{"description":"Gravado.","content":{"application/json":{"schema":{"type":"object","properties":{"gravado":{"type":"boolean"}}}}}},"400":{"description":"Pedido inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Token ausente, inválido ou revogado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"O token não tem o escopo necessário.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Título ou episódio não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"502":{"description":"A TMDB não respondeu; tente de novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/watchlist":{"get":{"summary":"Lista \"Quero assistir\"","security":[{"token":[]},{"oauth":["leitura"]}],"parameters":[{"name":"pagina","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Uma página da lista.","content":{"application/json":{"schema":{"type":"object","properties":{"tem_mais":{"type":"boolean"},"itens":{"type":"array","items":{"type":"object","properties":{"tipo":{"type":"string","enum":["movie","tv"],"description":"movie (filme) ou tv (série)."},"tmdb_id":{"type":"integer","minimum":1,"description":"Id do título na TMDB."},"titulo":{"type":["string","null"]},"ano":{"type":["integer","null"]}}}}}}}}},"401":{"description":"Token ausente, inválido ou revogado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}},"post":{"summary":"Põe na lista \"Quero assistir\"","security":[{"token":[]},{"oauth":["escrita"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tipo","tmdb_id"],"properties":{"tipo":{"type":"string","enum":["movie","tv"],"description":"movie (filme) ou tv (série)."},"tmdb_id":{"type":"integer","minimum":1,"description":"Id do título na TMDB."}}}}}},"responses":{"200":{"description":"Situação do título.","content":{"application/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","enum":["movie","tv"],"description":"movie (filme) ou tv (série)."},"tmdb_id":{"type":"integer","minimum":1,"description":"Id do título na TMDB."},"na_watchlist":{"type":"boolean"}}}}}},"400":{"description":"Pedido inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Token ausente, inválido ou revogado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"O token não tem o escopo necessário.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Título ou episódio não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"502":{"description":"A TMDB não respondeu; tente de novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}},"delete":{"summary":"Tira da lista \"Quero assistir\"","security":[{"token":[]},{"oauth":["escrita"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tipo","tmdb_id"],"properties":{"tipo":{"type":"string","enum":["movie","tv"],"description":"movie (filme) ou tv (série)."},"tmdb_id":{"type":"integer","minimum":1,"description":"Id do título na TMDB."}}}}}},"responses":{"200":{"description":"Situação do título.","content":{"application/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","enum":["movie","tv"],"description":"movie (filme) ou tv (série)."},"tmdb_id":{"type":"integer","minimum":1,"description":"Id do título na TMDB."},"na_watchlist":{"type":"boolean"}}}}}},"400":{"description":"Pedido inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Token ausente, inválido ou revogado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"O token não tem o escopo necessário.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Título ou episódio não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"502":{"description":"A TMDB não respondeu; tente de novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/continuar":{"get":{"summary":"Continue assistindo: o próximo episódio de cada série em andamento","description":"Séries com episódio visto e episódio exibido por ver, da mais recente para a mais antiga (até 20). Pausadas e abandonadas não entram.","security":[{"token":[]},{"oauth":["leitura"]}],"responses":{"200":{"description":"As séries e o próximo episódio de cada uma.","content":{"application/json":{"schema":{"type":"object","properties":{"itens":{"type":"array","items":{"type":"object","properties":{"tipo":{"type":"string","enum":["tv"]},"tmdb_id":{"type":"integer","minimum":1,"description":"Id do título na TMDB."},"titulo":{"type":"string"},"poster":{"type":["string","null"]},"proximo":{"type":"object","properties":{"temporada":{"type":"integer","minimum":0,"maximum":500},"episodio":{"type":"integer","minimum":1,"maximum":5000}}},"progresso":{"type":"object","properties":{"vistos":{"type":"integer"},"exibidos":{"type":"integer"}}},"ultima_vez":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Token ausente, inválido ou revogado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Muitas requisições; espere um pouco.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/notas":{"get":{"summary":"Títulos com nota","security":[{"token":[]},{"oauth":["leitura"]}],"parameters":[{"name":"pagina","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Uma página das notas.","content":{"application/json":{"schema":{"type":"object","properties":{"tem_mais":{"type":"boolean"},"itens":{"type":"array","items":{"type":"object","properties":{"tipo":{"type":"string","enum":["movie","tv"],"description":"movie (filme) ou tv (série)."},"tmdb_id":{"type":"integer","minimum":1,"description":"Id do título na TMDB."},"titulo":{"type":["string","null"]},"nota":{"type":"integer","minimum":1,"maximum":10}}}}}}}}},"401":{"description":"Token ausente, inválido ou revogado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}},"post":{"summary":"Dá (ou tira, com null) a nota de 1 a 10","security":[{"token":[]},{"oauth":["escrita"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tipo","tmdb_id","nota"],"properties":{"tipo":{"type":"string","enum":["movie","tv"],"description":"movie (filme) ou tv (série)."},"tmdb_id":{"type":"integer","minimum":1,"description":"Id do título na TMDB."},"nota":{"type":["integer","null"],"minimum":1,"maximum":10}}}}}},"responses":{"200":{"description":"Nota gravada.","content":{"application/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","enum":["movie","tv"],"description":"movie (filme) ou tv (série)."},"tmdb_id":{"type":"integer","minimum":1,"description":"Id do título na TMDB."},"nota":{"type":["integer","null"]}}}}}},"400":{"description":"Pedido inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Token ausente, inválido ou revogado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"O token não tem o escopo necessário.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Título ou episódio não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"502":{"description":"A TMDB não respondeu; tente de novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/scrobble":{"post":{"summary":"Para players: começou, pausou ou parou de tocar","description":"iniciar = \"assistindo agora\"; parar com progresso de 80 ou mais grava como assistido. O mesmo filme avisado de novo em até 6 horas (reenvio ou outro player) não grava outra vez.","security":[{"token":[]},{"oauth":["escrita"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Alvo"},{"type":"object","required":["acao"],"properties":{"acao":{"type":"string","enum":["iniciar","pausar","parar"]},"progresso":{"type":"number","minimum":0,"maximum":100,"default":0}}}]},"examples":{"parar":{"value":{"acao":"parar","tipo":"movie","tmdb_id":550,"progresso":92}},"episodioPeloNome":{"value":{"acao":"iniciar","tipo":"tv","serie":"Breaking Bad","temporada":1,"episodio":2}}}}}},"responses":{"200":{"description":"O que aconteceu.","content":{"application/json":{"schema":{"type":"object","properties":{"resultado":{"type":"string","enum":["assistindo","pausado","assistido","encerrado"]}}}}}},"400":{"description":"Pedido inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Token ausente, inválido ou revogado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"O token não tem o escopo necessário.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Título ou episódio não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"502":{"description":"A TMDB não respondeu; tente de novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}}}}