# Grailed — 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.

> Access Grailed's fashion resale marketplace: search listings by designer, category, size, and condition; retrieve listing details, seller profiles and reviews; and browse categories, popular designers, and curated collections.

**Category:** Marketplaces | **Website:** [grailed.com/](https://grailed.com/) | **Docs:** [parse.bot/marketplace/759cac5c-2a9c-481b-830d-8f0fb798d406/grailed-com-api](https://parse.bot/marketplace/759cac5c-2a9c-481b-830d-8f0fb798d406/grailed-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-grailed-com-api-759cac5c/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_categories

Get the full category hierarchy for menswear and womenswear departments, including subcategory paths and associated Algolia filter configurations. No input parameters required.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-grailed-com-api-759cac5c/get_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_homepage_collections

Get curated homepage collections (capsules) with their descriptions and detail page info. Returns the current set of editorial collections featured on Grailed.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-grailed-com-api-759cac5c/get_homepage_collections \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_listing_detail

Fetch the full detail page for a single listing by its numeric ID. Returns all fields including full description, photos, seller profile, shipping rates, traits, measurements, and designer info. One network round-trip per listing.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `listing_id` | string | Yes | The numeric listing ID. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-grailed-com-api-759cac5c/get_listing_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"<string>"}'
```

### get_seller_listings

Get all active listings for a specific seller, paginated. Returns the same listing shape as search_listings. Uses the Algolia index filtered by user ID.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (0-indexed). |
| `user_id` | string | Yes | The seller's numeric user ID. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-grailed-com-api-759cac5c/get_seller_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","user_id":"<string>"}'
```

### get_seller_profile

Fetch a seller's public profile including their ratings and top designers they sell. Combines data from the seller_ratings and top_designers API endpoints. The user_id is the seller's numeric user ID.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `user_id` | string | Yes | The seller's numeric user ID. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-grailed-com-api-759cac5c/get_seller_profile \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"<string>"}'
```

### get_seller_reviews

Get seller feedback and reviews including ratings, tags, notes, and associated listing info. Returns the full seller_ratings array for the given user.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `user_id` | string | Yes | The seller's numeric user ID. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-grailed-com-api-759cac5c/get_seller_reviews \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"<string>"}'
```

### get_similar_listings

Get similar listings for a given item based on its designer and category. Returns a list of similar listings with metadata about the source algorithm.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `listing_id` | string | Yes | The listing ID to find similar items for. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-grailed-com-api-759cac5c/get_similar_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"<string>"}'
```

### list_popular_designers

Get the list of popular designers sorted by number of listings. Returns up to 100 designers from the Algolia Designer index with their listing counts and departments.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-grailed-com-api-759cac5c/list_popular_designers \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_listings

Full-text search over Grailed listings with optional facet filters for department, category, designer, size, and condition. Results are paginated via a page counter. Each hit includes id, title, price, designers, condition, photos, and seller info. Sort changes the underlying index.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category path filter (e.g. footwear.lowtop_sneakers, tops.sweatshirts_hoodies). |
| `condition` | string | No | Condition filter. |
| `department` | string | No | Department filter. |
| `designer` | string | No | Designer name filter, matched exactly against the designer name field. |
| `limit` | integer | No | Results per page (max 100). |
| `page` | integer | No | Page number (0-indexed). |
| `query` | string | No | Search keyword to match against listing title and attributes. |
| `size` | string | No | Size filter (e.g. m, l, 10.5, 34). |
| `sort` | string | No | Sort order for results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-grailed-com-api-759cac5c/search_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","condition":"<string>","department":"<string>","designer":"<string>","limit":"<integer>","page":"<integer>","query":"<string>","size":"<string>","sort":"<string>"}'
```