API quickstart

API quickstart

JSON under /api/v1. Errors are RFC 9457 problem documents. Unsafe requests need the session cookie and the token from GET /auth/csrf in X-CSRF-Token. The full contract: openapi.yaml.

BASE=https://offlineshelf.ahmershah.dev/api/v1
TOKEN=$(curl -s -c jar -b jar $BASE/auth/csrf | jq -r .token)
TOKEN=$(curl -s -c jar -b jar -H "X-CSRF-Token: $TOKEN" -H 'Content-Type: application/json' \
  -d '{"email": "you@example.org", "password": "a long passphrase"}' $BASE/auth/login | jq -r .csrf)

# create and build a list
ID=$(curl -s -c jar -b jar -H "X-CSRF-Token: $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name": "Vaccines", "wiki": "en.wikipedia.org", "params": {"kind": "category", "category": "Vaccines", "depth": 1}}' \
  $BASE/lists | jq .id)
curl -s -X POST -c jar -b jar -H "X-CSRF-Token: $TOKEN" $BASE/lists/$ID/build

# poll until ready, then read
curl -s -b jar "$BASE/lists/$ID/versions?limit=1" | jq '.items[0] | {id, status, article_count, added_count, removed_count}'
curl -s -b jar "$BASE/lists/$ID/versions/<v>/articles?limit=100"
curl -s -b jar "$BASE/lists/$ID/versions/<v>/changes?kind=added"
curl -s -b jar -o list.tsv "$BASE/lists/$ID/versions/<v>/export.tsv"

Exports

POST /lists/{id}/versions/{v}/exports with {"format": "html"} or {"format": "zim"} answers 202. Poll GET on the same path until status is ready, then download GET /lists/{id}/exports/{e}/download (410 after 7 days).

Limits

300 requests a minute per IP; sign-in 10 a minute per IP and per email; list writes 30 a minute; builds and exports 20 an hour. Limited responses are 429 with Retry-After.