Developer Docs

API tokens, webhooks, and data export for integrating Lex with your tools.

API Tokens

Generate a personal token in Settings → Integrations → API Tokens. Use it to access your own reading data from scripts, automations, or other apps.

Send it as a Bearer token in the Authorization header:

curl -H "Authorization: Bearer lex_your_token_here" \ https://lex-books.com/api/reading-progress/export?format=json

Security

Tokens are shown once when generated. Lex stores only the SHA-256 hash — the plaintext cannot be recovered. If you lose a token, revoke it and create a new one.

Limits: 5 tokens per account. API requests share the global rate limit of 500 requests per minute per IP address.

API Endpoints

Your personal token works with all authenticated endpoints — the same ones the web and mobile apps use. The most useful ones for integrations:

Method	Endpoint	Description
`GET`	`/api/reading-progress/export?format=json`	Export all reading progress as JSON
`GET`	`/api/reading-progress/export?format=csv`	Export all reading progress as CSV
`GET`	`/api/reading-progress?bookId=ID`	Get progress for a single book
`POST`	`/api/reading-progress`	Batch lookup — send `{"bookIds": [...]}`
`GET`	`/api/webhooks`	List your webhook configs
`POST`	`/api/webhooks`	Create a webhook
`PATCH`	`/api/webhooks`	Update a webhook
`DELETE`	`/api/webhooks?id=ID`	Delete a webhook

All responses are JSON. Errors return {"error": "message"} with the appropriate HTTP status code.

Webhooks

Configure in Settings → Integrations → Webhooks. Lex sends a POST request to your URL whenever a reading event occurs.

Event	Fires when
`reading.started`	You open a book for the first time
`reading.progress`	Reading progress is saved
`reading.finished`	You mark a book complete
`audiobook.started`	You start an audiobook
`audiobook.progress`	Audiobook progress is saved
`audiobook.finished`	You finish an audiobook

Request headers

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`Lex-Webhooks/1.0`
`X-Lex-Event`	Event name, e.g. `reading.progress`
`X-Lex-Signature`	HMAC-SHA256 hex digest (only if you set a signing secret)

Failure handling

If your endpoint returns a non-2xx status or times out (5 seconds), Lex increments a failure counter. After 10 consecutive failures the webhook is automatically disabled. Re-enable it from Settings to reset the counter. Use the test button to verify your endpoint before going live.

Webhook Payload

{ "event": "reading.progress", "timestamp": "2026-03-05T22:30:00.000Z", "data": { "book": { "id": "abc-123", "title": "The Art of War", "author": "Sun Tzu", "slug": "the-art-of-war" }, "progress": { "percentage": 42, "current_page": 21, "total_pages": 50, "current_chapter": "Chapter 3: Attack by Stratagem", "is_finished": false }, "audio": { "position_seconds": 1234, "chapter_index": 3 } } }

The audio object only appears for audiobook events. The book.slug can be used to link to the book at lex-books.com/book/SLUG.

Signature Verification

If you set a signing secret on your webhook, every request includes an X-Lex-Signature header containing the HMAC-SHA256 hex digest of the request body.

Python

import hmac, hashlib secret = b"your_signing_secret" body = request.body # raw bytes expected = hmac.new(secret, body, hashlib.sha256).hexdigest() assert request.headers["X-Lex-Signature"] == expected

Node.js

const crypto = require('crypto'); const secret = 'your_signing_secret'; const body = req.rawBody; // raw string const expected = crypto .createHmac('sha256', secret) .update(body) .digest('hex'); const valid = req.headers['x-lex-signature'] === expected;

Export Progress

Download all your reading history from Settings → Integrations, or use the API directly:

# JSON (all progress with book metadata) curl -H "Authorization: Bearer lex_..." \ https://lex-books.com/api/reading-progress/export?format=json \ -o progress.json # CSV (spreadsheet-friendly) curl -H "Authorization: Bearer lex_..." \ https://lex-books.com/api/reading-progress/export?format=csv \ -o progress.csv

Both formats include: title, author, slug, percentage complete, current/total pages, current chapter, audiobook position, started/finished/last-read dates, and word counts.

Ryot Integration

To send reading progress to Ryot:

Go to Settings → Integrations → Webhooks
Click Add Webhook
Set the URL to your Ryot Generic JSON sink endpoint (e.g. https://ryot.example.com/_i/your_slug)
Set Payload Format to Ryot (Generic JSON)
Pick which events to send
Hit the test button — Ryot should show “The Art of War” in your media

Lex sends Ryot’s CompleteExport format with an OpenLibrary or Google Books identifier. If a book doesn’t have an ISBN or OpenLibrary ID, Lex will look it up automatically on first sync. Books that can’t be matched to any external database won’t appear in Ryot.