Reference
REST API
Updated 1 Oct 2026
For agents
Load this page when: you need to call the Trove REST API, handle one of its errors, or find the endpoint for a task
- 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/v1Authentication
Send your API key as a Bearer token. Create a key in API keys.
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 |
| GET | /items | List your books | Items API |
| DELETE | /items | Delete books | Items API |
| POST | /items/markdown | Create a markdown book | Items API |
| PATCH | /items/enrich | Set metadata | Items API |
| POST | /items/flag | Flag for enrichment | Items API |
| POST | /items/{itemId}/reprocess | Rebuild from the original file | Items API |
| GET | /items/{itemId}/content | Get full content | Reading API |
| POST | /items/batch | Read pages | Reading API |
| POST | /items/batch/toc | Get tables of contents | Reading API |
| PUT | /items/{itemId}/content | Replace a whole book | Writing API |
| PUT | /items/{itemId}/pages/{pageNum} | Replace one page | Writing API |
| POST | /items/{itemId}/pages | Append or prepend | Writing API |
| GET | /items/{itemId}/versions | List versions | Writing API |
| POST | /items/{itemId}/versions | Restore a version | Writing API |
| POST | /items/{itemId}/gaps | Report a missing topic | Gaps API |
| GET | /items/{itemId}/gaps | List requests for a book | Gaps API |
| POST | /items/{itemId}/gaps/fulfill | Mark requests covered | Gaps API |
| POST | /items/{itemId}/gaps/dismiss | Decline requests | Gaps API |
| POST | /items/{itemId}/gaps/restore | Reopen declined requests | Gaps API |
| GET | /author/gaps | Summarize requests across your books | Gaps API |
| POST | /librarian/gaps | Report a topic no book covers | Gaps API |
| GET, POST | /shelves | List and create shelves | Shelves API |
| GET, PATCH, DELETE | /shelves/{id} | Get, change and delete a shelf | Shelves API |
| POST, DELETE | /shelves/{id}/items | Add and remove books | Shelves API |
| GET, POST | /manuscripts | List and create manuscripts | Manuscripts API |
| PUT, DELETE | /manuscripts/{id} | Update and archive | Manuscripts API |
| POST, DELETE | /marketplace/subscribe | Add and remove a listing | Marketplace API |
| POST | /upload | Get an upload URL | Upload API |
| POST | /upload/check | Check for duplicates | Upload API |
| POST | /upload/confirm | Start the import | Upload API |
| GET | /reports/value | Get your value report | Reports API |
| GET | /reports/value/sessions | Page through sessions | Reports API |
| POST | /access/session | Start a research session | Reports API |
| POST | /access/session/complete | Complete a session | Reports API |
| GET | /teams | List your teams | Teams API |
| GET, POST, DELETE | /teams/{teamId}/members | List, invite and remove members | Teams API |
| GET, POST | /teams/{teamId}/departments | List and create departments | Teams API |
| PATCH, DELETE | /teams/{teamId}/departments/{dept} | Rename and delete | Teams API |
| GET, POST, DELETE | /teams/{teamId}/departments/{dept}/members | Manage department members | Teams API |
| GET, POST, PATCH, DELETE | /teams/{teamId}/items | Manage shared books | Teams API |
| GET | /teams/{teamId}/access-report | Show the access matrix | Teams API |
| GET, PATCH | /user/config | Read and change settings | Account API |
| PATCH | /user/config/agents | Turn an agent on or off | Account API |
| GET, PUT | /user/agents | Read and report machines | Account API |
| GET | /user/notifications | List notifications | Account API |
| POST | /user/notifications/mark-read | Mark notifications read | Account API |
| POST | /report | Send a report | Account API |
The marketplace listing endpoint, GET /api/marketplace/browse, sits outside /api/v1 and needs no key. See Marketplace API.