> ## 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. # Create a new book > Creates a new book with `PENDING` status. The book will not be visible to customers until it is finalized using the finalize endpoint. ## Workflow 1. Create book with `PENDING` status 2. Review and verify book details 3. Finalize book to make it `ACTIVE` ## OpenAPI ````yaml POST /books openapi: 3.0.3 info: title: BookHub Publisher API description: > BookHub's Publisher API enables programmatic management of book inventory on the BookHub marketplace. This API uses path-based versioning (v2) and requires authentication via JWTs. > The interactive "Try it" playground is backed by a mock server: requests return documented example responses and don't persist. Enter any value in the Authorization field to try a request; for write endpoints, fill the required fields shown. version: 2.0.1 contact: name: BookHub API Support email: api-support@bookhub.com url: https://docs.bookhub.com servers: - url: https://bookhub-mock.onrender.com description: >- Interactive mock — returns live example responses (no real data or persistence) - url: https://api.bookhub.com/api/v2 description: Production server - Version 2 - url: https://api.bookhub.com/api/v1 description: Production server - Version 1 (legacy) security: - BearerAuth: [] tags: - name: Books description: Operations for managing book catalog paths: /books: description: Endpoints for creating and managing books in the BookHub catalog. post: tags: - Books summary: Create a new book description: > Creates a new book with `PENDING` status. The book will not be visible to customers until it is finalized using the finalize endpoint. ## Workflow 1. Create book with `PENDING` status 2. Review and verify book details 3. Finalize book to make it `ACTIVE` operationId: createBook parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/RequestId' - $ref: '#/components/parameters/PublisherId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BaseBook' example: 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 coverImages: - https://covers.bookhub.com/great-adventure-front.jpg - https://covers.bookhub.com/great-adventure-back.jpg genres: - Fiction - Adventure bookFormat: Hardcover responses: '200': description: > Idempotent replay. A request with a previously used `Idempotency-Key` (within its 24-hour validity window) returns the existing book instead of creating a duplicate. content: application/json: schema: type: object properties: status: type: string enum: - success message: type: string example: Book already created data: $ref: '#/components/schemas/BaseBook' example: status: success message: Book already created data: 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: PENDING coverImages: - https://covers.bookhub.com/great-adventure-front.jpg genres: - Fiction - Adventure bookFormat: Hardcover createdDate: '2024-12-25T10:30:00Z' updatedDate: '2024-12-25T10:30:00Z' '201': description: >- Book created successfully. Returned when the Idempotency-Key has not been used before; replaying a used key returns 200 with the existing book. headers: Location: schema: type: string description: URL of the newly created book example: /v2/books/123e4567-e89b-41d4-a716-426614174000 content: application/json: schema: type: object properties: status: type: string enum: - success message: type: string example: Book created successfully data: $ref: '#/components/schemas/BaseBook' example: status: success message: Book created successfully data: 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: PENDING coverImages: - https://covers.bookhub.com/great-adventure-front.jpg genres: - Fiction - Adventure bookFormat: Hardcover createdDate: '2024-12-25T10:30:00Z' updatedDate: '2024-12-25T10:30:00Z' '400': description: >- Bad request (e.g., validation failure such as an invalid ISBN format or a malformed Idempotency-Key) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidIsbn: summary: ISBN format is invalid value: status: error message: Validation failed errors: - field: isbn error: INVALID_FORMAT description: ISBN must match the pattern for ISBN-10 or ISBN-13 validation_context: rule: pattern_match constraint: pattern: ^[0-9]{13}$ provided_value: invalid-isbn invalidIdempotencyKey: summary: Idempotency-Key is not a valid UUID value: status: error message: Validation failed errors: - field: Idempotency-Key error: INVALID_FORMAT description: Idempotency-Key must be a valid UUID validation_context: rule: format constraint: format: uuid provided_value: not-a-uuid '401': $ref: '#/components/responses/UnauthorizedError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitError' components: parameters: IdempotencyKey: name: Idempotency-Key in: header description: | Unique key (UUID) for request deduplication. Reusing a key within its 24-hour validity window returns the original response instead of creating a duplicate resource. Keys match on the key value only, not the request body. required: true schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 RequestId: name: X-Request-ID in: header description: Request tracking identifier required: false schema: type: string PublisherId: name: X-Publisher-ID in: header description: Publisher identifier required: false schema: type: string schemas: BaseBook: type: object required: - title - author - description - language - publisher - publishedDate - isbn - price - genres - bookFormat properties: bookId: type: string description: Unique identifier for the book readOnly: true title: type: string maxLength: 255 description: Book title example: The Great Adventure author: type: string maxLength: 255 description: Primary author name example: Jane Smith description: type: string maxLength: 5000 description: Book description or synopsis example: An epic tale of courage and discovery publisher: type: string maxLength: 255 description: Publisher name example: Adventure Books Inc publishedDate: type: string format: date description: Original publication date example: '2024-01-15' isbn: type: string pattern: >- ^(?:ISBN(?:-1[03])?:? )?(?=[0-9X]{10}$|(?=(?:[0-9]+[- ]){3})[- 0-9X]{13}$|97[89][0-9]{10}$|(?=(?:[0-9]+[- ]){4})[- 0-9]{17}$)(?:97[89][- ]?)?[0-9]{1,5}[- ]?[0-9]+[- ]?[0-9]+[- ]?[0-9X]$ description: >- ISBN-10 or ISBN-13 identifier. Must be unique across the publisher's catalog. Duplicate ISBNs return `409 Conflict`. example: 978-0-1234-5678-9 price: type: number format: decimal minimum: 0.01 description: Base price in USD example: 24.99 status: type: string enum: - PENDING - ACTIVE - INACTIVE default: PENDING description: Current publication status. Always set to PENDING on creation. readOnly: true coverImages: type: array items: type: string format: uri minItems: 1 maxItems: 5 description: URLs to book cover images genres: type: array items: type: string minItems: 1 maxItems: 5 description: Book genres or categories example: - Fiction - Mystery - Thriller bookFormat: type: string enum: - Paperback - Hardcover - eBook description: Physical or digital format createdDate: type: string format: date-time description: When the book was created in the system readOnly: true example: '2024-12-25T10:30:00Z' updatedDate: type: string format: date-time description: When the book was last updated readOnly: true example: '2024-12-26T15:45:00Z' ErrorResponse: type: object description: > Error response returned when an API request fails. Note: `validation_context` and `provided_value` use snake_case rather than camelCase — this is a known inconsistency that will be addressed in a future version. required: - status - message properties: status: type: string enum: - error description: Status indicator message: type: string description: Human-readable error message example: Validation failed errors: type: array description: Detailed error information for each failed field items: type: object properties: field: type: string description: Field that caused the error example: isbn error: type: string description: Error type example: INVALID_FORMAT description: type: string description: Detailed error explanation example: ISBN must match the pattern for ISBN-10 or ISBN-13 validation_context: type: object description: Additional context about the validation failure properties: rule: type: string example: pattern_match constraint: type: object example: pattern: ^[0-9]{13}$ provided_value: type: string example: invalid-isbn responses: UnauthorizedError: description: Unauthorized access content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: error message: Authentication failed errors: - field: Authorization error: INVALID_TOKEN description: >- The JWT is missing, malformed, or expired. Obtain a new token and retry. ConflictError: description: A book with this ISBN already exists content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: error message: A book with this ISBN already exists errors: - field: isbn error: DUPLICATE_VALUE description: >- ISBN 978-0-1234-5678-9 is already registered to bookId 123e4567-e89b-41d4-a716-426614174000 RateLimitError: description: | Rate limit exceeded. Retry after the window resets — see the `X-RateLimit-Reset` header for the Unix timestamp when the current window closes, and `X-RateLimit-Remaining` for requests left in it. headers: X-RateLimit-Limit: schema: type: integer description: Maximum requests allowed per minute X-RateLimit-Remaining: schema: type: integer description: Requests remaining in current window X-RateLimit-Reset: schema: type: integer format: unix-timestamp description: Unix timestamp when rate limit resets content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: error message: >- Rate limit exceeded. Retry after the window resets (see X-RateLimit-Reset header). securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT obtained from the authentication endpoint ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.