bookhoard/docs/api/collections/create_shelf_mapping.md

Create Shelf Mapping

Map a collection to a device shelf for syncing.

Endpoint: POST /api/devices/{deviceId}/collections Auth: Required Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
deviceId	string (UUID)	Yes	Device UUID

Request Body

Field	Type	Required	Description
collection_id	string (UUID)	Yes	Collection UUID to map
device_shelf_name	string	Yes	Name of the shelf on the device
sync_direction	string	No	Sync direction (default: "bidirectional")

Sync Directions

Direction	Description
bidirectional	Sync both ways between Bookhoard and device
book_to_hoard	Bookhoard → Device only
device_to_hoard	Device → Bookhoard only
none	No sync (mapping only for reference)

Example Request

{
  "collection_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_shelf_name": "Sci-Fi",
  "sync_direction": "bidirectional"
}

Response (201 Created)

{
  "id": "990e8400-e29b-41d4-a716-446655440000",
  "collection_id": "550e8400-e29b-41d4-a716-446655440000",
  "collection_name": "Science Fiction",
  "device_shelf_name": "Sci-Fi",
  "sync_direction": "bidirectional",
  "created_at": "2026-02-01T10:00:00Z"
}

Use Case

Collections can be synced to device-specific shelves (Kobo, KOReader). This allows automatic organization of books on your e-reader based on your Bookhoard collections.

Error Responses

Code	Description
400	Invalid request (validation failed)
401	Authentication required
404	Device or collection not found
409	Mapping already exists
500	Internal server error

Try It Out