Skip to main content

Schema API

The Schema API is part of EDITED's REST API (same host and access key as the Query API). It's a set of discovery endpoints: the REST way to turn a brand, retailer, category, or detail name into the slug or ID you put in a filter, and to fetch the field definitions for a schema version. It is the REST counterpart to MCP's search_* tools.

Resolving filter values

Most filters take slugs or IDs, not free text — see Filters → Resolving values. The Schema API is how you resolve them over REST; over MCP, the search_* tools do the same job. The slugs and IDs are the same whichever surface you use, so you can resolve on one and filter on the other.

Authentication & base URL​

Every endpoint is a GET under https://apis.edited.com/schema/v1/, carrying your EDITED access key in the x-api-key header — the same key as every other surface (see Authentication & access).

curl -H "x-api-key: YOUR_API_KEY" \
  "https://apis.edited.com/schema/v1/brands"

Discovery endpoints​

These four endpoints return the valid values for their matching filters. Each returns the full list, so fetch it once and cache it rather than calling it per query.

Brands — GET /schema/v1/brands​

The normalized brands. Each brand's slug is the input for the brand_slug filter. Copy it exactly: the filter is case-sensitive and some slugs carry capitals (e.g. LC-Waikiki). The brand filter is a free-text match on the brand name, so pass the name there, never a slug. (brand_slug is only present on documents whose brand EDITED has normalized.)

{
  "brands": [
    { "name": "Love Moschino", "slug": "love-moschino" }
  ]
}

Retailers — GET /schema/v1/retailers​

The retailers and their slugs — the valid input for the retailer filter. This is the full list, not filtered to your subscription, so it can include retailers your key can't query. Each regional storefront is its own retailer with its own slug (Zara UK and Zara ES are separate) — resolve the market first; see Before you build.

{
  "retailers": [
    { "name": "My Retailer", "slug": "my-retailer" }
  ]
}

Searches — GET /schema/v1/searches​

The product searches — the category / subcategory / style tree — and the valid input for the product_searches filter. Each row carries a type (top_level_category, subcategory, or style) and a parent_id linking it to its parent; a top-level category has parent_id: null.

{
  "searches": [
    {
      "category": "bottoms",
      "id": 535,
      "name": "Bottoms",
      "parent_id": null,
      "type": "top_level_category",
      "vertical": "apparel"
    },
    {
      "category": "bottoms",
      "id": 1344,
      "name": "Shorts",
      "parent_id": 535,
      "type": "subcategory",
      "vertical": "apparel"
    }
  ]
}

Names repeat across the tree, so match on parent_id, not just name. For example, there are three different Shorts — under Bottoms, under Pyjama Bottoms, and under Underwear — so resolving by name alone can pick the wrong one.

Details — GET /schema/v1/details​

The product details — the valid input for the product_details filter. It has the same { id, name, parent_id } tree shape as searches.

{
  "details": [
    { "id": 276, "name": "Fabrication", "parent_id": null },
    { "id": 60, "name": "Denim", "parent_id": 276 }
  ]
}

Schema version — GET /schema/v1/{schema_version}​

Returns the field definitions and types for a given schema version. Every option document is tagged with the schema_version used to generate it; the default is 2018-04-18. This is the machine-readable companion to the data dictionary — see Operations → Versioning for how schema_version works.

curl -H "x-api-key: YOUR_API_KEY" \
  "https://apis.edited.com/schema/v1/2018-04-18"
{
  "schema": {
    "brand": {
      "__definition": "The product brand, normalised across EDITED's dataset.",
      "type": "text"
    },
    "brand_slug": {
      "__definition": "A short representation of a product's brand name with no spaces or special characters.",
      "type": "keyword"
    }
  }
}

Which endpoint resolves which filter​

To filter by…CallMCP equivalent
brand_slug (the slug) · brand (the name)/brandssearch_brands
retailer/retailerssearch_retailers
product_searches/searchessearch_product_searches
product_details/details—