---
title: "Full-text faceted search"
method: POST
path: "/search"
tags: ["search"]
---

# Full-text faceted search

`POST /search`

This is the main marketplace search endpoint.

Use it for:
- global search bars
- category and filter pages
- any browse/results screen where users need discoverability

Behavior:
- Accepts free-text query, facet filters, sorting, and paging input.
- Returns matching items plus facet aggregations so the UI can render filter chips and counts.

Good to know:
- Results are cached briefly (~30s) for identical request bodies.
- Different JSON bodies generate different cache keys.

## Request body

- SearchQuery — A search query includes a free text query property, refinements in the form of facets, pagination controls and optional sorting.
  - `query` string — One or more free text search terms
  - `filters` object[]
  - `facets` object — Facets to refine the search results. Values are case-sensitive unless noted otherwise.
    - `Game` string[] — Game name to match, e.g. Pokemon or Magic
    - `Product Type` string[] — Type of product, for example "card" or "product"
    - `Rarity` string[] — Card rarity values
    - `Series` string[] — Series names
    - `Set` string[] — Set names
    - `Illustrator` string[] — Illustrator names as stored on item images
    - `Condition` string[] — Listing condition codes, e.g. MT, NM
    - `Grading` string[] — Whether the card is "Graded" or "Ungraded"
    - `Price` string[] — Price buckets expressed in pounds sterling (inclusive of lower bounds)
    - `Quantity` string[] — Quantity buckets for available stock
    - `Valid` string[] — Listing validity status for seller views
    - `Hidden` string[] — Listing visibility status for seller views
    - `Availability` string[] — Filter listings or items to only those that are "In Stock"
    - `Category` string[] — Item categories (metadata)
  - `from` number, nullable — Offset for pagination
  - `size` number — Number of results to return
  - `sorting` object — Sort results by field and order
    - `field` 'name' | 'number' | 'indexed' | 'price', required
    - `order` 'asc' | 'desc', required

## Response `200`

Search items and available facets

- SearchItemsResult
  - `total` number, required
  - `hits` union[], required
    - union
      - object
        - `urn` string, required
        - `type` 'card', required
        - `game` 'Pokemon', required
        - `title` string, required
        - `name` string, required
        - `rarity` string, required
        - `number` string, nullable
        - `description` string
        - `set` object, required
          - `name` string, required
          - `size` number
          - `urn` string, required
          - `counts` object, required
            - `printed` number
            - `total` number
          - `symbol` object
            - `url` string, required
          - `released` string
          - `references` string[], required
        - `series` object, required
          - `name` string, required
          - `urn` string, required
        - `images` object[], required
          - `urn` string, required
          - `illustrator` string
          - `orientation` 'portrait' | 'landscape', required
          - `url` string, uri, required
        - `price` integer
        - `available` integer — Total available for this listing
        - `quantity` integer — Total quantity available
        - `min` object
          - `price` integer, nullable, required — Price of the cheapest listing in pence
        - `max` object
          - `price` integer, nullable, required — Price of the most expensive listing in pence
      - object
        - `urn` string, required
        - `type` 'product', required
        - `game` 'Pokemon', required
        - `title` string, required
        - `name` string, required
        - `classification` 'CARD', required
        - `count` number, required
        - `description` string
        - `images` object[], required
          - `urn` string, required
          - `illustrator` string
          - `orientation` 'portrait' | 'landscape', required
          - `url` string, uri, required
        - `series` object, required
          - `name` string, required
          - `urn` string, required
        - `set` object, required
          - `name` string, required
          - `size` number
          - `urn` string, required
          - `counts` object, required
            - `printed` number
            - `total` number
          - `symbol` object
            - `url` string, required
          - `released` string
          - `references` string[], required
        - `price` integer
        - `available` integer — Total available for this listing
        - `quantity` integer — Total quantity available
        - `min` object
          - `price` integer, nullable, required — Price of the cheapest listing in pence
        - `max` object
          - `price` integer, nullable, required — Price of the most expensive listing in pence
  - `facets` object, required

---

[API](https://skmtc.net/managem/apis/managem-api.md) · [All operations](https://skmtc.net/managem/apis/managem-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/managem/managem-api/versions/e8d78a3a2e8b/schema)