Screvi/Docs

Öffentliche API

Lies und schreibe deine Screvi-Highlights, gespeicherten Artikel, Quellen und Tags über eine REST-API. Authentifizierung, Endpunkte, Rate-Limits und Beispielanfragen.

Aktualisiert

Auf dieser Seite

Überblick

Screvi hat eine REST-API für deine eigenen Highlights und Quellen. Nutze sie, um Highlights in ein Skript zu ziehen, Highlights aus einem Tool einzuspielen, das Screvi noch nicht unterstützt, oder ein persönliches Dashboard zu bauen.

Die API braucht ein aktives Abo oder eine Testphase. Die vollständige Referenz mit Request- und Response-Schemas liegt unter api.screvi.com/api/docs, die OpenAPI-Spezifikation unter api.screvi.com/api/docs.json.

Wenn ein KI-Assistent mit deinen Highlights arbeiten soll, statt dass du Code schreibst, nutze den MCP-Server.

Authentifizierung

  1. Geh in der Web-App zu Einstellungen > API und erstelle einen Schlüssel. Gib ihm einen Namen und aktiviere Schreibzugriff nur, wenn das Tool deine Bibliothek ändern muss.
  2. Schick den Schlüssel bei jeder Anfrage im Header X-API-Key mit. Authorization: Bearer <key> funktioniert auch.
GET https://api.screvi.com/api/v1/highlights?per_page=50
X-API-Key: sk_live_your_key_here

Schlüssel haben einen read-Scope und optional write zum Erstellen oder Bearbeiten von Daten. Ein Schlüssel wird beim Erstellen genau einmal angezeigt. Behandle ihn wie ein Passwort und widerrufe ihn auf derselben Einstellungsseite, falls er durchsickert.

Rate-Limits

Jeder Schlüssel bekommt 100 Anfragen pro Minute. Antworten enthalten Rate-Limit-Header, damit du bremsen kannst, bevor du die Grenze erreichst. Anfragen über dem Limit liefern 429.

Endpunkte

Alle Pfade sind relativ zu https://api.screvi.com/api/v1. Listen-Endpunkte nutzen page und per_page zur Paginierung (per_page maximal 100). Überall, wo ein tags-Feld akzeptiert wird, nimmt es Tag-Namen (ohne Beachtung der Groß-/Kleinschreibung abgeglichen und bei Bedarf angelegt) oder Tag-IDs.

Highlights

Methode Pfad Hinweise
GET /highlights Filter: source_id, favorite, tag, tag_id, updated_since, include_deleted
GET /highlights/random Ein zufälliges Highlight. Mit count (max. 20) mehrere; Filter: favorite, types, tag, source_id
GET /highlights/:id Ein einzelnes Highlight mit Quelle und Tags
GET /search Semantische und Stichwortsuche. Parameter: q, source, tag, types, favorite, min_relevance, page, per_page (max. 50)
POST /highlights Ein Highlight erstellen, optional mit tags (write-Scope)
POST /highlights/bulk Viele Highlights in einem Aufruf erstellen (write-Scope)
PATCH /highlights/:id Text, Notiz, Favorit bearbeiten oder tags ersetzen (write-Scope)
DELETE /highlights/:id Ein Highlight löschen (write-Scope)
POST /highlights/:id/tags Tags hinzufügen, ohne bestehende anzutasten (write-Scope)
DELETE /highlights/:id/tags Die genannten Tags entfernen (write-Scope)

Artikel

Gespeicherte Webseiten, Newsletter und PDFs: die Später-lesen-Seite von Screvi.

Methode Pfad Hinweise
GET /articles Filter: 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 Der Artikel mit Text, Tags und Highlights. format=text für reinen Text; lange Texte mit offset und max_chars blättern
POST /articles Eine URL speichern, optional mit tags. Antwortet sofort mit parse_state: queued; die Seite wird im Hintergrund verarbeitet (write-Scope)
PATCH /articles/:id Sortieren und Metadaten: home_status, favorite, title, excerpt, note, tags (write-Scope)
POST /articles/:id/tags Tags hinzufügen (write-Scope)
DELETE /articles/:id/tags Tags entfernen (write-Scope)

Artikel können über die API nicht gelöscht, nur archiviert werden.

Quellen

Methode Pfad Hinweise
GET /sources Filter: type, search, updated_since, include_deleted, include_empty
GET /sources/:id Eine Quelle mit ihren Highlights, paginiert
POST /sources Ein Buch, einen Podcast, ein Video, einen Tweet oder eine eigene Quelle erstellen (write-Scope). Webartikel laufen über POST /articles
PATCH /sources/:id Titel, Autor, Cover und andere Metadaten bearbeiten (write-Scope)
DELETE /sources/:id Eine Quelle löschen. Mit ?cascade=true auch ihre Highlights löschen (write-Scope)

Tags

Methode Pfad Hinweise
GET /tags Alle deine Tags mit Zählern
POST /tags Einen Tag per Name erstellen. Liefert den bestehenden Tag, wenn der Name schon vergeben ist (write-Scope)
PATCH /tags/:id Einen Tag umbenennen oder umfärben (write-Scope)
DELETE /tags/:id Einen Tag löschen und überall entfernen; Highlights und Artikel bleiben (write-Scope)

Inkrementelle Synchronisierung

Um ein anderes Tool mit Screvi in Einklang zu halten, speichere den Zeitpunkt deines letzten Durchlaufs und übergib ihn beim nächsten als updated_since. Nur Highlights oder Quellen, die danach geändert wurden, kommen zurück. Ergänze include_deleted=true, wenn du Löschungen spiegeln musst.

Beispiel: Neue Highlights mit curl exportieren

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"

Ideen

  • Jeden Morgen ein zufälliges Highlight in Slack oder auf X posten
  • Einen Raycast- oder Alfred-Befehl bauen, der deine Bibliothek durchsucht
  • Highlights aus einer Lese-App einspielen, die Screvi noch nicht integriert
  • Deine Highlights in eine persönliche Wissensdatenbank oder einen eigenen KI-Agenten einspeisen

Verwandte Themen

Noch Fragen?