API pública
Lee y escribe tus subrayados, artículos guardados, fuentes y etiquetas de Screvi a través de una API REST. Autenticación, endpoints, límites de peticiones y ejemplos de solicitudes.
Actualizado
En esta página
Resumen
Screvi tiene una API REST para tus propios subrayados y fuentes. Úsala para traer subrayados a un script, enviar subrayados desde una herramienta que Screvi aún no admite o montar un panel personal.
La API necesita una suscripción o prueba activa. La referencia completa con los esquemas de solicitud y respuesta está en api.screvi.com/api/docs, y la especificación OpenAPI está en api.screvi.com/api/docs.json.
Si quieres que un asistente de IA trabaje con tus subrayados en lugar de escribir código, usa el servidor MCP.
Autenticación
- En la app web, ve a Ajustes > API y crea una clave. Ponle un nombre y marca el acceso de escritura solo si la herramienta necesita cambiar tu biblioteca.
- Envía la clave con cada solicitud en la cabecera
X-API-Key.Authorization: Bearer <key>también funciona.
GET https://api.screvi.com/api/v1/highlights?per_page=50
X-API-Key: sk_live_your_key_here
Las claves tienen un ámbito de lectura y, opcionalmente, de escritura para crear o editar datos. La clave se muestra una sola vez al crearla. Trátala como una contraseña y revócala desde la misma página de ajustes si se filtra.
Límites de peticiones
Cada clave tiene 100 solicitudes por minuto. Las respuestas incluyen cabeceras de límite para que puedas frenar antes de alcanzar el tope. Las solicitudes por encima del límite devuelven 429.
Endpoints
Todas las rutas son relativas a https://api.screvi.com/api/v1. Los endpoints de listado usan page y per_page para la paginación (per_page llega como máximo a 100). Allí donde se acepta un campo tags, admite nombres de etiqueta (sin distinguir mayúsculas y creados si no existen) o ids de etiqueta.
Subrayados
| Método | Ruta | Notas |
|---|---|---|
| GET | /highlights |
Filtros: source_id, favorite, tag, tag_id, updated_since, include_deleted |
| GET | /highlights/random |
Un subrayado aleatorio. Añade count (máx. 20) para varios; filtros: favorite, types, tag, source_id |
| GET | /highlights/:id |
Un solo subrayado con su fuente y etiquetas |
| GET | /search |
Búsqueda semántica y por palabras clave. Parámetros: q, source, tag, types, favorite, min_relevance, page, per_page (máx. 50) |
| POST | /highlights |
Crea un subrayado, opcionalmente con tags (ámbito de escritura) |
| POST | /highlights/bulk |
Crea muchos subrayados en una sola llamada (ámbito de escritura) |
| PATCH | /highlights/:id |
Edita texto, nota, favorito o reemplaza tags (ámbito de escritura) |
| DELETE | /highlights/:id |
Elimina un subrayado (ámbito de escritura) |
| POST | /highlights/:id/tags |
Añade etiquetas sin tocar las existentes (ámbito de escritura) |
| DELETE | /highlights/:id/tags |
Quita las etiquetas indicadas (ámbito de escritura) |
Artículos
Páginas web guardadas, boletines y PDF: el lado de leer más tarde de Screvi.
| Método | Ruta | 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 |
El artículo con su cuerpo, etiquetas y subrayados. format=text para texto plano; pagina cuerpos largos con offset y max_chars |
| POST | /articles |
Guarda una URL, opcionalmente con tags. Responde al instante con parse_state: queued; la página se procesa en segundo plano (ámbito de escritura) |
| PATCH | /articles/:id |
Triaje y metadatos: home_status, favorite, title, excerpt, note, tags (ámbito de escritura) |
| POST | /articles/:id/tags |
Añade etiquetas (ámbito de escritura) |
| DELETE | /articles/:id/tags |
Quita etiquetas (ámbito de escritura) |
Los artículos no se pueden eliminar desde la API, solo archivar.
Fuentes
| Método | Ruta | Notas |
|---|---|---|
| GET | /sources |
Filtros: type, search, updated_since, include_deleted, include_empty |
| GET | /sources/:id |
Una fuente con sus subrayados, paginados |
| POST | /sources |
Crea un libro, podcast, vídeo, tuit o fuente personalizada (ámbito de escritura). Los artículos web van por POST /articles |
| PATCH | /sources/:id |
Edita título, autor, portada y otros metadatos (ámbito de escritura) |
| DELETE | /sources/:id |
Elimina una fuente. Añade ?cascade=true para eliminar también sus subrayados (ámbito de escritura) |
Etiquetas
| Método | Ruta | Notas |
|---|---|---|
| GET | /tags |
Todas tus etiquetas con recuentos |
| POST | /tags |
Crea una etiqueta por nombre. Devuelve la existente si el nombre ya está en uso (ámbito de escritura) |
| PATCH | /tags/:id |
Renombra o cambia el color de una etiqueta (ámbito de escritura) |
| DELETE | /tags/:id |
Elimina una etiqueta y la quita de todo; los subrayados y artículos se conservan (ámbito de escritura) |
Sincronización incremental
Para mantener otra herramienta al día con Screvi, guarda la hora de tu última ejecución y pásala como updated_since en la siguiente. Solo vuelven los subrayados o fuentes modificados después de ese momento. Añade include_deleted=true si necesitas reflejar las eliminaciones.
Ejemplo: exportar subrayados nuevos con 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"
Ideas
- Publica un subrayado aleatorio en Slack o X cada mañana
- Crea un comando de Raycast o Alfred que busque en tu biblioteca
- Envía subrayados desde una app de lectura con la que Screvi aún no se integra
- Alimenta con tus subrayados una base de conocimiento personal o un agente de IA a tu medida
Relacionado
- Servidor MCP de Screvi
- Exportar tus subrayados para exportaciones ZIP puntuales sin código
¿Aún tienes preguntas?