Wishlist

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Titles users have asked for.

Back to the web API reference.

GET /api/wishlist

Lists open wishlist rows for the caller (portal identity or operator-owned).

Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).

Credentials: operatorToken or operatorSession or portalSession or clerkToken

Responses

  • 200The caller's open requests. Body: array of TitleRequestRecord (application/json)30 fields
    • idinteger (int64)requiredSurrogate primary key assigned by the database.
    • uuidstringrequiredStable UUID for this row (API / foreign-key identity).
    • identity_idinteger (int64) or nullForeign key to portal_identities.id.
    • titlestringrequiredDisplay title: the title of the wish's work.
    • authorsstring or nullComma-separated authors: the work's author credits in billing order.
    • asinstring or nullAmazon ASIN from the wish's storefront sources, when one carries it.
    • isbnstring or nullISBN-10/13 from the wish's storefront sources, when one carries it.
    • notesstring or nullFree-form operator or requester notes.
    • statusRequestStatusrequiredLifecycle status for the row (user, request, …).
    • work_keystringBibliographic card key (isbn:… / asin:… / soft:…) clients use to match a wish to a catalog card. Derived from the work's title and authors and the sources' identifiers on every read, never stored.
    • work_idstringrequiredThe work the wish is for; wishes for one work are one queue entry.
    • edition_idstring or nullThe edition the wish named, when the library knows it.
    • resolved_edition_idstring or nullEdition (editions.id) the library holds once the wishlist item is fulfilled.
    • cover_urlstring or nullHTTPS URL for cover art when known.
    • cover_pathstring or nullSame-origin path of this cover's processed images, set by the daemon when cover_url is an https URL. Append /128 (thumbnail), /360 (card) or /full, so a client can show covers without loading cover_url from another site.
    • sourcesarray of TitleRequestSourceRecordPer-storefront snapshots (empty for legacy rows).
    • descriptionstring or nullBlurb / synopsis text (may contain HTML).
    • subtitlestring or nullOptional subtitle from bibliographic metadata.
    • narratorsstring or nullComma-separated or JSON narrator list when present.
    • seriesstring or nullSeries name when the title belongs to a series.
    • series_indexstring or nullPosition within the series (storefront string form).
    • publisherstring or nullPublisher name from metadata enrichment or the storefront.
    • length_minutesinteger (int64) or nullRuntime in whole minutes when the storefront reports it.
    • published_atstring or nullPublication date string from the storefront or enrichment.
    • genresstring or nullMerged genre / category list for display.
    • languagestring or nullBCP-47 or storefront language code when known.
    • store_editionsarray of WishlistStoreEditionDistinct storefront editions contributing to this wishlist item.
    • purchase_hintsarray of WishlistPurchaseHintPurchase URLs and prices observed per storefront.
    • created_atstring (date-time)requiredRFC 3339 timestamp when the row was inserted.
    • updated_atstring (date-time)requiredRFC 3339 timestamp when the row was last modified.
  • 401No signed-in caller. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The request could not be read or written. Body: string (text/plain)
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/wishlist' \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/wishlist' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/wishlist",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/wishlist", {
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/wishlist")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The caller's open requests.

[
  {
    "id": 31,
    "uuid": "7c1e5a2b-3d4f-4e6a-9b8c-0d1e2f3a4b5c",
    "identity_id": 7,
    "title": "The Left Hand of Darkness",
    "authors": "Ursula K. Le Guin",
    "asin": "B002V0QK4C",
    "isbn": "9780441478125",
    "notes": "Book club pick for March",
    "status": "open",
    "work_key": "isbn:9780441478125",
    "work_id": "7c1e9a2b-3d4f-4e5a-9b6c-8d7e0f1a2b3c",
    "edition_id": "0b8e3f2a-5c1d-5e7f-9a2b-4c6d8e0f1a3b",
    "resolved_edition_id": "3f2c0d7e-9d4b-4a62-8b1e-6d0f7c2a9b31",
    "cover_url": "https://images.example.com/covers/9780441478125.jpg",
    "cover_path": "/api/covers/aHR0cHM6Ly9pbWFnZXMuZXhhbXBsZS5jb20vYy5qcGc.q2fW1n4bJm0Rg9xV3kTzPA",
    "sources": [
      {
        "id": 88,
        "title_request_id": 31,
        "source": "libro",
        "product_id": "9780441478125",
        "title": "The Left Hand of Darkness",
        "subtitle": "A Hainish Novel",
        "authors": "Ursula K. Le Guin",
        "narrators": "George Guidall",
        "series": "Hainish Cycle",
        "series_index": "4",
        "asin": "B002V0QK4C",
        "isbn": "9780441478125",
        "description": "An envoy to the planet Gethen must win the trust of a people who have no fixed gender.",
        "publisher": "Blackstone Publishing",
        "length_minutes": 560,
        "published_at": "2005-06-21",
        "categories": "Science Fiction & Fantasy > Science Fiction",
        "language": "en",
        "cover_url": "https://images.example.com/covers/9780441478125.jpg",
        "url": "https://libro.fm/audiobooks/9780441478125",
        "price_cents": 2499,
        "currency": "USD",
        "price_label": "$24.99",
        "list_price_cents": 2999,
        "list_price_label": "$29.99",
        "member_price_cents": 1499,
        "member_price_label": "$14.99",
        "observed_at": "2026-10-29T10:12:00Z",
        "created_at": "2026-10-29T10:12:00Z",
        "updated_at": "2026-10-29T10:14:22Z"
      }
    ],
    "description": "An envoy to the planet Gethen must win the trust of a people who have no fixed gender.",
    "subtitle": "A Hainish Novel",
    "narrators": "George Guidall",
    "series": "Hainish Cycle",
    "series_index": "4",
    "publisher": "Blackstone Publishing",
    "length_minutes": 560,
    "published_at": "2005-06-21",
    "genres": "Science Fiction, Classics",
    "language": "en",
    "store_editions": [
      {
        "source": "libro",
        "product_id": "9780441478125"
      }
    ],
    "purchase_hints": [
      {
        "source": "libro",
        "product_id": "9780441478125",
        "title": "The Left Hand of Darkness",
        "url": "https://libro.fm/audiobooks/9780441478125",
        "price_cents": 2499,
        "currency": "USD",
        "price_label": "$24.99",
        "list_price_cents": 2999,
        "list_price_label": "$29.99",
        "member_price_cents": 1499,
        "member_price_label": "$14.99"
      }
    ],
    "created_at": "2026-10-29T10:12:00Z",
    "updated_at": "2026-10-29T10:14:22Z"
  }
]

Schema:

{
  "type": "array",
  "items": {
    "type": "object",
    "description": "Personal wishlist row (also contributes to the shared global queue while open).",
    "required": [
      "id",
      "uuid",
      "title",
      "status",
      "work_id",
      "created_at",
      "updated_at"
    ],
    "properties": {
      "id": {
        "type": "integer",
        "format": "int64",
        "description": "Surrogate primary key assigned by the database.",
        "example": 31
      },
      "uuid": {
        "type": "string",
        "description": "Stable UUID for this row (API / foreign-key identity).",
        "example": "7c1e5a2b-3d4f-4e6a-9b8c-0d1e2f3a4b5c"
      },
      "identity_id": {
        "type": [
          "integer",
          "null"
        ],
        "format": "int64",
        "description": "Foreign key to `portal_identities.id`.",
        "example": 7
      },
      "title": {
        "type": "string",
        "description": "Display title: the title of the wish's work.",
        "example": "The Left Hand of Darkness"
      },
      "authors": {
        "type": [
          "string",
          "null"
        ],
        "description": "Comma-separated authors: the work's author credits in billing order.",
        "example": "Ursula K. Le Guin"
      },
      "asin": {
        "type": [
          "string",
          "null"
        ],
        "description": "Amazon ASIN from the wish's storefront sources, when one carries it.",
        "example": "B002V0QK4C"
      },
      "isbn": {
        "type": [
          "string",
          "null"
        ],
        "description": "ISBN-10/13 from the wish's storefront sources, when one carries it.",
        "example": "9780441478125"
      },
      "notes": {
        "type": [
          "string",
          "null"
        ],
        "description": "Free-form operator or requester notes.",
        "example": "Book club pick for March"
      },
      "status": {
        "type": "string",
        "description": "Lifecycle status for the row (user, request, …).",
        "enum": [
          "open",
          "cancelled"
        ]
      },
      "work_key": {
        "type": "string",
        "description": "Bibliographic card key (`isbn:…` / `asin:…` / `soft:…`) clients use\nto match a wish to a catalog card. Derived from the work's title and\nauthors and the sources' identifiers on every read, never stored.",
        "example": "isbn:9780441478125"
      },
      "work_id": {
        "type": "string",
        "description": "The work the wish is for; wishes for one work are one queue entry.",
        "example": "7c1e9a2b-3d4f-4e5a-9b6c-8d7e0f1a2b3c"
      },
      "edition_id": {
        "type": [
          "string",
          "null"
        ],
        "description": "The edition the wish named, when the library knows it.",
        "example": "0b8e3f2a-5c1d-5e7f-9a2b-4c6d8e0f1a3b"
      },
      "resolved_edition_id": {
        "type": [
          "string",
          "null"
        ],
        "description": "Edition (`editions.id`) the library holds once the wishlist item is fulfilled.",
        "example": "3f2c0d7e-9d4b-4a62-8b1e-6d0f7c2a9b31"
      },
      "cover_url": {
        "type": [
          "string",
          "null"
        ],
        "description": "HTTPS URL for cover art when known.",
        "example": "https://images.example.com/covers/9780441478125.jpg"
      },
      "cover_path": {
        "type": [
          "string",
          "null"
        ],
        "description": "Same-origin path of this cover's processed images, set by the daemon\nwhen `cover_url` is an `https` URL. Append `/128`\n(thumbnail), `/360` (card) or `/full`, so a client can show covers\nwithout loading `cover_url` from another site.",
        "example": "/api/covers/aHR0cHM6Ly9pbWFnZXMuZXhhbXBsZS5jb20vYy5qcGc.q2fW1n4bJm0Rg9xV3kTzPA"
      },
      "sources": {
        "type": "array",
        "items": {
          "type": "object",
          "description": "Per-storefront catalog/pricing snapshot attached to a wishlist row.",
          "required": [
            "id",
            "title_request_id",
            "source",
            "product_id",
            "created_at",
            "updated_at"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64",
              "description": "Surrogate primary key assigned by the database.",
              "example": 88
            },
            "title_request_id": {
              "type": "integer",
              "format": "int64",
              "description": "Foreign key to `title_requests.id`.",
              "example": 31
            },
            "source": {
              "type": "string",
              "description": "Content-source plugin id (`audible`, `libro`, …).",
              "example": "libro"
            },
            "product_id": {
              "type": "string",
              "description": "Storefront product id (ASIN, ISBN, UUID, …).",
              "example": "9780441478125"
            },
            "title": {
              "type": [
                "string",
                "null"
              ],
              "description": "Display title of the work or edition.",
              "example": "The Left Hand of Darkness"
            },
            "subtitle": {
              "type": [
                "string",
                "null"
              ],
              "description": "Optional subtitle from bibliographic metadata.",
              "example": "A Hainish Novel"
            },
            "authors": {
              "type": [
                "string",
                "null"
              ],
              "description": "Comma-separated or JSON author list from the storefront.",
              "example": "Ursula K. Le Guin"
            },
            "narrators": {
              "type": [
                "string",
                "null"
              ],
              "description": "Comma-separated or JSON narrator list when present.",
              "example": "George Guidall"
            },
            "series": {
              "type": [
                "string",
                "null"
              ],
              "description": "Series name when the title belongs to a series.",
              "example": "Hainish Cycle"
            },
            "series_index": {
              "type": [
                "string",
                "null"
              ],
              "description": "Position within the series (storefront string form).",
              "example": "4"
            },
            "asin": {
              "type": [
                "string",
                "null"
              ],
              "description": "Amazon ASIN when known; otherwise null.",
              "example": "B002V0QK4C"
            },
            "isbn": {
              "type": [
                "string",
                "null"
              ],
              "description": "ISBN-10/13 when known; otherwise null.",
              "example": "9780441478125"
            },
            "description": {
              "type": [
                "string",
                "null"
              ],
              "description": "Blurb / synopsis text (may contain HTML).",
              "example": "An envoy to the planet Gethen must win the trust of a people who have no fixed gender."
            },
            "publisher": {
              "type": [
                "string",
                "null"
              ],
              "description": "Publisher name from metadata enrichment or the storefront.",
              "example": "Blackstone Publishing"
            },
            "length_minutes": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int64",
              "description": "Runtime in whole minutes when the storefront reports it.",
              "example": 560
            },
            "published_at": {
              "type": [
                "string",
                "null"
              ],
              "description": "Publication date string from the storefront or enrichment.",
              "example": "2005-06-21"
            },
            "categories": {
              "type": [
                "string",
                "null"
              ],
              "description": "Storefront category / genre path list (serialized).",
              "example": "Science Fiction & Fantasy > Science Fiction"
            },
            "language": {
              "type": [
                "string",
                "null"
              ],
              "description": "BCP-47 or storefront language code when known.",
              "example": "en"
            },
            "cover_url": {
              "type": [
                "string",
                "null"
              ],
              "description": "HTTPS URL for cover art when known.",
              "example": "https://images.example.com/covers/9780441478125.jpg"
            },
            "url": {
              "type": [
                "string",
                "null"
              ],
              "description": "Storefront product or purchase URL when known.",
              "example": "https://libro.fm/audiobooks/9780441478125"
            },
            "price_cents": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int64",
              "description": "Observed price in minor currency units, when known.",
              "example": 2499
            },
            "currency": {
              "type": [
                "string",
                "null"
              ],
              "description": "ISO 4217 currency code for price fields.",
              "example": "USD"
            },
            "price_label": {
              "type": [
                "string",
                "null"
              ],
              "description": "Storefront-formatted price string for display.",
              "example": "$24.99"
            },
            "list_price_cents": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int64",
              "description": "List/MSRP price in minor units, when known.",
              "example": 2999
            },
            "list_price_label": {
              "type": [
                "string",
                "null"
              ],
              "description": "Storefront-formatted list price for display.",
              "example": "$29.99"
            },
            "member_price_cents": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int64",
              "description": "Member/subscriber price in minor units, when known.",
              "example": 1499
            },
            "member_price_label": {
              "type": [
                "string",
                "null"
              ],
              "description": "Storefront-formatted member price for display.",
              "example": "$14.99"
            },
            "observed_at": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "description": "RFC 3339 time when this storefront snapshot was observed.",
              "example": "2026-10-29T10:12:00Z"
            },
            "created_at": {
              "type": "string",
              "format": "date-time",
              "description": "RFC 3339 timestamp when the row was inserted.",
              "example": "2026-10-29T10:12:00Z"
            },
            "updated_at": {
              "type": "string",
              "format": "date-time",
              "description": "RFC 3339 timestamp when the row was last modified.",
              "example": "2026-10-29T10:14:22Z"
            }
          }
        },
        "description": "Per-storefront snapshots (empty for legacy rows)."
      },
      "description": {
        "type": [
          "string",
          "null"
        ],
        "description": "Blurb / synopsis text (may contain HTML).",
        "example": "An envoy to the planet Gethen must win the trust of a people who have no fixed gender."
      },
      "subtitle": {
        "type": [
          "string",
          "null"
        ],
        "description": "Optional subtitle from bibliographic metadata.",
        "example": "A Hainish Novel"
      },
      "narrators": {
        "type": [
          "string",
          "null"
        ],
        "description": "Comma-separated or JSON narrator list when present.",
        "example": "George Guidall"
      },
      "series": {
        "type": [
          "string",
          "null"
        ],
        "description": "Series name when the title belongs to a series.",
        "example": "Hainish Cycle"
      },
      "series_index": {
        "type": [
          "string",
          "null"
        ],
        "description": "Position within the series (storefront string form).",
        "example": "4"
      },
      "publisher": {
        "type": [
          "string",
          "null"
        ],
        "description": "Publisher name from metadata enrichment or the storefront.",
        "example": "Blackstone Publishing"
      },
      "length_minutes": {
        "type": [
          "integer",
          "null"
        ],
        "format": "int64",
        "description": "Runtime in whole minutes when the storefront reports it.",
        "example": 560
      },
      "published_at": {
        "type": [
          "string",
          "null"
        ],
        "description": "Publication date string from the storefront or enrichment.",
        "example": "2005-06-21"
      },
      "genres": {
        "type": [
          "string",
          "null"
        ],
        "description": "Merged genre / category list for display.",
        "example": "Science Fiction, Classics"
      },
      "language": {
        "type": [
          "string",
          "null"
        ],
        "description": "BCP-47 or storefront language code when known.",
        "example": "en"
      },
      "store_editions": {
        "type": "array",
        "items": {
          "type": "object",
          "description": "Storefront edition key for wishlist / queue payloads.",
          "required": [
            "source",
            "product_id"
          ],
          "properties": {
            "source": {
              "type": "string",
              "description": "Content-source plugin id (`audible`, `libro`, …).",
              "example": "libro"
            },
            "product_id": {
              "type": "string",
              "description": "Storefront product id (ASIN, ISBN, UUID, …).",
              "example": "9780441478125"
            }
          }
        },
        "description": "Distinct storefront editions contributing to this wishlist item."
      },
      "purchase_hints": {
        "type": "array",
        "items": {
          "type": "object",
          "description": "Snapshotted purchase link/price for a wishlist title.",
          "required": [
            "source",
            "product_id"
          ],
          "properties": {
            "source": {
              "type": "string",
              "description": "Content-source plugin id (`audible`, `libro`, …).",
              "example": "libro"
            },
            "product_id": {
              "type": "string",
              "description": "Storefront product id (ASIN, ISBN, UUID, …).",
              "example": "9780441478125"
            },
            "title": {
              "type": [
                "string",
                "null"
              ],
              "description": "Display title of the work or edition.",
              "example": "The Left Hand of Darkness"
            },
            "url": {
              "type": [
                "string",
                "null"
              ],
              "description": "Storefront product or purchase URL when known.",
              "example": "https://libro.fm/audiobooks/9780441478125"
            },
            "price_cents": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int64",
              "description": "Observed price in minor currency units, when known.",
              "example": 2499
            },
            "currency": {
              "type": [
                "string",
                "null"
              ],
              "description": "ISO 4217 currency code for price fields.",
              "example": "USD"
            },
            "price_label": {
              "type": [
                "string",
                "null"
              ],
              "description": "Storefront-formatted price string for display.",
              "example": "$24.99"
            },
            "list_price_cents": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int64",
              "description": "List/MSRP price in minor units, when known.",
              "example": 2999
            },
            "list_price_label": {
              "type": [
                "string",
                "null"
              ],
              "description": "Storefront-formatted list price for display.",
              "example": "$29.99"
            },
            "member_price_cents": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int64",
              "description": "Member/subscriber price in minor units, when known.",
              "example": 1499
            },
            "member_price_label": {
              "type": [
                "string",
                "null"
              ],
              "description": "Storefront-formatted member price for display.",
              "example": "$14.99"
            }
          }
        },
        "description": "Purchase URLs and prices observed per storefront."
      },
      "created_at": {
        "type": "string",
        "format": "date-time",
        "description": "RFC 3339 timestamp when the row was inserted.",
        "example": "2026-10-29T10:12:00Z"
      },
      "updated_at": {
        "type": "string",
        "format": "date-time",
        "description": "RFC 3339 timestamp when the row was last modified.",
        "example": "2026-10-29T10:14:22Z"
      }
    }
  }
}

