---
title: "REST API"
description: "Use when you call Trove over HTTP and need the base URL, authentication, error shapes, rate limits and the list of every endpoint with a link to its page."
url: https://docs.heytrove.ai/reference/api
updated: 2026-10-01
---

# REST API

> Load this page when: you need to call the Trove REST API, handle one of its errors, or find the endpoint for a task

## For agents

- Send Authorization Bearer with a trove_ API key to {base}/api/v1 and branch on the code field of an error.
- Stop and tell the user on READ_LIMIT_EXCEEDED, ITEM_LOCKED and PLAN_LIMIT_EXCEEDED. Do not retry.
- Retry RATE_LIMITED after the Retry-After seconds.

The REST API is what the CLI calls. Everything the CLI does, you can do over HTTP.

## Base URL

All endpoints live under one base path.

```bash
https://heytrove.ai/api/v1
```

## Authentication

Send your API key as a Bearer token. Create a key in [API keys](https://docs.heytrove.ai/reference/api-keys.md).

```bash
curl https://heytrove.ai/api/v1/auth/whoami \
  -H "Authorization: Bearer trove_your_key"
```

New keys start with `trove_`. Older `ck_` keys keep working. OAuth connector tokens, which start with `ck_oauth_`, are bound to the MCP server. On REST routes they fail with `Token resource binding does not match request`, so use an API key here.

## Error shape

Every error is JSON with a human `error` message and, for most errors, a machine `code`. Branch on `code`, not on the message.

```json
{ "error": "Invalid shelf parameter", "code": "SHELF_PARAM_INVALID" }
```

## Errors

| Status | Message | Code | Fix |
| --- | --- | --- | --- |
| 401 | `Missing Authorization header` | none | Send the header. |
| 401 | ``Invalid Authorization header format. Expected: Bearer <token>`` | none | Use `Authorization: Bearer trove_your_key`. |
| 401 | `Invalid API key format` | none | Check that you pasted the whole key. |
| 401 | `Invalid or revoked API key` | none | Create a key in Settings, or run `trove auth login`. |
| 401 | `Token resource binding does not match request` | none | You sent an OAuth token. Use an API key. |
| 403 | `Your library is full. Upgrade to add more items.` | `PLAN_LIMIT_EXCEEDED` | Remove a book or upgrade. The body adds `tier`, `itemCount`, `itemLimit` and `upgradeUrl`. |
| 403 | `This book is locked on the Personal plan. The Personal plan keeps {n} book(s) usable and the rest are kept but locked. Upgrade at {host}/billing or choose this book as one of your usable books in the library at {host}/library/usable.` | `ITEM_LOCKED` | Stop. Tell the user. Do not retry. |
| 429 | `Trove: your agent has used all {limit} reads for {month}. Reads reset on {date}. Pro has unlimited reads: {host}/billing` | `READ_LIMIT_EXCEEDED` | Stop. Tell the user. Do not retry. The body adds `tier`, `used`, `limit`, `upgradeUrl` and `resetsAt`, and the response has `Retry-After`. |
| 429 | `Too many content writes in a short window — wait a minute and retry.` | `RATE_LIMITED` | Wait for `Retry-After`, then retry. |
| 429 | `Too many library writes in a short window — wait a minute and retry.` | `RATE_LIMITED` | Wait for `Retry-After`, then retry. |
| 503 | A short retry message | `TRANSIENT_CONFLICT` | Retry after `retryAfterSeconds`. |

## Rate limits

Limits are per user, per minute, in a 60 second window. A limited call returns 429 with `Retry-After` in seconds.

| Bucket | Calls per minute | Applies to |
| --- | --- | --- |
| Library writes | 120 | Starting an upload and adding a marketplace book |
| Content writes | 60 | Creating a markdown book, replacing, appending, editing pages and restoring versions |
| Upload check | 60 | `POST /upload/check` |
| Team changes | 20 | Invites, departments and sharing |
| Settings writes | 20 | `PATCH /user/config/agents` and `PUT /user/agents` |
| Value reports | 100 | `GET /reports/value` and `GET /reports/value/sessions` |
| Reports | 10 | `POST /report` |

## Endpoints

| Method | Path | What it does | Page |
| --- | --- | --- | --- |
| GET | `/auth/whoami` | Show your account and usage | [Auth API](https://docs.heytrove.ai/reference/api/auth.md) |
| GET | `/items` | List your books | [Items API](https://docs.heytrove.ai/reference/api/items.md) |
| DELETE | `/items` | Delete books | [Items API](https://docs.heytrove.ai/reference/api/items.md) |
| POST | `/items/markdown` | Create a markdown book | [Items API](https://docs.heytrove.ai/reference/api/items.md) |
| PATCH | `/items/enrich` | Set metadata | [Items API](https://docs.heytrove.ai/reference/api/items.md) |
| POST | `/items/flag` | Flag for enrichment | [Items API](https://docs.heytrove.ai/reference/api/items.md) |
| POST | `/items/{itemId}/reprocess` | Rebuild from the original file | [Items API](https://docs.heytrove.ai/reference/api/items.md) |
| GET | `/items/{itemId}/content` | Get full content | [Reading API](https://docs.heytrove.ai/reference/api/items-read.md) |
| POST | `/items/batch` | Read pages | [Reading API](https://docs.heytrove.ai/reference/api/items-read.md) |
| POST | `/items/batch/toc` | Get tables of contents | [Reading API](https://docs.heytrove.ai/reference/api/items-read.md) |
| PUT | `/items/{itemId}/content` | Replace a whole book | [Writing API](https://docs.heytrove.ai/reference/api/items-write.md) |
| PUT | `/items/{itemId}/pages/{pageNum}` | Replace one page | [Writing API](https://docs.heytrove.ai/reference/api/items-write.md) |
| POST | `/items/{itemId}/pages` | Append or prepend | [Writing API](https://docs.heytrove.ai/reference/api/items-write.md) |
| GET | `/items/{itemId}/versions` | List versions | [Writing API](https://docs.heytrove.ai/reference/api/items-write.md) |
| POST | `/items/{itemId}/versions` | Restore a version | [Writing API](https://docs.heytrove.ai/reference/api/items-write.md) |
| POST | `/items/{itemId}/gaps` | Report a missing topic | [Gaps API](https://docs.heytrove.ai/reference/api/gaps.md) |
| GET | `/items/{itemId}/gaps` | List requests for a book | [Gaps API](https://docs.heytrove.ai/reference/api/gaps.md) |
| POST | `/items/{itemId}/gaps/fulfill` | Mark requests covered | [Gaps API](https://docs.heytrove.ai/reference/api/gaps.md) |
| POST | `/items/{itemId}/gaps/dismiss` | Decline requests | [Gaps API](https://docs.heytrove.ai/reference/api/gaps.md) |
| POST | `/items/{itemId}/gaps/restore` | Reopen declined requests | [Gaps API](https://docs.heytrove.ai/reference/api/gaps.md) |
| GET | `/author/gaps` | Summarize requests across your books | [Gaps API](https://docs.heytrove.ai/reference/api/gaps.md) |
| POST | `/librarian/gaps` | Report a topic no book covers | [Gaps API](https://docs.heytrove.ai/reference/api/gaps.md) |
| GET, POST | `/shelves` | List and create shelves | [Shelves API](https://docs.heytrove.ai/reference/api/shelves.md) |
| GET, PATCH, DELETE | `/shelves/{id}` | Get, change and delete a shelf | [Shelves API](https://docs.heytrove.ai/reference/api/shelves.md) |
| POST, DELETE | `/shelves/{id}/items` | Add and remove books | [Shelves API](https://docs.heytrove.ai/reference/api/shelves.md) |
| GET, POST | `/manuscripts` | List and create manuscripts | [Manuscripts API](https://docs.heytrove.ai/reference/api/manuscripts.md) |
| PUT, DELETE | `/manuscripts/{id}` | Update and archive | [Manuscripts API](https://docs.heytrove.ai/reference/api/manuscripts.md) |
| POST, DELETE | `/marketplace/subscribe` | Add and remove a listing | [Marketplace API](https://docs.heytrove.ai/reference/api/marketplace.md) |
| POST | `/upload` | Get an upload URL | [Upload API](https://docs.heytrove.ai/reference/api/upload.md) |
| POST | `/upload/check` | Check for duplicates | [Upload API](https://docs.heytrove.ai/reference/api/upload.md) |
| POST | `/upload/confirm` | Start the import | [Upload API](https://docs.heytrove.ai/reference/api/upload.md) |
| GET | `/reports/value` | Get your value report | [Reports API](https://docs.heytrove.ai/reference/api/reports.md) |
| GET | `/reports/value/sessions` | Page through sessions | [Reports API](https://docs.heytrove.ai/reference/api/reports.md) |
| POST | `/access/session` | Start a research session | [Reports API](https://docs.heytrove.ai/reference/api/reports.md) |
| POST | `/access/session/complete` | Complete a session | [Reports API](https://docs.heytrove.ai/reference/api/reports.md) |
| GET | `/teams` | List your teams | [Teams API](https://docs.heytrove.ai/reference/api/teams.md) |
| GET, POST, DELETE | `/teams/{teamId}/members` | List, invite and remove members | [Teams API](https://docs.heytrove.ai/reference/api/teams.md) |
| GET, POST | `/teams/{teamId}/departments` | List and create departments | [Teams API](https://docs.heytrove.ai/reference/api/teams.md) |
| PATCH, DELETE | `/teams/{teamId}/departments/{dept}` | Rename and delete | [Teams API](https://docs.heytrove.ai/reference/api/teams.md) |
| GET, POST, DELETE | `/teams/{teamId}/departments/{dept}/members` | Manage department members | [Teams API](https://docs.heytrove.ai/reference/api/teams.md) |
| GET, POST, PATCH, DELETE | `/teams/{teamId}/items` | Manage shared books | [Teams API](https://docs.heytrove.ai/reference/api/teams.md) |
| GET | `/teams/{teamId}/access-report` | Show the access matrix | [Teams API](https://docs.heytrove.ai/reference/api/teams.md) |
| GET, PATCH | `/user/config` | Read and change settings | [Account API](https://docs.heytrove.ai/reference/api/account.md) |
| PATCH | `/user/config/agents` | Turn an agent on or off | [Account API](https://docs.heytrove.ai/reference/api/account.md) |
| GET, PUT | `/user/agents` | Read and report machines | [Account API](https://docs.heytrove.ai/reference/api/account.md) |
| GET | `/user/notifications` | List notifications | [Account API](https://docs.heytrove.ai/reference/api/account.md) |
| POST | `/user/notifications/mark-read` | Mark notifications read | [Account API](https://docs.heytrove.ai/reference/api/account.md) |
| POST | `/report` | Send a report | [Account API](https://docs.heytrove.ai/reference/api/account.md) |

The marketplace listing endpoint, `GET /api/marketplace/browse`, sits outside `/api/v1` and needs no key. See [Marketplace API](https://docs.heytrove.ai/reference/api/marketplace.md).