Reference

#API

Everything Shelf's pages do goes through the same HTTP API, which answers in JSON. Every call works on the signed-in reader's own shelf, signed in by an API token or the browser's cookie. In Development, the OpenAPI document is at /openapi/v1.json.

#API tokens

A script or a home dashboard signs in with an API token. Make one on Account, under API tokens: name it after what will use it, and tick Let it change things if it needs more than reading. The token is shown once. Send it with every request:

curl -s -H "Authorization: Bearer $SHELF_TOKEN" https://shelf.example.org/books?status=Reading

A token opens the calls on this page under /books, /settings, and /readers. Under What it opens, a token can be kept to some of them: the library (books, reading, lending, collections, goals, and settings), files (e-books, recordings, covers, pictures of a copy, backups, and the file check), the journal, book clubs, and the event feed. Leave every box clear for all of them; a call outside a token's parts is refused with 403, and /version is open to every token. Send "areas": ["journal", "events"] to make one through the API. It never opens the account (passwords, keys, other tokens, the sandbox) or the admin pages, so a token that leaks cannot take the account over; remove it on Account and it stops working at once. A read-only token is refused anything but GET, with 403. Account shows when each token was last used.

#Trying a connector on a sandbox

On Account, Sandbox, Make a sandbox token gives a token for a shelf of a dozen sample books instead of yours: a connector, a script, or a webhook can be tried on it, writing included, before it is given the real one. Everything under /books works the same there, webhooks and the event feed too, but it is a reader of its own that no one signs in as: no other reader sees it, it lends to and asks no one, and it is in no club. Put the samples back as they were resets it and its tokens go on working; Remove the sandbox ends it and them.

#Home Assistant

A REST sensor shows what you are reading and how the year's goal is going. Keep the token in secrets.yaml as shelf_token: "Bearer shelf_…", then:

rest:
  - resource: https://shelf.example.org/books/stats
    headers:
      Authorization: !secret shelf_token
    scan_interval: 3600
    sensor:
      - name: Books reading
        value_template: "{{ value_json.reading }}"
      - name: Books finished this year
        value_template: "{{ value_json.finishedThisYear }}"
        json_attributes:
          - yearlyGoal
          - pagesRead

#Signing in from a script without a token

A script can also sign in with the cookie the browser uses, posting the sign-in form with the anti-forgery token the page carries. This doesn't work with Turnstile on; use an API token then.

site=https://shelf.example.org
jar=$(mktemp)
token=$(curl -s -c "$jar" "$site/signin" \
  | grep -o 'name="__RequestVerificationToken"[^>]*value="[^"]*"' | sed 's/.*value="//; s/"$//')
curl -s -b "$jar" -c "$jar" -o /dev/null "$site/account/signin" \
  --data-urlencode "email=tenar@example.org" --data-urlencode "password=$SHELF_PASSWORD" \
  --data-urlencode "__RequestVerificationToken=$token"

curl -s -b "$jar" "$site/books?status=Reading"

A reader with two-step sign-in is asked for a code next, at /account/signin/code. The device key is for e-reader catalogs and shelf-to-shelf sync only, not for this API.

#Books

Statuses are Want, Reading, Finished, and Abandoned; formats are Hardcover, Paperback, Ebook, and Audiobook.

#Files and covers

#Reading and listening

#Lending and open shelves

#Importing and exporting

| GET /books/import/recipes | Your import recipes. POST /books/import/recipes/preview with file (and a spec or recipeId, or neither to guess one) answers with the file's columns, the recipe, the words in its status column, and its first rows as they would come in; POST /books/import/recipes/import with file, the same, and saveAs to keep the recipe brings it in. A spec is {"columns": {"Title": "Book Name", "Author": "By"}, "statuses": {"wishlist": "Want"}, "tagSeparator": ";", "dateFormat": "dd.MM.yyyy", "ratingOutOfTen": true}. DELETE /books/import/recipes/{id} forgets one. |

GET /books/export/full also carries README.md, books.csv, collections.json, loans.json, and borrowed-highlights.json; the README says what each holds.

#Trash, history, and undo

#Your reading

#Scanning

#Tidying

#Book clubs

A meeting's at is the moment it begins, with an offset or in UTC; timeZone, an IANA name such as Europe/Paris, is the zone it is told in, in notifications and chat messages.

#Events

Everything a webhook is sent is also kept for you, the latest 1,000, for a script that would rather ask than be told. Each event is the same JSON a signed webhook carries, so one script can take either.

after=0
while true; do
  page=$(curl -s -H "Authorization: Bearer $SHELF_TOKEN" "https://shelf.example.org/books/events?after=$after")
  echo "$page" | jq -c '.events[].event'
  after=$(echo "$page" | jq '.next')
  sleep 60
done

#Your account

#For admins

#Devices

These sign in differently, as their apps expect.

#Open to anyone