Status 401: No signed-in caller.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable.

{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 500: The request could not be read or written.

ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection

Schema:

A text/plain body: a string.

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/wishlist

Creates a wishlist / title-request row for the authenticated caller.

Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).

Credentials: operatorToken or operatorSession or portalSession or clerkToken

Request body

application/json: CreateRequestBody

  • titlestringrequiredRequired title text; empty values are rejected with 400.
  • authorsstring or nullOptional author list as a single display string.
  • asinstring or nullOptional Audible ASIN used for work-key identity.
  • isbnstring or nullOptional ISBN used for work-key identity.
  • notesstring or nullOptional operator or member note stored on the request.
  • store_editionsarray of StoreEditionKnown storefront editions to persist as title_request_sources.
  • purchase_hintsarray of PurchaseHintOptional priced storefront links snapshotted at wishlist time.
  • cover_urlstring or nullOptional cover image URL snapshotted onto the request.
  • descriptionstring or nullOptional plot/summary text persisted with the request.
  • subtitlestring or nullOptional subtitle stored on the request and source rows.
  • narratorsstring or nullOptional narrator list as a single display string.
  • seriesstring or nullOptional series name.
  • series_indexstring or nullOptional series position as a display string.
  • publisherstring or nullOptional publisher name.
  • length_minutesinteger (int64) or nullOptional runtime in minutes.
  • published_atstring or nullOptional publication date as a display string.
  • genresstring or nullOptional genre list as a single display string.
  • languagestring or nullOptional content language code.

