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

POST /books

Create a new book

cURL

curl --request POST \
  --url https://bookhub-mock.onrender.com/books \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "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"
}
'

200

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"
  }
}

Authorizations

Authorization · string · header · required

JWT obtained from the authentication endpoint

Headers

Idempotency-Key · string<uuid> · required

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.

Example:

"550e8400-e29b-41d4-a716-446655440000"

X-Request-ID · string

Request tracking identifier

X-Publisher-ID · string

Publisher identifier

Body

application/json

title · string · required

Book title

Maximum string length: 255

Example:

"The Great Adventure"

author · string · required

Primary author name

Maximum string length: 255

Example:

"Jane Smith"

description · string · required

Book description or synopsis

Maximum string length: 5000

Example:

"An epic tale of courage and discovery"

publisher · string · required

Publisher name

Maximum string length: 255

Example:

"Adventure Books Inc"

publishedDate · string<date> · required

Original publication date

Example:

"2024-01-15"

isbn · string · required

ISBN-10 or ISBN-13 identifier. Must be unique across the publisher's catalog. Duplicate ISBNs return 409 Conflict.

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]$

Example:

"978-0-1234-5678-9"

price · number<decimal> · required

Base price in USD

Required range: x >= 0.01

Example:

24.99

genres · string[] · required

Book genres or categories

Required array length: 1 - 5 elements

Example:

["Fiction", "Mystery", "Thriller"]

bookFormat · enum<string> · required

Physical or digital format

Available options: Paperback, Hardcover, eBook

coverImages · string<uri>[]

URLs to book cover images

Required array length: 1 - 5 elements

Response

200

application/json

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.

status · enum<string>

Available options: success

message · string

Example:

"Book already created"

data · object

Show child attributes