> ## Documentation Index
> Fetch the complete documentation index at: https://galejames.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Data models

> Explore schema definitions for BaseBook, BookWithAnalytics, Pagination, and Error response objects in the BookHub Publisher API.

## Endpoint coverage for the `hitCount` field

The `hitCount` field records how many times buyers have retrieved a book's details. For its full definition (type, constraints, read-only status), see [Data models](/reference/reference-data-models.md#bookwithanalytics-schema-v2-only). The following table shows which endpoints include `hitCount` in their responses.

| Endpoint | `hitCount` field in response? |
| - | - |
| `GET /v2/books/{bookId}` | Yes |
| `GET /v2/books` | No |
| `POST /v2/books` | No |
| `DELETE /v2/books/{bookId}` | No |
| `PATCH /v2/books/{bookId}/finalize` | No |

## BaseBook schema

This is the standard `book` object returned by the create, get, and list endpoints.

```json theme={null}
{
  "bookId": "string (read-only)",
  "title": "string (max 255 chars)",
  "author": "string (max 255 chars)",
  "description": "string (max 5000 chars)",
  "language": "string (BCP 47 language tag, e.g., en-US)",
  "publisher": "string (max 255 chars)",
  "publishedDate": "date (YYYY-MM-DD)",
  "isbn": "string (unique ISBN-10 or ISBN-13)",
  "price": "number (minimum 0.01)",
  "status": "enum (PENDING, ACTIVE, INACTIVE)",
  "coverImages": ["array of URLs (1-5 items)"],
  "genres": ["array of strings (1-5 items)"],
  "bookFormat": "enum (Paperback, Hardcover, eBook)",
  "createdDate": "datetime (ISO 8601, read-only)",
  "updatedDate": "datetime (ISO 8601, read-only)"
}
```

### BaseBook example

A populated `BaseBook` object:

```json theme={null}
{
  "bookId": "123e4567-e89b-41d4-a716-426614174000",
  "title": "The Great Adventure",
  "author": "Jane Smith",
  "description": "An epic tale of courage and discovery",
  "language": "en-US",
  "publisher": "Adventure Books Inc",
  "publishedDate": "2024-03-15",
  "isbn": "978-0-1234-5678-9",
  "price": 24.99,
  "status": "ACTIVE",
  "coverImages": [
    "https://covers.bookhub.com/great-adventure-front.jpg"
  ],
  "genres": [
    "Fiction",
    "Adventure"
  ],
  "bookFormat": "Hardcover",
  "createdDate": "2024-12-25T10:30:00Z",
  "updatedDate": "2024-12-26T15:45:00Z"
}
```

## BookWithAnalytics schema (v2 only)

This schema extends BaseBook with the following additional field:

```json theme={null}
  "hitCount": "integer (minimum 0, read-only)"
```

### BookWithAnalytics example

For a populated BookWithAnalytics example, see the [Get a specific book](/api-reference/endpoint/getBook.mdx) `200` response, which returns a BookWithAnalytics object, including the `hitCount` field.

## Pagination schema

The pagination object used in list endpoints (e.g., `GET /v2/books`) to provide pagination details.

```json theme={null}
{
  "currentPage": "integer (minimum 1)",
  "totalPages": "integer (minimum 0)",
  "totalItems": "integer (minimum 0)",
  "itemsPerPage": "integer (1-100)"
}
```

## Error response schema

The error response object returned when an API request fails.

> [!NOTE]
>
> The `validation_context` and `provided_value` fields use snake\_case rather than camelCase. This is a known inconsistency in the v2 API that will be addressed in a future version. When parsing error responses, match these two fields by their exact snake\_case keys.

```json theme={null}
{
  "status": "error",
  "message": "string",
  "errors": [
    {
      "field": "string",
      "error": "string",
      "description": "string",
      "validation_context": {
        "rule": "string",
        "constraint": "object",
        "provided_value": "string"
      }
    }
  ]
}
```

## Next steps

Explore related topics:

### Conceptual guides

* [Using the `hitCount` field for analytics](/conceptual-guides/conceptual-guides-hitcount-analytics) — Learn how `hitCount` tracks customer interest in specific titles.
* [Pagination](/conceptual-guides/conceptual-guides-pagination.mdx) — Understand how pagination works in the BookHub Publisher API.

### How-to guides

* [Rank books by hitCount to find top performers](/how-to-guides/how-to-guides-use-hitcount-to-track-book-performance.md) — Use the `hitCount` field to rank books by buyer interest and flag your top performers.

### Reference

* [Release notes](/reference/reference-release-notes.md) — Explore all changes in BookHub Publisher API v2.
* [API endpoints](/reference/reference-api-endpoints.md) — Provides additional information about the BookHub Publisher API v2 endpoints, including business rules.
* [Code examples](/reference/reference-code-examples.md) — Copy code samples for book creation, sorting by creation date, handling removed title sorting, and tracking performance with `hitCount`.

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.