API reference

16 endpoints across 6 tag groups.

Every endpoint requires the bearer header. All paths sit under api.sendside.xyz/v1. Successful responses are wrapped in the SousLab envelope. The gateway only exposes the meta / search / restaurants / chains / prices / stats surfaces — upstream /admin paths are not reachable through /v1.

Response envelope

Successful 2xx JSON is always wrapped: { data, pagination?, meta? }. List endpoints carry limit, offset, returned, has_more, and a total when known (total for exact counts, total_estimated for searches). Single-resource endpoints just return { data }. Errors and non-JSON bodies pass through unchanged.

{
  "data": [ ... ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "returned": 20,
    "total": 487,           // exact, for /chains, /search
    "has_more": true
  },
  "meta": { "query": "ramen", "processing_ms": 7 }
}

AUTHAuthorization: Bearer sk_live_…on every call (except /v1/health)Authentication →

Search

Full-text + filter search across restaurants and items. Backed by Typesense upstream; results carry processing_ms in the meta block. Each hit's record is returned at the top of the document object — opt in to per-hit highlight snippets with ?include_highlights=true. Search index covers ~92% of items today; full coverage is in flight.

POST/v1/search/restaurants

Search restaurants

Full-text restaurant search with optional state / cuisine / geo-radius / source-tier filters. When `geo` is present, results are sorted by distance.

Parameters

Body

qstringdefault

Free-text query. Empty string returns top-ranked restaurants (useful with filters).

statestring

Two-letter state code (e.g. NY).

cuisinestring

Matches cuisine_primary.

cuisinesstring[]

Match ANY cuisine in the cuisines[] array.

geoGeoRadius

Optional radius filter: { lat, lng, radius_m } (radius_m max 50,000). Sorts by distance.

has_geoboolean

Filter to restaurants with geo.

data_tierstring

Filter to one source tier.

primarysecondarysupplemental

data_tier_instring[]

Filter to multiple tiers.

data_confirmationstring

Filter by confirmation level of the source data.

highmediumlow

sortstring[]

Sort fields, e.g. ["item_count:desc"].

limitintegerdefault 20

1–100.

offsetintegerdefault 0

0–10,000.

POST/v1/search/items

Search menu items

Full-text search across menu items (dish names, descriptions). Optional state / cuisine / price-range / stock filters.

Parameters

Body

qstringdefault

Free-text query.

statestring

Two-letter state code.

cuisinestring

Restrict to one cuisine.

min_pricenumber

Minimum item price (USD).

max_pricenumber

Maximum item price (USD).

in_stock_onlybooleandefault false

Hide items with out_of_stock=true.

geoGeoRadius

Optional radius filter; sorts by distance.

data_tierstring

Filter to one source tier.

primarysecondarysupplemental

data_tier_instring[]

Filter to multiple tiers.

sortstring[]

Sort fields, e.g. ["price:asc"].

limitintegerdefault 20

1–100.

offsetintegerdefault 0

0–10,000.

Restaurants

Single-restaurant lookups: full record, normalized menu.

GET/v1/restaurants/{restaurant_id}

Restaurant details

Full record for a single restaurant: name, address, geo, cuisines, price stats, social media, item count.

Parameters

Path

restaurant_idULID (26 chars)required

Restaurant ID. Format: Crockford base32, 26 chars.

GET/v1/restaurants/{restaurant_id}/menu

Restaurant menu

Complete normalized menu: menus → sections → items. Items include parsed price (number) and price_text (the original string — populated when upstream could not coerce to a number, e.g. “Market price”).

Parameters

Path

restaurant_idULID (26 chars)required

Restaurant ID.

curl https://api.sendside.xyz/v1/restaurants/01KQQ8EZ3VM7FCTFVY9CWQ647X/menu \
  -H "Authorization: Bearer $SOUSLAB_API_KEY"

Response●200 OK · application/json

{
  "data": {
    "restaurant_id": "01KQQ8EZ3VM7FCTFVY9CWQ647X",
    "restaurant": "Beer City Pizza",
    "total_items": 104,
    "menus": [
      {
        "menu_name": "Pizzas",
        "sections": [
          {
            "section_name": "Specialty",
            "items": [
              {
                "item_uid": "9b2c1a4f8e6d3b7a5c9d8e6f1a2b3c4d",
                "item_name": "Margherita",
                "description": "Tomato, fresh mozzarella, basil.",
                "price": 17,
                "price_text": "$17",
                "currency": "USD",
                "out_of_stock": false
              }
            ]
          }
        ]
      }
    ]
  }
}

Chains

The chain entity layer: brand → corporate parent → public ticker. Locations, canonical menu items, and geographic price summaries per chain.

GET/v1/chains

List chains

Paginated list of restaurant chain entities. Filter by ticker, parent company, cuisine, coverage priority, or full-text on canonical name. Sortable by location count or name.

Parameters

Query

qstring

Search canonical_name + display_name.

tickerstring

Restrict to one public ticker.

parentstring