Responses

  • 200The new request. Body: TitleRequestRecord (application/json)30 fields
    • idinteger (int64)requiredSurrogate primary key assigned by the database.
    • uuidstringrequiredStable UUID for this row (API / foreign-key identity).
    • identity_idinteger (int64) or nullForeign key to portal_identities.id.
    • titlestringrequiredDisplay title: the title of the wish's work.
    • authorsstring or nullComma-separated authors: the work's author credits in billing order.
    • asinstring or nullAmazon ASIN from the wish's storefront sources, when one carries it.
    • isbnstring or nullISBN-10/13 from the wish's storefront sources, when one carries it.
    • notesstring or nullFree-form operator or requester notes.
    • statusRequestStatusrequiredLifecycle status for the row (user, request, …).
    • work_keystringBibliographic card key (isbn:… / asin:… / soft:…) clients use to match a wish to a catalog card. Derived from the work's title and authors and the sources' identifiers on every read, never stored.
    • work_idstringrequiredThe work the wish is for; wishes for one work are one queue entry.
    • edition_idstring or nullThe edition the wish named, when the library knows it.
    • resolved_edition_idstring or nullEdition (editions.id) the library holds once the wishlist item is fulfilled.
    • cover_urlstring or nullHTTPS URL for cover art when known.
    • cover_pathstring or nullSame-origin path of this cover's processed images, set by the daemon when cover_url is an https URL. Append /128 (thumbnail), /360 (card) or /full, so a client can show covers without loading cover_url from another site.
    • sourcesarray of TitleRequestSourceRecordPer-storefront snapshots (empty for legacy rows).
    • descriptionstring or nullBlurb / synopsis text (may contain HTML).
    • subtitlestring or nullOptional subtitle from bibliographic metadata.
    • narratorsstring or nullComma-separated or JSON narrator list when present.
    • seriesstring or nullSeries name when the title belongs to a series.
    • series_indexstring or nullPosition within the series (storefront string form).
    • publisherstring or nullPublisher name from metadata enrichment or the storefront.
    • length_minutesinteger (int64) or nullRuntime in whole minutes when the storefront reports it.
    • published_atstring or nullPublication date string from the storefront or enrichment.
    • genresstring or nullMerged genre / category list for display.
    • languagestring or nullBCP-47 or storefront language code when known.
    • store_editionsarray of WishlistStoreEditionDistinct storefront editions contributing to this wishlist item.
    • purchase_hintsarray of WishlistPurchaseHintPurchase URLs and prices observed per storefront.
    • created_atstring (date-time)requiredRFC 3339 timestamp when the row was inserted.
    • updated_atstring (date-time)requiredRFC 3339 timestamp when the row was last modified.
  • 400The title is missing or invalid. As text/plain, when the body is not syntactically valid JSON. Body: string (text/plain)
  • 401No signed-in caller. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The request could not be read or written. Body: string (text/plain)
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/wishlist' \
    -X POST \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{"title": "The Left Hand of Darkness"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/wishlist' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{"title": "The Left Hand of Darkness"}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/wishlist",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={"title": "The Left Hand of Darkness"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/wishlist", {
  method: "POST",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"title": "The Left Hand of Darkness"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/wishlist")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({"title": "The Left Hand of Darkness"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The new request.

{
  "id": 31,
  "uuid": "7c1e5a2b-3d4f-4e6a-9b8c-0d1e2f3a4b5c",
  "identity_id": 7,
  "title": "The Left Hand of Darkness",
  "authors": "Ursula K. Le Guin",
  "asin": "B002V0QK4C",
  "isbn": "9780441478125",
  "notes": "Book club pick for March",
  "status": "open",
  "work_key": "isbn:9780441478125",
  "work_id": "7c1e9a2b-3d4f-4e5a-9b6c-8d7e0f1a2b3c",
  "edition_id": "0b8e3f2a-5c1d-5e7f-9a2b-4c6d8e0f1a3b",
  "resolved_edition_id": "3f2c0d7e-9d4b-4a62-8b1e-6d0f7c2a9b31",
  "cover_url": "https://images.example.com/covers/9780441478125.jpg",
  "cover_path": "/api/covers/aHR0cHM6Ly9pbWFnZXMuZXhhbXBsZS5jb20vYy5qcGc.q2fW1n4bJm0Rg9xV3kTzPA",
  "sources": [
    {
      "id": 88,
      "title_request_id": 31,
      "source": "libro",
      "product_id": "9780441478125",
      "title": "The Left Hand of Darkness",
      "subtitle": "A Hainish Novel",
      "authors": "Ursula K. Le Guin",
      "narrators": "George Guidall",
      "series": "Hainish Cycle",
      "series_index": "4",
      "asin": "B002V0QK4C",
      "isbn": "9780441478125",
      "description": "An envoy to the planet Gethen must win the trust of a people who have no fixed gender.",
      "publisher": "Blackstone Publishing",
      "length_minutes": 560,
      "published_at": "2005-06-21",
      "categories": "Science Fiction & Fantasy > Science Fiction",
      "language": "en",
      "cover_url": "https://images.example.com/covers/9780441478125.jpg",
      "url": "https://libro.fm/audiobooks/9780441478125",
      "price_cents": 2499,
      "currency": "USD",
      "price_label": "$24.99",
      "list_price_cents": 2999,
      "list_price_label": "$29.99",
      "member_price_cents": 1499,
      "member_price_label": "$14.99",
      "observed_at": "2026-10-29T10:12:00Z",
      "created_at": "2026-10-29T10:12:00Z",
      "updated_at": "2026-10-29T10:14:22Z"
    }
  ],
  "description": "An envoy to the planet Gethen must win the trust of a people who have no fixed gender.",
  "subtitle": "A Hainish Novel",
  "narrators": "George Guidall",
  "series": "Hainish Cycle",
  "series_index": "4",
  "publisher": "Blackstone Publishing",
  "length_minutes": 560,
  "published_at": "2005-06-21",
  "genres": "Science Fiction, Classics",
  "language": "en",
  "store_editions": [
    {
      "source": "libro",
      "product_id": "9780441478125"
    }
  ],
  "purchase_hints": [
    {
      "source": "libro",
      "product_id": "9780441478125",
      "title": "The Left Hand of Darkness",
      "url": "https://libro.fm/audiobooks/9780441478125",
      "price_cents": 2499,
      "currency": "USD",
      "price_label": "$24.99",
      "list_price_cents": 2999,
      "list_price_label": "$29.99",
      "member_price_cents": 1499,
      "member_price_label": "$14.99"
    }
  ],
  "created_at": "2026-10-29T10:12:00Z",
  "updated_at": "2026-10-29T10:14:22Z"
}

Schema:

{
  "type": "object",
  "description": "Personal wishlist row (also contributes to the shared global queue while open).",
  "required": [
    "id",
    "uuid",
    "title",
    "status",
    "work_id",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64",
      "description": "Surrogate primary key assigned by the database.",
      "example": 31
    },
    "uuid": {
      "type": "string",
      "description": "Stable UUID for this row (API / foreign-key identity).",
      "example": "7c1e5a2b-3d4f-4e6a-9b8c-0d1e2f3a4b5c"
    },
    "identity_id": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "Foreign key to `portal_identities.id`.",
      "example": 7
    },
    "title": {
      "type": "string",
      "description": "Display title: the title of the wish's work.",
      "example": "The Left Hand of Darkness"
    },
    "authors": {
      "type": [
        "string",
        "null"
      ],
      "description": "Comma-separated authors: the work's author credits in billing order.",
      "example": "Ursula K. Le Guin"
    },
    "asin": {
      "type": [
        "string",
        "null"
      ],
      "description": "Amazon ASIN from the wish's storefront sources, when one carries it.",
      "example": "B002V0QK4C"
    },
    "isbn": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISBN-10/13 from the wish's storefront sources, when one carries it.",
      "example": "9780441478125"
    },
    "notes": {
      "type": [
        "string",
        "null"
      ],
      "description": "Free-form operator or requester notes.",
      "example": "Book club pick for March"
    },
    "status": {
      "type": "string",
      "description": "Lifecycle status for the row (user, request, …).",
      "enum": [
        "open",
        "cancelled"
      ]
    },
    "work_key": {
      "type": "string",
      "description": "Bibliographic card key (`isbn:…` / `asin:…` / `soft:…`) clients use\nto match a wish to a catalog card. Derived from the work's title and\nauthors and the sources' identifiers on every read, never stored.",
      "example": "isbn:9780441478125"
    },
    "work_id": {
      "type": "string",
      "description": "The work the wish is for; wishes for one work are one queue entry.",
      "example": "7c1e9a2b-3d4f-4e5a-9b6c-8d7e0f1a2b3c"
    },
    "edition_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The edition the wish named, when the library knows it.",
      "example": "0b8e3f2a-5c1d-5e7f-9a2b-4c6d8e0f1a3b"
    },
    "resolved_edition_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Edition (`editions.id`) the library holds once the wishlist item is fulfilled.",
      "example": "3f2c0d7e-9d4b-4a62-8b1e-6d0f7c2a9b31"
    },
    "cover_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "HTTPS URL for cover art when known.",
      "example": "https://images.example.com/covers/9780441478125.jpg"
    },
    "cover_path": {
      "type": [
        "string",
        "null"
      ],
      "description": "Same-origin path of this cover's processed images, set by the daemon\nwhen `cover_url` is an `https` URL. Append `/128`\n(thumbnail), `/360` (card) or `/full`, so a client can show covers\nwithout loading `cover_url` from another site.",
      "example": "/api/covers/aHR0cHM6Ly9pbWFnZXMuZXhhbXBsZS5jb20vYy5qcGc.q2fW1n4bJm0Rg9xV3kTzPA"
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Per-storefront catalog/pricing snapshot attached to a wishlist row.",
        "required": [
          "id",
          "title_request_id",
          "source",
          "product_id",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Surrogate primary key assigned by the database.",
            "example": 88
          },
          "title_request_id": {
            "type": "integer",
            "format": "int64",
            "description": "Foreign key to `title_requests.id`.",
            "example": 31
          },
          "source": {
            "type": "string",
            "description": "Content-source plugin id (`audible`, `libro`, …).",
            "example": "libro"
          },
          "product_id": {
            "type": "string",
            "description": "Storefront product id (ASIN, ISBN, UUID, …).",
            "example": "9780441478125"
          },
          "title": {
            "type": [
              "string",
              "null"
            ],
            "description": "Display title of the work or edition.",
            "example": "The Left Hand of Darkness"
          },
          "subtitle": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional subtitle from bibliographic metadata.",
            "example": "A Hainish Novel"
          },
          "authors": {
            "type": [
              "string",
              "null"
            ],
            "description": "Comma-separated or JSON author list from the storefront.",
            "example": "Ursula K. Le Guin"
          },
          "narrators": {
            "type": [
              "string",
              "null"
            ],
            "description": "Comma-separated or JSON narrator list when present.",
            "example": "George Guidall"
          },
          "series": {
            "type": [
              "string",
              "null"
            ],
            "description": "Series name when the title belongs to a series.",
            "example": "Hainish Cycle"
          },
          "series_index": {
            "type": [
              "string",
              "null"
            ],
            "description": "Position within the series (storefront string form).",
            "example": "4"
          },
          "asin": {
            "type": [
              "string",
              "null"
            ],
            "description": "Amazon ASIN when known; otherwise null.",
            "example": "B002V0QK4C"
          },
          "isbn": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISBN-10/13 when known; otherwise null.",
            "example": "9780441478125"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Blurb / synopsis text (may contain HTML).",
            "example": "An envoy to the planet Gethen must win the trust of a people who have no fixed gender."
          },
          "publisher": {
            "type": [
              "string",
              "null"
            ],
            "description": "Publisher name from metadata enrichment or the storefront.",
            "example": "Blackstone Publishing"
          },
          "length_minutes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Runtime in whole minutes when the storefront reports it.",
            "example": 560
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "Publication date string from the storefront or enrichment.",
            "example": "2005-06-21"
          },
          "categories": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront category / genre path list (serialized).",
            "example": "Science Fiction & Fantasy > Science Fiction"
          },
          "language": {
            "type": [
              "string",
              "null"
            ],
            "description": "BCP-47 or storefront language code when known.",
            "example": "en"
          },
          "cover_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "HTTPS URL for cover art when known.",
            "example": "https://images.example.com/covers/9780441478125.jpg"
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront product or purchase URL when known.",
            "example": "https://libro.fm/audiobooks/9780441478125"
          },
          "price_cents": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Observed price in minor currency units, when known.",
            "example": 2499
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 4217 currency code for price fields.",
            "example": "USD"
          },
          "price_label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront-formatted price string for display.",
            "example": "$24.99"
          },
          "list_price_cents": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "List/MSRP price in minor units, when known.",
            "example": 2999
          },
          "list_price_label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront-formatted list price for display.",
            "example": "$29.99"
          },
          "member_price_cents": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Member/subscriber price in minor units, when known.",
            "example": 1499
          },
          "member_price_label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront-formatted member price for display.",
            "example": "$14.99"
          },
          "observed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 time when this storefront snapshot was observed.",
            "example": "2026-10-29T10:12:00Z"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp when the row was inserted.",
            "example": "2026-10-29T10:12:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp when the row was last modified.",
            "example": "2026-10-29T10:14:22Z"
          }
        }
      },
      "description": "Per-storefront snapshots (empty for legacy rows)."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "Blurb / synopsis text (may contain HTML).",
      "example": "An envoy to the planet Gethen must win the trust of a people who have no fixed gender."
    },
    "subtitle": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional subtitle from bibliographic metadata.",
      "example": "A Hainish Novel"
    },
    "narrators": {
      "type": [
        "string",
        "null"
      ],
      "description": "Comma-separated or JSON narrator list when present.",
      "example": "George Guidall"
    },
    "series": {
      "type": [
        "string",
        "null"
      ],
      "description": "Series name when the title belongs to a series.",
      "example": "Hainish Cycle"
    },
    "series_index": {
      "type": [
        "string",
        "null"
      ],
      "description": "Position within the series (storefront string form).",
      "example": "4"
    },
    "publisher": {
      "type": [
        "string",
        "null"
      ],
      "description": "Publisher name from metadata enrichment or the storefront.",
      "example": "Blackstone Publishing"
    },
    "length_minutes": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "Runtime in whole minutes when the storefront reports it.",
      "example": 560
    },
    "published_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Publication date string from the storefront or enrichment.",
      "example": "2005-06-21"
    },
    "genres": {
      "type": [
        "string",
        "null"
      ],
      "description": "Merged genre / category list for display.",
      "example": "Science Fiction, Classics"
    },
    "language": {
      "type": [
        "string",
        "null"
      ],
      "description": "BCP-47 or storefront language code when known.",
      "example": "en"
    },
    "store_editions": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Storefront edition key for wishlist / queue payloads.",
        "required": [
          "source",
          "product_id"
        ],
        "properties": {
          "source": {
            "type": "string",
            "description": "Content-source plugin id (`audible`, `libro`, …).",
            "example": "libro"
          },
          "product_id": {
            "type": "string",
            "description": "Storefront product id (ASIN, ISBN, UUID, …).",
            "example": "9780441478125"
          }
        }
      },
      "description": "Distinct storefront editions contributing to this wishlist item."
    },
    "purchase_hints": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Snapshotted purchase link/price for a wishlist title.",
        "required": [
          "source",
          "product_id"
        ],
        "properties": {
          "source": {
            "type": "string",
            "description": "Content-source plugin id (`audible`, `libro`, …).",
            "example": "libro"
          },
          "product_id": {
            "type": "string",
            "description": "Storefront product id (ASIN, ISBN, UUID, …).",
            "example": "9780441478125"
          },
          "title": {
            "type": [
              "string",
              "null"
            ],
            "description": "Display title of the work or edition.",
            "example": "The Left Hand of Darkness"
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront product or purchase URL when known.",
            "example": "https://libro.fm/audiobooks/9780441478125"
          },
          "price_cents": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Observed price in minor currency units, when known.",
            "example": 2499
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 4217 currency code for price fields.",
            "example": "USD"
          },
          "price_label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront-formatted price string for display.",
            "example": "$24.99"
          },
          "list_price_cents": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "List/MSRP price in minor units, when known.",
            "example": 2999
          },
          "list_price_label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront-formatted list price for display.",
            "example": "$29.99"
          },
          "member_price_cents": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Member/subscriber price in minor units, when known.",
            "example": 1499
          },
          "member_price_label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront-formatted member price for display.",
            "example": "$14.99"
          }
        }
      },
      "description": "Purchase URLs and prices observed per storefront."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp when the row was inserted.",
      "example": "2026-10-29T10:12:00Z"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp when the row was last modified.",
      "example": "2026-10-29T10:14:22Z"
    }
  }
}

