API Reference

{
  "id": 42,
  "book_id": 17,
  "title": "The City & The City",
  "authors": ["China Miéville"],
  "isbn": "9780345524256",
  "publisher": "Del Rey",
  "published_year": 2009,
  "genre": "Science Fiction",
  "shelf": {
    "id": 3,
    "display": "Living Room - Shelf 2",
    "location_name": "Living Room",
    "number": 2
  },
  "reading_status": "read",
  "on_loan": false,
  "rating": 5,
  "condition": "good",
  "notes": null,
  "date_added": "2026-06-06T10:30:00Z"
}

curl -X POST /auth/register/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "supersecret"
  }'

{
  "access": "eyJ...",
  "refresh": "eyJ...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "username": "user@example.com"
  }
}

curl -X POST /auth/login/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "supersecret"
  }'

{
  "access": "eyJ...",
  "refresh": "eyJ...",
  "user": { /* user object */ }
}

curl -X POST /auth/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{ "refresh": "eyJ..." }'

{
  "access": "eyJ...",
  "refresh": "eyJ..."
}

curl /auth/me/ \
  -H "Authorization: Bearer eyJ..."

{
  "id": 1,
  "email": "user@example.com",
  "username": "user@example.com"
}

curl -X PATCH /auth/me/ \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "supersecret",
    "new_password": "evenmoresecret"
  }'

{
  "access": "eyJ...",
  "refresh": "eyJ...",
  "user": { /* user object */ }
}

GET /api/books/?search=mieville&ordering=-date_added

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [{ /* Copy objects */ }]
}

curl -X POST /api/books/ \
  -H "Content-Type: application/json" \
  -d '{
    "title": "The City & The City",
    "author": "China Miéville",
    "isbn": "9780345524256",
    "shelf_id": 3,
    "reading_status": "read",
    "rating": 5
  }'

{ /* Copy object */ }

GET /api/books/42/

{ /* Copy object */ }

curl -X PATCH /api/books/42/ \
  -H "Content-Type: application/json" \
  -d '{
    "reading_status": "read",
    "rating": 4,
    "on_loan": false
  }'

{ /* Updated Copy object */ }

curl -X DELETE /api/books/42/

204 No Content

curl -X PATCH /api/books/42/restore/

{ /* Restored Copy object */ }

GET /api/books/lookup/?isbn=9780345524256

{
  "matched": true,
  "title": "The City & The City",
  "authors": ["China Miéville"],
  "author": "China Miéville",
  "publisher": "Del Rey",
  "published_year": "2009",
  "cover_url": "https://covers.openlibrary.org/...",
  "isbn": "9780345524256"
}

{ "matched": false }

GET /api/books/export/

# Or directly in browser — triggers download

Content-Type: text/csv
Content-Disposition: attachment; filename="library.csv"

curl -X POST /api/scans/shelf/ \
  -F "image=@/path/to/shelf.jpg"

{
  "id": 7,
  "status": "done",
  "book_count": 14,
  "processing_time_ms": 3241,
  "books": [
    {
      "title": "The City & The City",
      "author": "China Miéville"
    },
    /* ... */
  ]
}

GET /api/scans/7/results/

{ /* Same structure as POST /api/scans/shelf/ response */ }

curl -X POST /api/scans/7/confirm/ \
  -H "Content-Type: application/json" \
  -d '{
    "shelf_id": 3,
    "books": [
      {
        "title": "The City & The City",
        "author": "China Miéville"
      },
      {
        "title": "Perdido Street Station",
        "author": "China Miéville"
      }
    ]
  }'

[
  { /* Copy object */ },
  { /* Copy object */ }
]

curl -X POST /api/scans/cover/ \
  -H "Authorization: Bearer eyJ..." \
  -F "image=@/path/to/cover.jpg"

{
  "title": "Perdido Street Station",
  "author": "China Miéville",
  "isbn": "9780345459404",
  "publisher": "Del Rey",
  "published_year": 2001,
  "genre": "Science Fiction",
  "description": null,
  "language": "en"
}

curl -X POST /api/scans/cover/confirm/ \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Perdido Street Station",
    "author": "China Miéville",
    "isbn": "9780345459404",
    "shelf_id": 3
  }'

{
  /* Copy object */,
  "_augmentation": { "status": "queued" }
}

GET /api/shelves/

[
  {
    "id": 1,
    "display": "Living Room - Shelf 1",
    "location_name": "Living Room",
    "number": 1,
    "book_count": 14
  }
]

curl -X POST /api/shelves/ \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "location_name": "Study",
    "number": 1
  }'

{
  "id": 4,
  "display": "Study - Shelf 1",
  "location_name": "Study",
  "number": 1,
  "book_count": 0
}

GET /api/shelves/4/

{ /* Shelf object */ }

curl -X DELETE /api/shelves/4/ \
  -H "Authorization: Bearer eyJ..."

204 No Content

GET /api/locations/

[
  { "name": "Living Room", "is_custom": false },
  { "name": "Study", "is_custom": true }
]

GET /api/stats/

{
  "total": 142,
  "unread": 87,
  "reading": 3,
  "read": 52,
  "on_loan": 4
}

GET /api/health/

{ "status": "ok" }