Reference
Marketplace API
Updated 1 Oct 2026
For agents
Load this page when: you need to find marketplace books or add or remove one over HTTP
- Browse with GET /api/marketplace/browse. It needs no key and sits outside /api/v1.
- Add a book only when the user wants it. It uses one library slot.
- Pass the listing id, not the book id, to subscribe and unsubscribe.
The marketplace is the public shelf of books other people published. Adding a book is free and takes no payment. See Marketplace.
Browse listings
GET https://heytrove.ai/api/marketplace/browse
Lists public listings. This endpoint is not under /api/v1 and needs no key. Anonymous responses may be cached for a short time.
Parameters
| Name | In | Type | Required | Constraints | Meaning |
|---|---|---|---|---|---|
search | query | string | no | none | Search query. |
tag | query | string | no | tag slug | Show one tag only. |
category | query | string | no | a listing category | Show one category. An unknown value returns 400 with the allowed list. |
sort | query | string | no | newest, popular or az | Sort order. Default newest. |
page | query | integer | no | 1 to 10,000 | Page number. Default 1. |
limit | query | integer | no | 1 to 100 | Page size. Default 20. |
since | query | string | no | ISO-8601 date | Only listings submitted after this time. |
proOnly | query | boolean | no | true | Only Pro listings. |
Request
curl "https://heytrove.ai/api/marketplace/browse?search=postgres&sort=popular&limit=5"Response
{
"listings": [
{
"id": "cmlst123",
"slug": "use-the-index-luke",
"category": null,
"proOnly": false,
"tags": [{ "name": "Postgres", "slug": "postgres" }],
"subscriberCount": 120,
"createdAt": "2026-09-01T09:00:00.000Z",
"item": {
"title": "Use The Index, Luke",
"description": null,
"author": "Markus Winand",
"sourceType": "pdf",
"pageCount": 42
},
"seller": { "name": "Markus", "imageUrl": null }
}
],
"total": 1,
"page": 1,
"totalPages": 1
}Errors
| Status | Message | Fix |
|---|---|---|
| 400 | Invalid `since`: expected an ISO-8601 date such as 2026-09-01 or 2026-09-01T00:00:00Z | Fix the date. |
| 400 | Invalid `category` | Use a value from the allowed list in the body. |
CLI equivalent: trove marketplace browse.
Add a listing to your library
POST https://heytrove.ai/api/v1/marketplace/subscribe
Adds a listed book to your library. It uses one library slot. A Pro-only listing can be added on any plan, but it returns a short preview until you upgrade.
Parameters
| Name | In | Type | Required | Constraints | Meaning |
|---|---|---|---|---|---|
listingId | body | string | yes | 1 to 64 characters | Listing id from browse. |
Request
curl https://heytrove.ai/api/v1/marketplace/subscribe \
-H "Authorization: Bearer trove_your_key" \
-H "Content-Type: application/json" \
-d '{"listingId":"cmlst123"}'Response
{ "success": true, "itemId": "cmabc123" }Errors
| Status | Message | Code | Fix |
|---|---|---|---|
| 400 | listingId is required | none | Send listingId. |
| 400 | Cannot subscribe to your own listing | none | You already own it. |
| 404 | Listing not found | none | Check the id. |
| 409 | Already subscribed to this listing | CONFLICT | Nothing to do. The body has the itemId. |
| 403 | Your library is full. Upgrade to add more items. | PLAN_LIMIT_EXCEEDED | See Errors. |
| 429 | Too many library writes in a short window — wait a minute and retry. | RATE_LIMITED | Wait for Retry-After. |
CLI equivalent: trove marketplace subscribe.
Remove a listing from your library
DELETE https://heytrove.ai/api/v1/marketplace/subscribe
Removes a marketplace book from your library and frees one slot. You can add it again while it is listed.
Parameters
| Name | In | Type | Required | Constraints | Meaning |
|---|---|---|---|---|---|
listingId | body | string | yes | 1 to 64 characters | Listing to remove. |
Request
curl -X DELETE https://heytrove.ai/api/v1/marketplace/subscribe \
-H "Authorization: Bearer trove_your_key" \
-H "Content-Type: application/json" \
-d '{"listingId":"cmlst123"}'Response
{ "success": true }Errors
| Status | Message | Code | Fix |
|---|---|---|---|
| 400 | listingId is required | none | Send listingId. |
| 404 | No subscription found for this listing | NOT_FOUND | You have not added this listing. |
CLI equivalent: trove marketplace unsubscribe.