Status 400: The title is missing or invalid. As text/plain, when the body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: No signed-in caller.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `title` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The request could not be read or written.

ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection

Schema:

A text/plain body: a string.

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

DELETE /api/wishlist/{uuid}

Cancels an open wishlist item the caller owns; others get 403.

Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).

Credentials: operatorToken or operatorSession or portalSession or clerkToken

Parameters

  • uuidpathstringrequiredRequest UUID.

Responses

  • 200The cancelled request. Body: TitleRequestRecord (application/json)30 fields
    • idinteger (int64)requiredSurrogate primary key assigned by the database.
    • uuidstringrequiredStable UUID for this row (API / foreign-key identity).
    • identity_idinteger (int64) or nullForeign key to portal_identities.id.
    • titlestringrequiredDisplay title: the title of the wish's work.
    • authorsstring or nullComma-separated authors: the work's author credits in billing order.
    • asinstring or nullAmazon ASIN from the wish's storefront sources, when one carries it.
    • isbnstring or nullISBN-10/13 from the wish's storefront sources, when one carries it.
    • notesstring or nullFree-form operator or requester notes.
    • statusRequestStatusrequiredLifecycle status for the row (user, request, …).
    • work_keystringBibliographic card key (isbn:… / asin:… / soft:…) clients use to match a wish to a catalog card. Derived from the work's title and authors and the sources' identifiers on every read, never stored.
    • work_idstringrequiredThe work the wish is for; wishes for one work are one queue entry.
    • edition_idstring or nullThe edition the wish named, when the library knows it.
    • resolved_edition_idstring or nullEdition (editions.id) the library holds once the wishlist item is fulfilled.
    • cover_urlstring or nullHTTPS URL for cover art when known.
    • cover_pathstring or nullSame-origin path of this cover's processed images, set by the daemon when cover_url is an https URL. Append /128 (thumbnail), /360 (card) or /full, so a client can show covers without loading cover_url from another site.
    • sourcesarray of TitleRequestSourceRecordPer-storefront snapshots (empty for legacy rows).
    • descriptionstring or nullBlurb / synopsis text (may contain HTML).
    • subtitlestring or nullOptional subtitle from bibliographic metadata.
    • narratorsstring or nullComma-separated or JSON narrator list when present.
    • seriesstring or nullSeries name when the title belongs to a series.
    • series_indexstring or nullPosition within the series (storefront string form).
    • publisherstring or nullPublisher name from metadata enrichment or the storefront.
    • length_minutesinteger (int64) or nullRuntime in whole minutes when the storefront reports it.
    • published_atstring or nullPublication date string from the storefront or enrichment.
    • genresstring or nullMerged genre / category list for display.
    • languagestring or nullBCP-47 or storefront language code when known.
    • store_editionsarray of WishlistStoreEditionDistinct storefront editions contributing to this wishlist item.
    • purchase_hintsarray of WishlistPurchaseHintPurchase URLs and prices observed per storefront.
    • created_atstring (date-time)requiredRFC 3339 timestamp when the row was inserted.
    • updated_atstring (date-time)requiredRFC 3339 timestamp when the row was last modified.
  • 400Only open wishlist items can be removed. Body: string (text/plain)
  • 401No signed-in caller. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The request belongs to someone else. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: string (text/plain); ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 404No such request. Body: string (text/plain)
  • 500The request could not be read or written. Body: string (text/plain)
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/wishlist/<uuid>' \
    -X DELETE \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/wishlist/<uuid>' `
    -Method Delete `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.delete(
    "http://127.0.0.1:8787/api/wishlist/<uuid>",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/wishlist/<uuid>", {
  method: "DELETE",
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .delete("http://127.0.0.1:8787/api/wishlist/<uuid>")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The cancelled request.

{
  "id": 31,
  "uuid": "7c1e5a2b-3d4f-4e6a-9b8c-0d1e2f3a4b5c",
  "identity_id": 7,
  "title": "The Left Hand of Darkness",
  "authors": "Ursula K. Le Guin",
  "asin": "B002V0QK4C",
  "isbn": "9780441478125",
  "notes": "Book club pick for March",
  "status": "open",
  "work_key": "isbn:9780441478125",
  "work_id": "7c1e9a2b-3d4f-4e5a-9b6c-8d7e0f1a2b3c",
  "edition_id": "0b8e3f2a-5c1d-5e7f-9a2b-4c6d8e0f1a3b",
  "resolved_edition_id": "3f2c0d7e-9d4b-4a62-8b1e-6d0f7c2a9b31",
  "cover_url": "https://images.example.com/covers/9780441478125.jpg",
  "cover_path": "/api/covers/aHR0cHM6Ly9pbWFnZXMuZXhhbXBsZS5jb20vYy5qcGc.q2fW1n4bJm0Rg9xV3kTzPA",
  "sources": [
    {
      "id": 88,
      "title_request_id": 31,
      "source": "libro",
      "product_id": "9780441478125",
      "title": "The Left Hand of Darkness",
      "subtitle": "A Hainish Novel",
      "authors": "Ursula K. Le Guin",
      "narrators": "George Guidall",
      "series": "Hainish Cycle",
      "series_index": "4",
      "asin": "B002V0QK4C",
      "isbn": "9780441478125",
      "description": "An envoy to the planet Gethen must win the trust of a people who have no fixed gender.",
      "publisher": "Blackstone Publishing",
      "length_minutes": 560,
      "published_at": "2005-06-21",
      "categories": "Science Fiction & Fantasy > Science Fiction",
      "language": "en",
      "cover_url": "https://images.example.com/covers/9780441478125.jpg",
      "url": "https://libro.fm/audiobooks/9780441478125",
      "price_cents": 2499,
      "currency": "USD",
      "price_label": "$24.99",
      "list_price_cents": 2999,
      "list_price_label": "$29.99",
      "member_price_cents": 1499,
      "member_price_label": "$14.99",
      "observed_at": "2026-10-29T10:12:00Z",
      "created_at": "2026-10-29T10:12:00Z",
      "updated_at": "2026-10-29T10:14:22Z"
    }
  ],
  "description": "An envoy to the planet Gethen must win the trust of a people who have no fixed gender.",
  "subtitle": "A Hainish Novel",
  "narrators": "George Guidall",
  "series": "Hainish Cycle",
  "series_index": "4",
  "publisher": "Blackstone Publishing",
  "length_minutes": 560,
  "published_at": "2005-06-21",
  "genres": "Science Fiction, Classics",
  "language": "en",
  "store_editions": [
    {
      "source": "libro",
      "product_id": "9780441478125"
    }
  ],
  "purchase_hints": [
    {
      "source": "libro",
      "product_id": "9780441478125",
      "title": "The Left Hand of Darkness",
      "url": "https://libro.fm/audiobooks/9780441478125",
      "price_cents": 2499,
      "currency": "USD",
      "price_label": "$24.99",
      "list_price_cents": 2999,
      "list_price_label": "$29.99",
      "member_price_cents": 1499,
      "member_price_label": "$14.99"
    }
  ],
  "created_at": "2026-10-29T10:12:00Z",
  "updated_at": "2026-10-29T10:14:22Z"
}

Schema:

{
  "type": "object",
  "description": "Personal wishlist row (also contributes to the shared global queue while open).",
  "required": [
    "id",
    "uuid",
    "title",
    "status",
    "work_id",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64",
      "description": "Surrogate primary key assigned by the database.",
      "example": 31
    },
    "uuid": {
      "type": "string",
      "description": "Stable UUID for this row (API / foreign-key identity).",
      "example": "7c1e5a2b-3d4f-4e6a-9b8c-0d1e2f3a4b5c"
    },
    "identity_id": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "Foreign key to `portal_identities.id`.",
      "example": 7
    },
    "title": {
      "type": "string",
      "description": "Display title: the title of the wish's work.",
      "example": "The Left Hand of Darkness"
    },
    "authors": {
      "type": [
        "string",
        "null"
      ],
      "description": "Comma-separated authors: the work's author credits in billing order.",
      "example": "Ursula K. Le Guin"
    },
    "asin": {
      "type": [
        "string",
        "null"
      ],
      "description": "Amazon ASIN from the wish's storefront sources, when one carries it.",
      "example": "B002V0QK4C"
    },
    "isbn": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISBN-10/13 from the wish's storefront sources, when one carries it.",
      "example": "9780441478125"
    },
    "notes": {
      "type": [
        "string",
        "null"
      ],
      "description": "Free-form operator or requester notes.",
      "example": "Book club pick for March"
    },
    "status": {
      "type": "string",
      "description": "Lifecycle status for the row (user, request, …).",
      "enum": [
        "open",
        "cancelled"
      ]
    },
    "work_key": {
      "type": "string",
      "description": "Bibliographic card key (`isbn:…` / `asin:…` / `soft:…`) clients use\nto match a wish to a catalog card. Derived from the work's title and\nauthors and the sources' identifiers on every read, never stored.",
      "example": "isbn:9780441478125"
    },
    "work_id": {
      "type": "string",
      "description": "The work the wish is for; wishes for one work are one queue entry.",
      "example": "7c1e9a2b-3d4f-4e5a-9b6c-8d7e0f1a2b3c"
    },
    "edition_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The edition the wish named, when the library knows it.",
      "example": "0b8e3f2a-5c1d-5e7f-9a2b-4c6d8e0f1a3b"
    },
    "resolved_edition_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Edition (`editions.id`) the library holds once the wishlist item is fulfilled.",
      "example": "3f2c0d7e-9d4b-4a62-8b1e-6d0f7c2a9b31"
    },
    "cover_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "HTTPS URL for cover art when known.",
      "example": "https://images.example.com/covers/9780441478125.jpg"
    },
    "cover_path": {
      "type": [
        "string",
        "null"
      ],
      "description": "Same-origin path of this cover's processed images, set by the daemon\nwhen `cover_url` is an `https` URL. Append `/128`\n(thumbnail), `/360` (card) or `/full`, so a client can show covers\nwithout loading `cover_url` from another site.",
      "example": "/api/covers/aHR0cHM6Ly9pbWFnZXMuZXhhbXBsZS5jb20vYy5qcGc.q2fW1n4bJm0Rg9xV3kTzPA"
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Per-storefront catalog/pricing snapshot attached to a wishlist row.",
        "required": [
          "id",
          "title_request_id",
          "source",
          "product_id",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Surrogate primary key assigned by the database.",
            "example": 88
          },
          "title_request_id": {
            "type": "integer",
            "format": "int64",
            "description": "Foreign key to `title_requests.id`.",
            "example": 31
          },
          "source": {
            "type": "string",
            "description": "Content-source plugin id (`audible`, `libro`, …).",
            "example": "libro"
          },
          "product_id": {
            "type": "string",
            "description": "Storefront product id (ASIN, ISBN, UUID, …).",
            "example": "9780441478125"
          },
          "title": {
            "type": [
              "string",
              "null"
            ],
            "description": "Display title of the work or edition.",
            "example": "The Left Hand of Darkness"
          },
          "subtitle": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional subtitle from bibliographic metadata.",
            "example": "A Hainish Novel"
          },
          "authors": {
            "type": [
              "string",
              "null"
            ],
            "description": "Comma-separated or JSON author list from the storefront.",
            "example": "Ursula K. Le Guin"
          },
          "narrators": {
            "type": [
              "string",
              "null"
            ],
            "description": "Comma-separated or JSON narrator list when present.",
            "example": "George Guidall"
          },
          "series": {
            "type": [
              "string",
              "null"
            ],
            "description": "Series name when the title belongs to a series.",
            "example": "Hainish Cycle"
          },
          "series_index": {
            "type": [
              "string",
              "null"
            ],
            "description": "Position within the series (storefront string form).",
            "example": "4"
          },
          "asin": {
            "type": [
              "string",
              "null"
            ],
            "description": "Amazon ASIN when known; otherwise null.",
            "example": "B002V0QK4C"
          },
          "isbn": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISBN-10/13 when known; otherwise null.",
            "example": "9780441478125"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Blurb / synopsis text (may contain HTML).",
            "example": "An envoy to the planet Gethen must win the trust of a people who have no fixed gender."
          },
          "publisher": {
            "type": [
              "string",
              "null"
            ],
            "description": "Publisher name from metadata enrichment or the storefront.",
            "example": "Blackstone Publishing"
          },
          "length_minutes": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Runtime in whole minutes when the storefront reports it.",
            "example": 560
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "Publication date string from the storefront or enrichment.",
            "example": "2005-06-21"
          },
          "categories": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront category / genre path list (serialized).",
            "example": "Science Fiction & Fantasy > Science Fiction"
          },
          "language": {
            "type": [
              "string",
              "null"
            ],
            "description": "BCP-47 or storefront language code when known.",
            "example": "en"
          },
          "cover_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "HTTPS URL for cover art when known.",
            "example": "https://images.example.com/covers/9780441478125.jpg"
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront product or purchase URL when known.",
            "example": "https://libro.fm/audiobooks/9780441478125"
          },
          "price_cents": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Observed price in minor currency units, when known.",
            "example": 2499
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 4217 currency code for price fields.",
            "example": "USD"
          },
          "price_label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront-formatted price string for display.",
            "example": "$24.99"
          },
          "list_price_cents": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "List/MSRP price in minor units, when known.",
            "example": 2999
          },
          "list_price_label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront-formatted list price for display.",
            "example": "$29.99"
          },
          "member_price_cents": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Member/subscriber price in minor units, when known.",
            "example": 1499
          },
          "member_price_label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront-formatted member price for display.",
            "example": "$14.99"
          },
          "observed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC 3339 time when this storefront snapshot was observed.",
            "example": "2026-10-29T10:12:00Z"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp when the row was inserted.",
            "example": "2026-10-29T10:12:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp when the row was last modified.",
            "example": "2026-10-29T10:14:22Z"
          }
        }
      },
      "description": "Per-storefront snapshots (empty for legacy rows)."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "Blurb / synopsis text (may contain HTML).",
      "example": "An envoy to the planet Gethen must win the trust of a people who have no fixed gender."
    },
    "subtitle": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional subtitle from bibliographic metadata.",
      "example": "A Hainish Novel"
    },
    "narrators": {
      "type": [
        "string",
        "null"
      ],
      "description": "Comma-separated or JSON narrator list when present.",
      "example": "George Guidall"
    },
    "series": {
      "type": [
        "string",
        "null"
      ],
      "description": "Series name when the title belongs to a series.",
      "example": "Hainish Cycle"
    },
    "series_index": {
      "type": [
        "string",
        "null"
      ],
      "description": "Position within the series (storefront string form).",
      "example": "4"
    },
    "publisher": {
      "type": [
        "string",
        "null"
      ],
      "description": "Publisher name from metadata enrichment or the storefront.",
      "example": "Blackstone Publishing"
    },
    "length_minutes": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "Runtime in whole minutes when the storefront reports it.",
      "example": 560
    },
    "published_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Publication date string from the storefront or enrichment.",
      "example": "2005-06-21"
    },
    "genres": {
      "type": [
        "string",
        "null"
      ],
      "description": "Merged genre / category list for display.",
      "example": "Science Fiction, Classics"
    },
    "language": {
      "type": [
        "string",
        "null"
      ],
      "description": "BCP-47 or storefront language code when known.",
      "example": "en"
    },
    "store_editions": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Storefront edition key for wishlist / queue payloads.",
        "required": [
          "source",
          "product_id"
        ],
        "properties": {
          "source": {
            "type": "string",
            "description": "Content-source plugin id (`audible`, `libro`, …).",
            "example": "libro"
          },
          "product_id": {
            "type": "string",
            "description": "Storefront product id (ASIN, ISBN, UUID, …).",
            "example": "9780441478125"
          }
        }
      },
      "description": "Distinct storefront editions contributing to this wishlist item."
    },
    "purchase_hints": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Snapshotted purchase link/price for a wishlist title.",
        "required": [
          "source",
          "product_id"
        ],
        "properties": {
          "source": {
            "type": "string",
            "description": "Content-source plugin id (`audible`, `libro`, …).",
            "example": "libro"
          },
          "product_id": {
            "type": "string",
            "description": "Storefront product id (ASIN, ISBN, UUID, …).",
            "example": "9780441478125"
          },
          "title": {
            "type": [
              "string",
              "null"
            ],
            "description": "Display title of the work or edition.",
            "example": "The Left Hand of Darkness"
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront product or purchase URL when known.",
            "example": "https://libro.fm/audiobooks/9780441478125"
          },
          "price_cents": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Observed price in minor currency units, when known.",
            "example": 2499
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 4217 currency code for price fields.",
            "example": "USD"
          },
          "price_label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront-formatted price string for display.",
            "example": "$24.99"
          },
          "list_price_cents": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "List/MSRP price in minor units, when known.",
            "example": 2999
          },
          "list_price_label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront-formatted list price for display.",
            "example": "$29.99"
          },
          "member_price_cents": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Member/subscriber price in minor units, when known.",
            "example": 1499
          },
          "member_price_label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront-formatted member price for display.",
            "example": "$14.99"
          }
        }
      },
      "description": "Purchase URLs and prices observed per storefront."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp when the row was inserted.",
      "example": "2026-10-29T10:12:00Z"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp when the row was last modified.",
      "example": "2026-10-29T10:14:22Z"
    }
  }
}

