---
title: "Identify a book or shelf photo"
method: POST
path: "/api/photo"
tags: ["photo"]
---

# Identify a book or shelf photo

`POST /api/photo`

## Request

- Base URL: `https://leafle.org` (the document declares no server; this is the origin it was published from)
- URL: `https://leafle.org/api/photo`
- Auth: HTTP bearer

**Access: write token.**

Upload an image in multipart field `file`. A cover returns candidate books without recording a read; a shelf records owned inventory; an unrecognised image returns mode none. Confirm reads separately. Pass `reader_id` in the query string.

## Query parameters

- `reader_id` integer, nullable

## Response `200`

Successful Response

- union
  - PhotoCoverScan
    - `mode` 'cover', required
    - `books` PhotoBook[], required
      - `title` string
      - `author` string
      - `isbn` string
      - `cover_url` string, nullable
      - `year` union
        - integer
        - string
      - `confidence` string
  - PhotoShelfScan
    - `mode` 'shelf', required
    - `recorded` integer, required
    - `message` string, required
    - `books` PhotoBook[], required
      - `title` string
      - `author` string
      - `isbn` string
      - `cover_url` string, nullable
      - `year` union
        - integer
        - string
      - `confidence` string
    - `strip` ShelfStripBook[], required
      - `title` string
      - `author` string
      - `cover_url` string, nullable
    - `author_runs` string[], required
  - PhotoNoneScan
    - `mode` 'none', required
    - `books` PhotoBook[], required
      - `title` string
      - `author` string
      - `isbn` string
      - `cover_url` string, nullable
      - `year` union
        - integer
        - string
      - `confidence` string

## Other responses

- `400`: Invalid input; see detail for the reason.
- `401`: Missing or unusable credential.
- `403`: Insufficient token scope or the reader is outside your account.
- `413`: The uploaded file exceeds this deployment's size limit.
- `422`: Validation Error
- `429`: Request or usage limit reached. Wait before retrying.
- `502`: The image recognition provider could not read the photo.
- `503`: Capacity is unavailable or the service is restarting. Honour Retry-After when present.

---

[API](https://skmtc.dev/leafle/apis/leafle-api.md) · [All operations](https://skmtc.dev/leafle/apis/leafle-api/llms.txt) · [OpenAPI document](https://skmtc.dev/leafle/apis/leafle-api/revisions/f2e56cb74495?raw)