---
title: "Book list"
method: GET
path: "/v1/books"
tags: ["Book Queries"]
---

# Book list

`GET /v1/books`

## Request

- Base URL: `https://api.ocrolus.com`
- URL: `https://api.ocrolus.com/v1/books`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://auth.ocrolus.com/oauth/token`

This API retrieves a list of all <<glossary:Book>>s available to the current user. It returns the following two different response shapes depending on whether the `limit` parameter is supplied, select the schema and example that matches your use case:
  - **Unpaginated**: When `limit` is omitted, the response is a bare array of Book objects with no wrapper.
  - **Paginated**: When `limit` is supplied, the response is an object containing `_links`, `limit`, `total_book_count`, and `books`.

  ---

  > 📘 Note
    > - By default results are ordered by <<glossary:Book>> PK in descending order but you can alter how and what books are returned by providing different parameters with your request.
    > - Use the `name` query parameter to find a <<glossary:Book>> by an exact name. This will be faster than `search` which uses approximate string matching algorithm.

## Query parameters

- `book_class` 'COMPLETE' | 'INSTANT' | 'INSTANT_CLASSIFY_ONLY' | 'INSTANT_CLASSIFY_ISO_CAPTURE'
- `limit` integer
- `offset` integer
- `order` 'ASC' | 'DESC'
- `order_by` 'created' | 'name' | 'pk'
- `name` string
- `search` string
- `xid` string

## Response `200`

Success

- union
  - object
    - `status` number: A numerical code that indicates the status of the request.
    - `response` object[]: An array containing objects of <<glossary:Book>>s. Returned when `limit` is not supplied.
      - `pk` integer: Primary key of the <<glossary:Book>>.
      - `id` integer: ID of the <<glossary:Book>> (same as `pk`).
      - `name` string: Name of the <<glossary:Book>>.
      - `created` string: ISO timestamp when the <<glossary:Book>> was created.
      - `created_ts` string: ISO timestamp when the <<glossary:Book>> was created.
      - `owner_email` string: Email of the <<glossary:Book>> owner.
      - `is_public` boolean: Whether the <<glossary:Book>> is public.
      - `book_uuid` string: UUID of the <<glossary:Book>>.
      - `book_type` 'DEFAULT' | 'INSTANT_ML' | 'WIDGET': Type of the Book. Possible values: DEFAULT, INSTANT_ML, WIDGET.
      - `xid` string, nullable: External ID of the <<glossary:Book>>.
    - `message` string: A textual description that indicates details about this response's status.
  - object
    - `status` number: A numerical code that indicates the status of the request.
    - `response` object: Paginated response object returned when `limit` is supplied.
      - `_links` object: Pagination links. `self` (always present), `next` (if more results exist), `prev` (if offset > 0).
        - `self` string: URL of the current page of results.
        - `next` string: URL of the next page of results. Present only when more results exist beyond the current page.
        - `prev` string: URL of the previous page of results. Present only when offset is greater than 0.
      - `limit` integer: Number of Books per page.
      - `total_book_count` integer: Total number of matching Books.
      - `books` object[]: List of Books for the current page.
        - `pk` integer: Primary key of the <<glossary:Book>>.
        - `id` integer: ID of the <<glossary:Book>> (same as `pk`).
        - `name` string: Name of the <<glossary:Book>>.
        - `created` string: ISO timestamp when the <<glossary:Book>> was created.
        - `created_ts` string: ISO timestamp when the <<glossary:Book>> was created.
        - `owner_email` string: Email of the <<glossary:Book>> owner.
        - `is_public` boolean: Whether the <<glossary:Book>> is public.
        - `book_uuid` string: UUID of the <<glossary:Book>>.
        - `book_type` 'DEFAULT' | 'INSTANT_ML' | 'WIDGET': Type of the Book. Possible values: DEFAULT, INSTANT_ML, WIDGET.
        - `xid` string, nullable: External ID of the <<glossary:Book>>.
    - `message` string: A textual description that indicates details about this response's status.

## Other responses

- `400`: Client Errors
- `500`: Internal server error

---

[API](https://skmtc.dev/ocrolus/apis/book-queries.md) - [All operations](https://skmtc.dev/ocrolus/apis/book-queries/llms.txt) - [OpenAPI document](https://skmtc.dev/ocrolus/apis/book-queries/revisions/cbe5b52f5b26?raw)