Status 400: Only open wishlist items can be removed.

only open wishlist items can be removed

Schema:

A text/plain body: a string.

Status 401: No signed-in caller.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The request belongs to someone else. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 404: No such request.

wishlist item not found: 0b7e4c1d-2a3f-4e5d-9c8b-7a6f5e4d3c2b

Schema:

A text/plain body: a string.

Status 500: The request could not be read or written.

ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection

Schema:

A text/plain body: a string.

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

GET /api/request-queue

Reads the shared open-request queue from its stored ranking.

The discover_request_queue job ranks the queue against household taste when a taste event says it may have moved; this route joins that stored ranking with the open requests and the live wish counts, so it reads no books, listening history or embedder. When an entry has no stored ranking yet, or the ranking is older than a day, the route queues a pass and answers with what it has.

Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).

Credentials: operatorToken or operatorSession or portalSession or clerkToken

Responses

  • 200Open requests, ranked. Body: array of RankedQueueEntry (application/json)16 fields
    • work_keystringrequiredStable map key for this work (isbn:…, asin:…, or soft title+author).
    • work_idstringrequiredThe work every wish of this entry is for. Wishes for one work are one entry even when their work_keys differ, so a client matches its own wishes on this id first and on work_key otherwise.
    • titlestringrequiredDisplay title as shown on the storefront or library card.
    • authorsstring or nullComma-separated author names when the storefront provides them.
    • asinstring or nullAudible / Amazon ASIN when this edition is sold on Audible.
    • isbnstring or nullCanonical ISBN-13 (or ISBN-10 normalized) when published.
    • cover_urlstring or nullHTTPS URL for cover art when the catalog exposes one.
    • cover_pathstring or nullSame-origin path of this cover's processed images, set by the daemon when cover_url is an https URL. Append /128 (thumbnail), /360 (card) or /full, so a client can show covers without loading cover_url from another site.
    • wish_countinteger (int64)requiredNumber of distinct users who wishlisted this title.
    • wishersarray of QueueWisherDistinct people who have this title on an open wishlist.
    • sample_uuidsarray of stringrequiredSample Bookclerk user UUIDs who requested this title (privacy-capped).
    • first_requested_atstring (date-time)requiredUTC timestamp of the earliest wishlist request for this work.
    • last_requested_atstring (date-time)requiredUTC timestamp of the latest wishlist request for this work.
    • scorenumber (double)requiredFinal rank score (taste_score + wish_count * [WISH_COUNT_WEIGHT]).
    • taste_scorenumber (double)requiredLocal taste / embedding component before the wish-count boost.
    • reasonsarray of stringrequiredShort human-readable explanations for why this item was ranked here.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The queue could not be read. Body: string (text/plain)
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/request-queue' \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/request-queue' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/request-queue",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/request-queue", {
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/request-queue")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Open requests, ranked.

[
  {
    "work_key": "isbn:9780441478125",
    "work_id": "0b7e2c1d-5f3a-4e6b-9c8d-1a2b3c4d5e6f",
    "title": "The Left Hand of Darkness",
    "authors": "Ursula K. Le Guin",
    "asin": "B002V0QK4C",
    "isbn": "9780441478125",
    "cover_url": "https://images.example.com/covers/9780441478125.jpg",
    "cover_path": "/api/covers/aHR0cHM6Ly9pbWFnZXMuZXhhbXBsZS5jb20vYy5qcGc.q2fW1n4bJm0Rg9xV3kTzPA",
    "wish_count": 3,
    "wishers": [
      {
        "user_id": 7,
        "identity_id": 7,
        "display_name": "Dana Reader",
        "login_name": "dana",
        "operator": false,
        "has_avatar": true,
        "avatar_source": "upload",
        "gravatar_hash": "84d2a1a1d9ba6a4c2f4b9d0e7a7c6b5f3e2d1c0b9a8f7e6d5c4b3a2918f7e6d5",
        "picture_url": "https://accounts.example.com/u/dana/picture.png",
        "picture_path": "/api/images/aHR0cHM6Ly9hY2NvdW50cy5leGFtcGxlLmNvbS91L2RhbmEvcGljdHVyZS5wbmc.N14rqh66Bok9-eCqJKBNoQ"
      }
    ],
    "sample_uuids": [
      "0b7e2c1d-5f3a-4e6b-9c8d-1a2b3c4d5e6f"
    ],
    "first_requested_at": "2026-09-02T08:15:00Z",
    "last_requested_at": "2026-10-29T10:12:00Z",
    "score": 120.61,
    "taste_score": 0.61,
    "reasons": [
      "wishlisted by 3 people",
      "matches liked author (Ursula K. Le Guin)"
    ]
  }
]

Schema:

{
  "type": "array",
  "items": {
    "type": "object",
    "description": "Global wishlist queue entry ranked by overall/operator recommend taste +\nheavy wish-count weight (shared order; not per-viewer personalized).",
    "required": [
      "work_key",
      "work_id",
      "title",
      "wish_count",
      "sample_uuids",
      "first_requested_at",
      "last_requested_at",
      "score",
      "taste_score",
      "reasons"
    ],
    "properties": {
      "work_key": {
        "type": "string",
        "description": "Stable map key for this work (`isbn:…`, `asin:…`, or soft title+author).",
        "example": "isbn:9780441478125"
      },
      "work_id": {
        "type": "string",
        "description": "The work every wish of this entry is for. Wishes for one work are\none entry even when their `work_key`s differ, so a client matches\nits own wishes on this id first and on `work_key` otherwise.",
        "example": "0b7e2c1d-5f3a-4e6b-9c8d-1a2b3c4d5e6f"
      },
      "title": {
        "type": "string",
        "description": "Display title as shown on the storefront or library card.",
        "example": "The Left Hand of Darkness"
      },
      "authors": {
        "type": [
          "string",
          "null"
        ],
        "description": "Comma-separated author names when the storefront provides them.",
        "example": "Ursula K. Le Guin"
      },
      "asin": {
        "type": [
          "string",
          "null"
        ],
        "description": "Audible / Amazon ASIN when this edition is sold on Audible.",
        "example": "B002V0QK4C"
      },
      "isbn": {
        "type": [
          "string",
          "null"
        ],
        "description": "Canonical ISBN-13 (or ISBN-10 normalized) when published.",
        "example": "9780441478125"
      },
      "cover_url": {
        "type": [
          "string",
          "null"
        ],
        "description": "HTTPS URL for cover art when the catalog exposes one.",
        "example": "https://images.example.com/covers/9780441478125.jpg"
      },
      "cover_path": {
        "type": [
          "string",
          "null"
        ],
        "description": "Same-origin path of this cover's processed images, set by the daemon\nwhen `cover_url` is an `https` URL. Append `/128`\n(thumbnail), `/360` (card) or `/full`, so a client can show covers\nwithout loading `cover_url` from another site.",
        "example": "/api/covers/aHR0cHM6Ly9pbWFnZXMuZXhhbXBsZS5jb20vYy5qcGc.q2fW1n4bJm0Rg9xV3kTzPA"
      },
      "wish_count": {
        "type": "integer",
        "format": "int64",
        "description": "Number of distinct users who wishlisted this title.",
        "example": 3
      },
      "wishers": {
        "type": "array",
        "items": {
          "type": "object",
          "description": "Compact wisher shown on the global queue (avatar + label).",
          "properties": {
            "user_id": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int64",
              "description": "First-party `users.id` when the portal identity is linked.",
              "example": 7
            },
            "identity_id": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int64",
              "description": "Portal identity that created the wish (dedupe for unlinked identities).",
              "example": 7
            },
            "display_name": {
              "type": [
                "string",
                "null"
              ],
              "description": "Display name, identity label, or `\"Operator\"`.",
              "example": "Dana Reader"
            },
            "login_name": {
              "type": [
                "string",
                "null"
              ],
              "description": "Local login name when the first-party user has one.",
              "example": "dana"
            },
            "operator": {
              "type": "boolean",
              "description": "True when the wish came from the operator token (no portal user).",
              "example": false
            },
            "has_avatar": {
              "type": "boolean",
              "description": "True when an uploaded avatar file exists (filled by the daemon).",
              "example": true
            },
            "avatar_source": {
              "type": [
                "string",
                "null"
              ],
              "description": "Explicit picture choice when the user has set one.",
              "example": "upload"
            },
            "gravatar_hash": {
              "type": [
                "string",
                "null"
              ],
              "description": "SHA-256 hex of the contact email for Gravatar.",
              "example": "84d2a1a1d9ba6a4c2f4b9d0e7a7c6b5f3e2d1c0b9a8f7e6d5c4b3a2918f7e6d5"
            },
            "picture_url": {
              "type": [
                "string",
                "null"
              ],
              "description": "HTTPS picture from the wishing identity, when any.",
              "example": "https://accounts.example.com/u/dana/picture.png"
            },
            "picture_path": {
              "type": [
                "string",
                "null"
              ],
              "description": "Same-origin 128 px copy of `picture_url` for the web app to show\n(filled by the daemon; never stored).",
              "example": "/api/images/aHR0cHM6Ly9hY2NvdW50cy5leGFtcGxlLmNvbS91L2RhbmEvcGljdHVyZS5wbmc.N14rqh66Bok9-eCqJKBNoQ"
            }
          }
        },
        "description": "Distinct people who have this title on an open wishlist."
      },
      "sample_uuids": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Sample Bookclerk user UUIDs who requested this title (privacy-capped).",
        "example": [
          "0b7e2c1d-5f3a-4e6b-9c8d-1a2b3c4d5e6f"
        ]
      },
      "first_requested_at": {
        "type": "string",
        "format": "date-time",
        "description": "UTC timestamp of the earliest wishlist request for this work.",
        "example": "2026-09-02T08:15:00Z"
      },
      "last_requested_at": {
        "type": "string",
        "format": "date-time",
        "description": "UTC timestamp of the latest wishlist request for this work.",
        "example": "2026-10-29T10:12:00Z"
      },
      "score": {
        "type": "number",
        "format": "double",
        "description": "Final rank score (`taste_score + wish_count * `[`WISH_COUNT_WEIGHT`]).",
        "example": 120.61
      },
      "taste_score": {
        "type": "number",
        "format": "double",
        "description": "Local taste / embedding component before the wish-count boost.",
        "example": 0.61
      },
      "reasons": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Short human-readable explanations for why this item was ranked here.",
        "example": [
          "wishlisted by 3 people",
          "matches liked author (Ursula K. Le Guin)"
        ]
      }
    }
  }
}