Parent company legal name (case-insensitive substring).

cuisinestring

Filter by primary cuisine.

prioritystring

Coverage priority bucket.

alt_data_criticalcpg_criticalstandard

public_onlybooleandefault false

Restrict to chains tied to a public ticker.

sortstringdefault locations_desc

locations_desclocations_ascname_ascticker_asc

limitintegerdefault 50

1–200.

offsetintegerdefault 0

0–10,000.

GET/v1/chains/{chain_id}

Chain details

Full chain entity record.

Parameters

Path

chain_idstring (10–32 chars)required

GET/v1/chains/{chain_id}/locations

Chain locations

Individual storefronts attached to a chain. Filter by state / city / metro (3-digit zip prefix).

Parameters

Path

chain_idstringrequired

Query

statestring

Two-letter state code.

citystring

Case-insensitive city_name match.

metrostring

3-digit zip prefix.

limitintegerdefault 50

1–500.

offsetintegerdefault 0

0–20,000.

GET/v1/chains/{chain_id}/canonical-items

Chain canonical items

Core menu items canonicalized across all locations of a chain. Populated for chains tagged alt_data_critical; returns an empty array for chains without canonical coverage.

Parameters

Path

chain_idstringrequired

GET/v1/chains/{chain_id}/price-summary

Chain price summary

Geographic spread of prices for one canonical item across a chain. Aggregates current per-source prices, grouped by state / metro / zip3 / none. Returns location count + min/median/avg/max per group.

Parameters

Path

chain_idstringrequired

Query

canonical_item_idstringrequired

Get this from /v1/chains/{id}/canonical-items.

group_bystringdefault state

metro = first 3 of zip; none = single row, with group_key returned as null.

statemetrozip3none

data_tierstring

Restrict to one tier; default = all tiers.

primarysecondarysupplemental

# Big Mac price by metro across all McDonald's locations
curl "https://api.sendside.xyz/v1/chains/01KR2R1CVHZ0XC9NX4TDY1G3AQ/price-summary?canonical_item_id=01KR2X7W9MTR3N5Q2H8K4FZD7P&group_by=metro" \
  -H "Authorization: Bearer $SOUSLAB_API_KEY"

Response●200 OK · application/json

{
  "data": {
    "chain_id": "01KR2R1CVHZ0XC9NX4TDY1G3AQ",
    "canonical_item_id": "01KR2X7W9MTR3N5Q2H8K4FZD7P",
    "group_by": "metro",
    "data_tier": null,
    "groups": [
      {
        "group_key": "100",
        "location_count": 142,
        "price_min": 5.49,
        "price_median": 6.29,
        "price_avg": 6.31,
        "price_max": 7.99
      },
      {
        "group_key": "900",
        "location_count": 188,
        "price_min": 5.29,
        "price_median": 6,
        "price_avg": 6.08,
        "price_max": 7.49
      }
    ]
  }
}

GET/v1/parent-companies/{parent_company_id}

Parent company

Corporate parent record + the chains it owns. Useful for ticker-level rollups (e.g. all chains under YUM, INSP, QSR).

Parameters

Path

parent_company_idstringrequired

Prices

Per-item current prices across sources, plus chronological price-change history.

GET/v1/items/{item_uid}/current

Current item prices

All current per-source prices for one item. Returns one observation per (item, source) — the same canonical menu item may appear on multiple aggregator sources at different prices.

Parameters

Path

item_uidhex (32 chars)required

Item UID. Format: lowercase hex, 32 chars.

GET/v1/items/{item_uid}/price-history

Item price history

Chronological price-change events for one item, across all sources. Each event carries an observation_method field — one of refresh, backfill, manual, or seed — indicating how the price was captured.

Parameters

Path

item_uidhex (32 chars)required

Query

sinceISO-8601 timestamp

Only changes after this instant.

limitintegerdefault 100

1–1,000.

GET/v1/restaurants/{restaurant_id}/price-history

Restaurant price history

All price-change events across all items at one restaurant. Each event carries an observation_method field — one of refresh, backfill, manual, or seed — indicating how the price was captured.

Parameters

Path

restaurant_idULID (26 chars)required

Query

sinceISO-8601 timestamp

Only changes after this instant.

limitintegerdefault 200

1–1,000.

Stats

Aggregate counts and percentile prices by region.

GET/v1/stats/top-cuisines

Top cuisines

Aggregate cuisine counts across the dataset, optionally filtered by state and / or city.

Parameters

Query

statestring

Two-letter state code.

citystring

City name (case-insensitive).

limitintegerdefault 20

1–100.

GET/v1/stats/{state}/{city}

City stats

Restaurant + item counts, average / median / 90th-percentile prices, and top cuisines for a single city.

Parameters

Path

statestringrequired

Two-letter state code.

citystringrequired

City name (URL-encoded).

Looking for a specific pattern?

The Recipes page has worked examples for the most common flows: search-by-city, chain price benchmarking, ticker-level price history. Or email hello@sendside.xyz and we'll write the snippet.