> ## Documentation Index
> Fetch the complete documentation index at: https://dev.phygitals.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get marketplace filters

> Returns facet values for building marketplace listing filters.

Returns the allowed metadata facet values for the Phygitals marketplace catalog. Use this to populate filter UI before calling [`GET /api/marketplace/marketplace-listings`](/public-api/marketplace/listings).

<Note>
  **No authentication required.** This is a public read endpoint. Responses are cached server-side for five minutes.
</Note>

## Example request

```http theme={"dark"}
GET /api/marketplace/filters
```

## Response

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "filters": {
      "metadata": {
        "Type": [{ "value": "Sports" }, { "value": "Pokemon" }],
        "Rarity": [{ "value": "Common" }, { "value": "Rare" }],
        "Set": [{ "value": "2024 Topps Chrome" }],
        "Grader": [{ "value": "PSA" }, { "value": "BGS" }],
        "Grade": [{ "value": "10" }, { "value": "9" }],
        "Set Release Date": [{ "value": "2024" }],
        "Language": [{ "value": "English" }]
      }
    }
  }
  ```
</ResponseExample>

## Fields

<ResponseField name="filters.metadata" type="object">
  Map of trait name → array of `{ value: string }` options. Only a fixed whitelist of traits is returned: `Type`, `Rarity`, `Set`, `Grader`, `Grade`, `Set Release Date`, and `Language`.
</ResponseField>

## Using filters with listings

Pass selected values into the `metadataConditions` query parameter on [`GET /api/marketplace/marketplace-listings`](/public-api/marketplace/listings):

```http theme={"dark"}
GET /api/marketplace/marketplace-listings?metadataConditions={"Grader":["PSA"],"Grade":["10"]}&listedStatus=listed&page=0&itemsPerPage=24
```

Trait keys in `metadataConditions` should match the facet names from this endpoint (for example `Grader`, not `grader`).

## Error responses

| Status | Body                                   | Cause                     |
| ------ | -------------------------------------- | ------------------------- |
| `500`  | `{ "error": "Internal server error" }` | Unexpected server failure |