# Invaluable — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and browse fine art auction listings from Invaluable.com, discovering items by artist, auction house, or upcoming lots. Get detailed information about artworks, artists, and auction house catalogs to track pieces and stay informed about upcoming sales.

**Category:** Marketplaces | **Website:** [invaluable.com/](https://invaluable.com/) | **Docs:** [parse.bot/marketplace/f3b5f1ce-8067-4329-bf74-c58dc727dddb/invaluable-com-api](https://parse.bot/marketplace/f3b5f1ce-8067-4329-bf74-c58dc727dddb/invaluable-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-invaluable-com-api-f3b5f1ce/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_artist_detail

Fetch the full profile for a single artist by artistRef. Returns display name, genres, and lot counts (total, upcoming, past). The artistRef comes from list_artists results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `artist_ref` | string | Yes | The artist reference ID (from list_artists results[*].artistRef). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-invaluable-com-api-f3b5f1ce/get_artist_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"artist_ref":"<string>"}'
```

### get_auction_detail

Get all lots for a specific auction catalog by catalogRef. Searches both upcoming and archived indices and returns whichever has results. CatalogRefs come from search_items or get_upcoming_lots_by_artist results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `catalog_ref` | string | Yes | The catalog reference ID (from search_items results[*].catalogRef). |
| `limit` | integer | No | Results per page. |
| `page` | integer | No | Page number (0-based). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-invaluable-com-api-f3b5f1ce/get_auction_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"catalog_ref":"<string>","limit":"<integer>","page":"<integer>"}'
```

### get_auction_house_detail

Fetch the full profile for an auction house by houseRef. Returns name, description, physical address, rating, review count, logo URL, and year joined. The houseRef comes from list_auction_houses results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `house_ref` | string | Yes | The auction house reference ID (from list_auction_houses results[*].houseRef). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-invaluable-com-api-f3b5f1ce/get_auction_house_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"house_ref":"<string>"}'
```

### get_item_detail

Fetch full details and live bidding state for a single auction lot by its lotRef. Returns basic metadata (title, description, image) plus real-time fields (currentBidAmount, bidCount, isClosed, viewCount, saveCount). The lotRef comes from search_items or get_auction_detail results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lot_ref` | string | Yes | The lot reference ID (from search_items results[*].lotRef or get_auction_detail results[*].lotRef). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-invaluable-com-api-f3b5f1ce/get_item_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lot_ref":"<string>"}'
```

### get_upcoming_lots_by_artist

Get upcoming auction lots attributed to a specific artist. Returns only lots from upcoming auctions, not past/archived ones. The artistRef comes from list_artists results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `artist_ref` | string | Yes | The artist reference ID (from list_artists results[*].artistRef). |
| `limit` | integer | No | Results per page. |
| `page` | integer | No | Page number (0-based). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-invaluable-com-api-f3b5f1ce/get_upcoming_lots_by_artist \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"artist_ref":"<string>","limit":"<integer>","page":"<integer>"}'
```

### list_artists

Search artists in the database by keyword. Returns matching artist profiles with lot counts and genre tags. For most queries all results fit on page 0.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (0-based). |
| `query` | string | No | Search keyword matched against artist names and aliases. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-invaluable-com-api-f3b5f1ce/list_artists \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```

### list_auction_houses

Search or list auction houses in the database by keyword. Returns house profiles with reference IDs and country.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (0-based). |
| `query` | string | No | Search keyword matched against house names. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-invaluable-com-api-f3b5f1ce/list_auction_houses \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```

### search_items

Full-text search across auction lots. Returns upcoming lots by default; set past=true for archived/sold lots. Each lot carries bid state, category hierarchy, and auction-house metadata. Paginated via page (0-based); server caps at 5000 pages. Optionally filter by currency code, supercategory name, results-posted status, or non-zero price result.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Filter results by supercategory name (e.g. Fine Art, Jewelry, Asian Art & Antiques). Matches the supercategoryName field on lots. When omitted, all supercategories are returned. |
| `currency` | string | No | Filter results to a specific currency code (e.g. USD, EUR, AUD, GBP). Matches the currencyCode field on lots. When omitted, all currencies are returned. |
| `limit` | integer | No | Results per page (max varies by server). |
| `page` | integer | No | Page number (0-based). |
| `past` | boolean | No | When true, searches past/archived lots instead of upcoming ones. |
| `price_result` | boolean | No | When true, returns only lots with a non-zero price result value. When false (default), no priceResult filter is applied. |
| `query` | string | No | Search keyword matched against lot title, description, and category names. |
| `results_posted` | boolean | No | When true, returns only lots where auction results have been posted. When false (default), no resultsPosted filter is applied. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-invaluable-com-api-f3b5f1ce/search_items \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","currency":"<string>","limit":"<integer>","page":"<integer>","past":"<boolean>","price_result":"<boolean>","query":"<string>","results_posted":"<boolean>"}'
```