---
title: "Marketplace API"
description: "Use when you browse public marketplace listings without a key, or add a listed book to your library and remove it again over HTTP."
url: https://docs.heytrove.ai/reference/api/marketplace
updated: 2026-10-01
---

# Marketplace API

> Load this page when: you need to find marketplace books or add or remove one over HTTP

## For agents

- 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](https://docs.heytrove.ai/concepts/marketplace.md).

## 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**

```bash
curl "https://heytrove.ai/api/marketplace/browse?search=postgres&sort=popular&limit=5"
```

**Response**

```json
{
  "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](https://docs.heytrove.ai/reference/cli/marketplace.md#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**

```bash
curl https://heytrove.ai/api/v1/marketplace/subscribe \
  -H "Authorization: Bearer trove_your_key" \
  -H "Content-Type: application/json" \
  -d '{"listingId":"cmlst123"}'
```

**Response**

```json
{ "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](https://docs.heytrove.ai/reference/api.md#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](https://docs.heytrove.ai/reference/cli/marketplace.md#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**

```bash
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**

```json
{ "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](https://docs.heytrove.ai/reference/cli/marketplace.md#trove-marketplace-unsubscribe).