Screvi/Docs

Public API

Read and write your Screvi highlights, saved articles, sources, and tags over a REST API. Authentication, endpoints, rate limits, and example requests.

Updated

On this page

Overview

Screvi has a REST API for your own highlights, saved articles, sources, and tags. Use it to pull highlights into a script, push highlights in from a tool Screvi does not support yet, save links from your own automations, or build a personal dashboard.

The API needs an active subscription or trial. Full reference docs with request and response schemas live at api.screvi.com/api/docs, and the OpenAPI spec is at api.screvi.com/api/docs.json. Coding agents can load the skill file instead.

If you want an AI assistant to work with your highlights instead of writing code, use the MCP server.

Authentication

  1. In the web app, go to Settings > API and create a key. Give it a name, and tick write access only if the tool needs to change your library.
  2. Send the key with every request in the X-API-Key header. Authorization: Bearer <key> also works.
GET https://api.screvi.com/api/v1/highlights?per_page=50
X-API-Key: sk_live_your_key_here

Keys carry a read scope, and optionally write for creating or editing data. A key is shown once when created. Treat it like a password, and revoke it from the same settings page if it leaks.

Rate Limits

Each key gets 100 requests per minute. Responses include rate-limit headers so you can back off before hitting the cap. Requests over the limit return 429 with code: "rate_limited".

Endpoints

All paths are relative to https://api.screvi.com/api/v1. List endpoints use page and per_page for pagination (per_page maxes out at 100). Everywhere a tags field is accepted it takes tag names, matched case-insensitively and created when new, or tag ids.

Highlights

Method Path Notes
GET /highlights Filters: source_id, favorite, tag, tag_id, updated_since, include_deleted
GET /highlights/random One random highlight. Add count (max 20) for several; filters: favorite, types, tag, source_id
GET /highlights/:id A single highlight with its source and tags
GET /search Hybrid semantic and keyword search. Params: q, source, tag, types, favorite, min_relevance, page, per_page (max 50)
POST /highlights Create one highlight, optionally with tags (write scope)
POST /highlights/bulk Create up to 100 highlights in one transaction (write scope)
PATCH /highlights/:id Edit text, note, favorite, or replace tags (write scope)
DELETE /highlights/:id Delete a highlight (write scope)
POST /highlights/:id/tags Add tags without touching existing ones (write scope)
DELETE /highlights/:id/tags Remove the named tags (write scope)

Articles

Saved web pages, newsletters, and PDFs: the read-later side of Screvi.

Method Path Notes
GET /articles Filters: 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 The article with its body, tags, and highlights. format=text for plain text; page long bodies with offset and max_chars
POST /articles Save a URL, optionally with tags. Returns at once with parse_state: queued; the page is parsed in the background (write scope)
PATCH /articles/:id Triage and metadata: home_status, favorite, title, excerpt, note, tags (write scope)
POST /articles/:id/tags Add tags (write scope)
DELETE /articles/:id/tags Remove tags (write scope)

Articles cannot be deleted through the API, only archived.

Sources

Method Path Notes
GET /sources Filters: type, search, updated_since, include_deleted, include_empty
GET /sources/:id A source with its highlights, paginated
POST /sources Create a book, podcast, video, tweet, or custom source (write scope). Web articles go through POST /articles
PATCH /sources/:id Edit title, author, cover, and other metadata (write scope)
DELETE /sources/:id Delete a source. Add ?cascade=true to delete its highlights too (write scope)

Tags

Method Path Notes
GET /tags All your tags with counts
POST /tags Create a tag by name. Returns the existing tag if the name is already taken (write scope)
PATCH /tags/:id Rename or recolor a tag (write scope)
DELETE /tags/:id Delete a tag and remove it from everything; the highlights and articles stay (write scope)

Incremental Sync

To keep another tool in step with Screvi, store the time of your last run and pass it as updated_since on the next one. Only highlights, sources, or articles changed after that moment come back. Add include_deleted=true if you need to mirror deletions.

Example: Export New Highlights with 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"

curl -X POST "https://api.screvi.com/api/v1/articles" \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/essay", "tags": ["to-read"] }'

The response carries the new article's id. A few seconds later, fetch the text:

curl "https://api.screvi.com/api/v1/articles/<id>?format=text" \
  -H "X-API-Key: sk_live_your_key_here"

Errors

Every error carries a stable code next to the message, so scripts can branch on the code rather than on wording. Validation problems come with a fields map naming what was wrong. The full list is in the API reference.

Ideas

  • Post a random highlight to Slack or X every morning
  • Build a Raycast or Alfred command that searches your library
  • Save links from an RSS reader, a Telegram bot, or a shortcut on your phone
  • Push highlights from a reading app Screvi does not integrate with yet
  • Feed your highlights and articles into a personal knowledge base or a custom AI agent

Still have questions?