---
title: "HTTP API"
description: "The internal HTTP API Bookhoarder's own frontend calls — authentication, conventions, and every endpoint."
---

> 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.

# HTTP API

This is the same HTTP API Bookhoarder's own web UI calls — there's no
separate public API surface. It's useful for scripting against a
self-hosted instance (bulk uploads, automating shelves), but it's
**internal and unversioned**: no API keys, no stability guarantee across
releases, and every route lives under the app's own origin (`http://localhost:3000`
by default).

## Authentication

There's no login form or token endpoint — identity comes from which
**profile** is active in the browser, tracked by the `bookhoard_profile`
cookie.

 **`/api/profiles/active`** sets that cookie: pass a
profile `id`, and its `password` if the profile has one set (see
[Profiles & Access](/features/profiles)). Every other endpoint reads the
active profile from the cookie already on the request — script against
this API with a cookie jar, the same way a browser session would.

Three permission levels apply, checked server-side on every request that
needs them (not just hidden in the UI):

| Level | Applies to |
| --- | --- |
| Anyone with a valid session | Reading books, shelves, settings; updating your own reading state |
| The profile itself, or an admin | Editing a profile's name, color, e-reader email, or password |
| Admin only | Creating/deleting profiles, deleting books, changing roles, changing server-wide settings (SMTP, trending, metadata) |

## Conventions

- All request and response bodies are JSON, except book upload
  (`multipart/form-data`) and file downloads (raw bytes)
- A failed request returns a JSON body shaped `{ "error": "..." }` with a
  4xx or 5xx status — there's no separate error-code field to switch on
- IDs are opaque strings — book IDs are slugs derived from title, profile
  and shelf IDs are UUIDs

## Endpoints by resource

| Resource | Page |
| --- | --- |
| Profiles — list, create, edit, switch active profile | [Profiles](/api/profiles) |
| Books — upload, list, edit, delete, send to e-reader, metadata lookup | [Books](/api/books) |
| Shelves — list, create, edit, delete, add/remove books | [Shelves](/api/shelves) |
| Settings — SMTP, trending, metadata lookup limit | [Settings](/api/settings) |
| Health, trending, cover/description lookups, file downloads, OPDS catalog | [Other endpoints](/api/other-endpoints) |

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