---
title: "Shelves"
description: "List, create, edit, delete shelves, and add or remove books from them."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.bookhoarder.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Shelves

Shelves are scoped to the active profile — see [Shelves](/features/shelves).
Every endpoint here operates on the active profile's own shelves; there's
no way to read or edit another profile's shelves through this API.

## `GET /api/shelves`

Lists the active profile's shelves, seeding the five default shelves on
first call if none exist yet.

**Response:** `{ "shelves": Shelf[] }`

## `POST /api/shelves`

Creates a shelf.

**Request body**

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `name` | string | Yes | Trimmed; rejected if empty |
| `color` | string | No | Assigned automatically if omitted |

**Response:** `201` with `{ "shelf": Shelf }`

## `PATCH /api/shelves/:id`

Renames or recolors a shelf. Both fields optional.

**Request body:** `{ "name"?: string, "color"?: string }`

**Response:** `{ "shelf": Shelf }`, or `404` if the shelf doesn't exist.

## `DELETE /api/shelves/:id`

Deletes a shelf. Books on it aren't affected — they just stop being on
that shelf.

**Response:** `{ "ok": true }`

## `POST /api/shelves/:id/books`

Adds a book to the shelf. Idempotent — adding a book already on the
shelf is a no-op.

**Request body:** `{ "bookId": string }`

**Response:** `{ "shelves": Shelf[] }` — every shelf for the active
profile, reflecting the change.

## `DELETE /api/shelves/:id/books/:bookId`

Removes a book from the shelf.

**Response:** `{ "shelves": Shelf[] }`

Source: https://docs.bookhoarder.dev/api/shelves//index.md