# Reverb Product

## Overview

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

## Description

Reverb Product API: fetch full listing data from a Reverb URL or listing id. Returns pricing, specs, images, description and shop info 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/product' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Aria Pro II XX Deluxe (96933467) on reverb.com

```json
{
  "url": "https://reverb.com/fr/item/96933467-aria-pro-ii-xx-deluxe-1983-matsumoku-noir",
  "make": "Aria",
  "shop": {
    "name": "etienne Vintage Shop",
    "slug": "etiennes-shop-59",
    "shop_id": "4508650",
    "location": "HARFLEUR, France",
    "feedback_percentage": 100
  },
  "year": 1983,
  "model": "XX Deluxe",
  "price": 580,
  "state": "live",
  "title": "Aria Pro II XX Deluxe 1983(Matsumoku) - Noir",
  "finish": "Noir",
  "images": [
    "https://rvb-img.reverb.com/i/s--4w_SZaeX--/quality=medium-low,height=800,width=800,fit=contain/ef1fd9bd-45f5-43fe-a27a-2cfb776430aa.jpeg"
  ],
  "category": "Guitares électriques",
  "currency": "EUR",
  "condition": "Correct",
  "image_url": "https://rvb-img.reverb.com/i/s--4w_SZaeX--/quality=medium-low,height=800,width=800,fit=contain/ef1fd9bd-45f5-43fe-a27a-2cfb776430aa.jpeg",
  "inventory": 0,
  "listing_id": "96933467",
  "description": "<p><b><strong>Aria Pro II XX Deluxe 1983(Matsumoku) - Noir</strong></b></p>",
  "listing_type": "MAKE_AN_OFFER",
  "price_display": "€580",
  "offers_enabled": true
}
```

## Documentation

## Overview
The **Reverb Product API** returns full listing page data from Reverb. Pass a **listing URL** or **numeric id** and receive structured JSON with pricing, specs, images, description, shop info, and availability flags.

Piloterr uses **browser rendering** and parses the Apollo Client cache embedded in rendered HTML (`<meta content="Listing:id:…">`).

Use [Reverb Search](https://www.piloterr.com/library/reverb-search) to discover listings, then [Reverb Product](https://www.piloterr.com/library/reverb-product) for the full record.

## Quickstart
```
GET https://api.piloterr.com/v2/reverb/product?query=96933467
GET https://api.piloterr.com/v2/reverb/product?query=https://reverb.com/fr/item/96933467-aria-pro-ii-xx-deluxe-1983-matsumoku-noir
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Listing URL or numeric id |
| `return_page_source` | boolean | no | Raw HTML as `{"result": "..."}` (default: `false`) |

## Input formats
| Format | Example |
|---|---|
| Listing id | `96933467` |
| Full URL | `https://reverb.com/fr/item/96933467-aria-pro-ii-xx-deluxe-1983-matsumoku-noir` |

The `bk` tracking parameter is stripped automatically.

## Response fields
| Field | Type | Description |
|---|---|---|
| `listing_id` | string | Reverb listing id |
| `title` | string | Listing title |
| `url` | string | Canonical listing URL (no `bk`) |
| `make` | string \| null | Brand |
| `model` | string \| null | Model |
| `year` | integer \| null | Year (from specs or title regex) |
| `finish` | string \| null | Finish / color |
| `price` | number | Buyer price (`pricing.buyerPrice`) |
| `price_display` | string \| null | Formatted price |
| `old_price` | number \| null | Strikethrough price if on sale |
| `currency` | string \| null | ISO currency |
| `condition` | string \| null | Item condition |
| `state` | string \| null | Listing state |
| `image_url` | string \| null | Main image |
| `images` | string[] \| null | Full gallery |
| `category` | string \| null | Primary category |
| `description` | string \| null | Seller HTML description |
| `inventory` | integer \| null | Remaining stock |
| `listing_type` | string \| null | `MAKE_AN_OFFER`, `BUY_IT_NOW`, … |
| `offers_enabled` | boolean \| null | Negotiation enabled |
| `shop.shop_id` | string | Shop id |
| `shop.name` | string | Shop name |
| `shop.slug` | string | Shop slug |
| `shop.location` | string | Seller location |
| `shop.feedback_percentage` | integer | Feedback score (0–100) |

## Year extraction
Reverb rarely exposes `year` at the top level. Piloterr resolves it from:
1. Apollo `listing.year`
2. Product spec with type `YEAR`
3. Title regex `(19xx|20xx)`

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

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | Listing not found or unparsable page |
| `500` | Rendering or parsing error |

## Notes
- Buyer price comes from `pricing.buyerPrice`, not the legacy top-level `price` field in Apollo.
- Costs **2 credits** per call (browser rendering).

## Main use cases
- **Listing enrichment**: description, gallery, shop metadata
- **Vintage gear intel**: year, make, model, condition
- **Offer monitoring**: `listing_type`, `offers_enabled`, price deltas