# Reverb Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/reverb/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/reverb-search |

## Description

Reverb Search API: search music gear listings by keyword, query string or marketplace URL on Reverb. Returns prices, thumbnails and pagination via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/reverb/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search 'guitar' on reverb.com (page 1)

```json
{
  "results": [
    {
      "url": "https://reverb.com/fr/item/92086927-fanta-studio-guitar-2023-bege-heavy-duty-engine-metal",
      "price": 847.45,
      "title": "Fanta Studio Guitar 2023 - Bege Heavy Duty Engine Metal",
      "image_url": "https://rvb-img.reverb.com/i/s--rmpkcW0d--/quality=medium-low,height=400,width=400,fit=cover,gravity=bottom/eashywrraatgvpugyof8.jpg",
      "listing_id": "92086927"
    },
    {
      "url": "https://reverb.com/fr/item/96872671-1988-gibson-sg-custom-antique-ivory-nitro-vintage-usa-guitar-w-original-chainsaw-case",
      "price": 4150,
      "title": "1988 Gibson SG Custom Antique Ivory Nitro Vintage USA Guitar w/ Original Chainsaw Case",
      "image_url": "https://rvb-img.reverb.com/i/s--uy4zcAiS--/quality=medium-low,height=400,width=400,fit=cover,gravity=bottom/7b197daf-4157-4dbc-87eb-20de0c382571.jpg",
      "listing_id": "96872671"
    }
  ],
  "pagination": {
    "next": "https://reverb.com/marketplace?query=guitar&product_type=electric-guitars&page=2",
    "page": 1,
    "per_page": 56,
    "total_pages": null,
    "total_results": null
  }
}
```

## Documentation

## Overview
The **Reverb Search API** returns music gear listings from Reverb. Pass a **keyword**, a **query string**, or a **full marketplace URL** and receive structured JSON with prices, thumbnails, and pagination.

Reverb is a React/Apollo SPA. Piloterr uses **browser rendering** and waits for Apollo listing data in `<meta content="Listing:id:…">` tags before parsing.

Use each result `url` or `listing_id` with [Reverb Product](https://www.piloterr.com/library/reverb-product) for full listing details (description, gallery, shop, year).

## Quickstart
```
GET https://api.piloterr.com/v2/reverb/search?query=guitar
GET https://api.piloterr.com/v2/reverb/search?query=query=guitar&product_type=electric-guitars
GET https://api.piloterr.com/v2/reverb/search?query=https://reverb.com/marketplace?query=guitar&product_type=electric-guitars
GET https://api.piloterr.com/v2/reverb/search?query=guitar&page=2
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword, `query=…&product_type=…`, or marketplace URL |
| `page` | integer | no | 1-based page override (default: from URL or `1`) |
| `return_page_source` | boolean | no | Raw HTML as `{"result": "..."}` (default: `false`) |

## Input formats
| Format | Example |
|---|---|
| Keyword | `guitar` |
| Query string | `query=guitar&product_type=electric-guitars` |
| Full URL | `https://reverb.com/marketplace?query=guitar&product_type=electric-guitars` |
| Shop search URL | `https://reverb.com/shop/…` |

## Response: each listing (`results[]`)
| Field | Type | Description |
|---|---|---|
| `listing_id` | string | Reverb listing id |
| `title` | string | Listing title |
| `url` | string | Listing URL (`bk` tracker stripped) |
| `price` | number | Buyer price |
| `image_url` | string | Card thumbnail |
| `make` | string \| null | Brand (when Apollo exposes it) |
| `model` | string \| null | Model |
| `year` | integer \| null | Year |
| `finish` | string \| null | Finish / color |
| `price_display` | string \| null | Formatted price |
| `currency` | string \| null | ISO currency |
| `condition` | string \| null | Item condition |
| `state` | string \| null | Listing state (`live`, `sold`, …) |
| `category` | string \| null | Primary category |
| `shop` | object \| null | Seller shop summary |

Search often returns the minimal set (`listing_id`, `title`, `url`, `price`, `image_url`). Use **Reverb Product** for full records.

## Response: pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page |
| `per_page` | integer | Results on this page (~24–56) |
| `total_results` | integer \| null | Often `null` |
| `total_pages` | integer \| null | Often `null` |
| `next` | string \| null | Next page URL |

## Reverb workflow
1. [Reverb Search](https://www.piloterr.com/library/reverb-search): discover listings (this endpoint)
2. [Reverb Product](https://www.piloterr.com/library/reverb-product): full listing JSON

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | Skeleton page or no parseable listings |
| `500` | Rendering or parsing error |

## Notes
- Listing URLs may include locale prefixes (`/fr/item/…`).
- The `bk` tracking query param is stripped from all returned URLs.
- Costs **2 credits** per call (browser rendering).

## Main use cases
- **Gear discovery**: harvest listing ids across categories and filters
- **Price monitoring**: track buyer prices on used instruments
- **Marketplace intel**: compare listings before fetching full PDP data