Status 401: The caller is not signed in, or the credential is wrong.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable.

{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 500: The queue could not be read.

ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection

Schema:

A text/plain body: a string.

Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/branch-requests

Asks a branch for a book it listed.

The work must currently be available through a branch this library trusts (its available_through in Discover and search). The branch takes the request automatically for anything it listed; the book arrives with the branch's catalog sync and is then held through that branch. Asking again while a request for the same work and branch waits returns that request.

Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).

Credentials: operatorToken or operatorSession or portalSession or clerkToken

Request body

application/json: BranchRequestBody

  • work_idstringrequiredThis library's work id, as Discover and search name it.
  • node_idstring or nullThe branch to ask, from the work's available_through; absent or null asks the first branch that lists the work.

Responses

  • 200The request was queued for the branch. Body: BranchRequestQueued (application/json)3 fields
    • job_idstringrequiredThe request's job (kind branch_request), as /api/jobs lists it.
    • node_idstringrequiredThe branch the request went to.
    • already_queuedbooleanrequiredtrue when a request for this work to this branch was already waiting or being taken; job_id is that request.
  • 400The work or node id is malformed. As text/plain, when the body is not syntactically valid JSON. Body: string (text/plain)
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's member controls turn requesting books off. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: string (text/plain); ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 404No branch this library trusts (or not the named one) currently lists the work. Body: string (text/plain)
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be read or written. Body: string (text/plain)
  • 503The job queue is full; try again later. When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out. Body: string (text/plain); ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/branch-requests' \
    -X POST \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{"work_id": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/branch-requests' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{"work_id": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b"}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/branch-requests",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={"work_id": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/branch-requests", {
  method: "POST",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"work_id": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/branch-requests")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({"work_id": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The request was queued for the branch.

{
  "job_id": "branch_request-5e0f2a1c-7b3d-4c6e-8f9a-1b2c3d4e5f6a",
  "node_id": "9b1c7d2e-4f3a-4b6c-8d1e-2f3a4b5c6d7e",
  "already_queued": false
}

Schema:

{
  "type": "object",
  "description": "`POST /api/branch-requests` answer.",
  "required": [
    "job_id",
    "node_id",
    "already_queued"
  ],
  "properties": {
    "job_id": {
      "type": "string",
      "description": "The request's job (kind `branch_request`), as `/api/jobs` lists it.",
      "example": "branch_request-5e0f2a1c-7b3d-4c6e-8f9a-1b2c3d4e5f6a"
    },
    "node_id": {
      "type": "string",
      "description": "The branch the request went to.",
      "example": "9b1c7d2e-4f3a-4b6c-8d1e-2f3a4b5c6d7e"
    },
    "already_queued": {
      "type": "boolean",
      "description": "`true` when a request for this work to this branch was already\nwaiting or being taken; `job_id` is that request.",
      "example": false
    }
  }
}

Status 400: The work or node id is malformed. As text/plain, when the body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller's member controls turn requesting books off. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 404: No branch this library trusts (or not the named one) currently lists the work.

work 0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b on any branch not found

Schema:

A text/plain body: a string.

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `work_id` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The library could not be read or written.

ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection

Schema:

A text/plain body: a string.

Status 503: The job queue is full; try again later. When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

POST /api/download-requests

Asks this library to download a book it holds but has no copy of.

The work must be on one of the library's store accounts, with no edition of it downloaded yet. The library downloads the first such edition (in edition id order) on the account that holds it, counted against that account's pace. Asking again while that download waits or runs returns it. A library card (a clerk) may ask, as may any signed-in patron whose member controls allow requesting books.

Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).

Credentials: operatorToken or operatorSession or portalSession or clerkToken

Request body

application/json: DownloadRequestBody

  • work_idstringrequiredThis library's work id, as its window books and search name it.

Responses

  • 200The download was queued. Body: DownloadRequestQueued (application/json)3 fields
    • job_idstringrequiredThe acquire job, as /api/jobs lists it.
    • edition_idstringrequiredThe edition being downloaded.
    • already_queuedbooleanrequiredtrue when a download of that edition was already waiting or running; job_id is that download.
  • 400The work id is malformed. As text/plain, when the body is not syntactically valid JSON. Body: string (text/plain)
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's member controls turn requesting books off. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: string (text/plain); ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 404No store account of this library holds the work. Body: string (text/plain)
  • 409The library already has a copy, or no node can run the download. Body: string (text/plain)
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be read or written. Body: string (text/plain)
  • 503The job queue is full or admission is paused; try again later. When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out. Body: string (text/plain); ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/download-requests' \
    -X POST \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{"work_id": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/download-requests' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{"work_id": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b"}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/download-requests",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={"work_id": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/download-requests", {
  method: "POST",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"work_id": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/download-requests")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({"work_id": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The download was queued.

{
  "job_id": "acquire-3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
  "edition_id": "5c2e8f1a-9b3d-4e7f-a1c2-d3e4f5a6b7c8",
  "already_queued": false
}

Schema:

{
  "type": "object",
  "description": "`POST /api/download-requests` answer.",
  "required": [
    "job_id",
    "edition_id",
    "already_queued"
  ],
  "properties": {
    "job_id": {
      "type": "string",
      "description": "The acquire job, as `/api/jobs` lists it.",
      "example": "acquire-3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
    },
    "edition_id": {
      "type": "string",
      "description": "The edition being downloaded.",
      "example": "5c2e8f1a-9b3d-4e7f-a1c2-d3e4f5a6b7c8"
    },
    "already_queued": {
      "type": "boolean",
      "description": "`true` when a download of that edition was already waiting or\nrunning; `job_id` is that download.",
      "example": false
    }
  }
}

Status 400: The work id is malformed. As text/plain, when the body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: The caller is not signed in.

{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}

Schema:

{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}

Status 403: The caller's member controls turn requesting books off. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.

{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 404: No store account of this library holds the work.

work 0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b on this library's store accounts not found

Schema:

A text/plain body: a string.

Status 409: The library already has a copy, or no node can run the download.

this library already has a copy of work 0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b

Schema:

A text/plain body: a string.

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `work_id` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The library could not be read or written.

ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection

Schema:

A text/plain body: a string.

Status 503: The job queue is full or admission is paused; try again later. When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out.

{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}

Schema:

{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}

Status 504: The request ran past the API's time budget.

request timed out

Schema:

A text/plain body: a string.

Generated from crates/bookclerkd/openapi.json at main · View as Markdown