API pública
Leia e grave seus destaques, artigos salvos, fontes e tags do Screvi por uma API REST. Autenticação, endpoints, limites de requisições e exemplos de chamadas.
Atualizado
Nesta página
Visão geral
O Screvi tem uma API REST para seus próprios destaques e fontes. Use-a para puxar destaques em um script, enviar destaques de uma ferramenta que o Screvi ainda não suporta ou montar um painel pessoal.
A API exige uma assinatura ativa ou um período de teste. A referência completa, com esquemas de requisição e resposta, está em api.screvi.com/api/docs, e a especificação OpenAPI está em api.screvi.com/api/docs.json.
Se você quer que um assistente de IA trabalhe com seus destaques em vez de escrever código, use o servidor MCP.
Autenticação
- No aplicativo web, vá em Configurações > API e crie uma chave. Dê um nome a ela e marque acesso de escrita só se a ferramenta precisar alterar sua biblioteca.
- Envie a chave em cada requisição no cabeçalho
X-API-Key.Authorization: Bearer <key>também funciona.
GET https://api.screvi.com/api/v1/highlights?per_page=50
X-API-Key: sk_live_your_key_here
As chaves têm escopo de leitura e, opcionalmente, de escrita para criar ou editar dados. A chave aparece uma única vez ao ser criada. Trate-a como uma senha e revogue-a na mesma página de configurações se vazar.
Limites de requisições
Cada chave tem direito a 100 requisições por minuto. As respostas incluem cabeçalhos de limite para você reduzir o ritmo antes de atingir o teto. Requisições acima do limite retornam 429.
Endpoints
Todos os caminhos são relativos a https://api.screvi.com/api/v1. Os endpoints de listagem usam page e per_page para paginação (per_page vai até 100). Sempre que um campo tags é aceito, ele recebe nomes de tag (comparados sem diferenciar maiúsculas e criados quando novos) ou ids de tag.
Destaques
| Método | Caminho | Observações |
|---|---|---|
| GET | /highlights |
Filtros: source_id, favorite, tag, tag_id, updated_since, include_deleted |
| GET | /highlights/random |
Um destaque aleatório. Adicione count (máx. 20) para vários; filtros: favorite, types, tag, source_id |
| GET | /highlights/:id |
Um único destaque com sua fonte e tags |
| GET | /search |
Busca semântica e por palavras-chave. Parâmetros: q, source, tag, types, favorite, min_relevance, page, per_page (máx. 50) |
| POST | /highlights |
Cria um destaque, opcionalmente com tags (escopo de escrita) |
| POST | /highlights/bulk |
Cria vários destaques em uma chamada (escopo de escrita) |
| PATCH | /highlights/:id |
Edita texto, nota, favorito ou substitui tags (escopo de escrita) |
| DELETE | /highlights/:id |
Exclui um destaque (escopo de escrita) |
| POST | /highlights/:id/tags |
Adiciona tags sem mexer nas existentes (escopo de escrita) |
| DELETE | /highlights/:id/tags |
Remove as tags indicadas (escopo de escrita) |
Artigos
Páginas web salvas, newsletters e PDFs: o lado de ler mais tarde do Screvi.
| Método | Caminho | Notas |
|---|---|---|
| GET | /articles |
Filtros: q, status, home_status (inbox, later, archive), favorite, has_highlights, tag, saved_since, saved_before, updated_since, include_deleted, sort_by, order |
| GET | /articles/:id |
O artigo com corpo, tags e destaques. format=text para texto puro; pagine corpos longos com offset e max_chars |
| POST | /articles |
Salva uma URL, opcionalmente com tags. Responde na hora com parse_state: queued; a página é processada em segundo plano (escopo de escrita) |
| PATCH | /articles/:id |
Triagem e metadados: home_status, favorite, title, excerpt, note, tags (escopo de escrita) |
| POST | /articles/:id/tags |
Adiciona tags (escopo de escrita) |
| DELETE | /articles/:id/tags |
Remove tags (escopo de escrita) |
Artigos não podem ser excluídos pela API, apenas arquivados.
Fontes
| Método | Caminho | Observações |
|---|---|---|
| GET | /sources |
Filtros: type, search, updated_since, include_deleted, include_empty |
| GET | /sources/:id |
Uma fonte com seus destaques, paginados |
| POST | /sources |
Cria um livro, podcast, vídeo, tweet ou fonte personalizada (escopo de escrita). Artigos da web passam por POST /articles |
| PATCH | /sources/:id |
Edita título, autor, capa e outros metadados (escopo de escrita) |
| DELETE | /sources/:id |
Exclui uma fonte. Adicione ?cascade=true para excluir também seus destaques (escopo de escrita) |
Tags
| Método | Caminho | Observações |
|---|---|---|
| GET | /tags |
Todas as suas tags com contagens |
| POST | /tags |
Cria uma tag pelo nome. Retorna a existente se o nome já estiver em uso (escopo de escrita) |
| PATCH | /tags/:id |
Renomeia ou muda a cor de uma tag (escopo de escrita) |
| DELETE | /tags/:id |
Exclui uma tag e a remove de tudo; os destaques e artigos ficam (escopo de escrita) |
Sincronização incremental
Para manter outra ferramenta alinhada com o Screvi, guarde o horário da sua última execução e passe-o como updated_since na próxima. Só voltam os destaques ou fontes alterados depois desse momento. Adicione include_deleted=true se precisar espelhar exclusões.
Exemplo: exportar destaques novos com curl
curl "https://api.screvi.com/api/v1/highlights?updated_since=2026-09-01T00:00:00Z&per_page=100" \
-H "X-API-Key: sk_live_your_key_here"
Ideias
- Publicar um destaque aleatório no Slack ou no X toda manhã
- Criar um comando do Raycast ou do Alfred que busca na sua biblioteca
- Enviar destaques de um aplicativo de leitura com o qual o Screvi ainda não se integra
- Alimentar uma base de conhecimento pessoal ou um agente de IA personalizado com seus destaques
Relacionados
- Servidor MCP do Screvi
- Exportar seus destaques para exportações pontuais em ZIP sem código
Ainda tens dúvidas?