API reference

Endpoints, parameters, examples.

Every endpoint requires the bearer header. All paths sit under api.souslab.site/v1.

Response envelope

Successful responses are always wrapped: { data, pagination?, meta? }. List endpoints carry pagination with limit, offset, returned, has_more, and (for searches) total_estimated. Single-resource endpoints just return { data }.

{
  "data": [ ... ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "returned": 20,
    "total_estimated": 1234,
    "has_more": true
  },
  "meta": { "query": "ramen", "processing_ms": 7 }
}

GET/v1/health

Gateway health probe

Unauthenticated. Returns the gateway's health and whether the upstream is reachable. Cached for 60 seconds — safe to call often.

api.souslab.site

curl https://api.souslab.site/v1/health

● 200 OK · 38 ms

POST/v1/search/restaurants

Search restaurants

Full-text restaurant search with optional state / city / cuisine filters. Returns a ranked list with metadata.

Body	Type	Description
qrequired	string	Free-text query.
state	string	Two-letter state code (e.g. NY).
city	string	City name.
limit	integer	Max results (default 20, max 100).

api.souslab.site

curl -X POST https://api.souslab.site/v1/search/restaurants \
  -H "Authorization: Bearer $SOUSLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"ramen","city":"portland","limit":5}'

● 200 OK · 38 ms

POST/v1/search/items

Search menu items

Full-text search across menu items (dish names, descriptions). Optional restaurant or city filters.

Body	Type	Description
qrequired	string	Free-text query.
restaurant_id	string	Restrict to one restaurant.
city	string	City name.
limit	integer	Max results (default 20, max 100).

api.souslab.site

curl -X POST https://api.souslab.site/v1/search/items \
  -H "Authorization: Bearer $SOUSLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"carbonara","city":"san francisco"}'

● 200 OK · 38 ms

GET/v1/restaurants/{restaurant_id}

Restaurant details

Full record for a single restaurant: name, address, cuisines, ratings, hours.

Path / query	Type	Description
restaurant_idrequired	string	Restaurant ID.

api.souslab.site

curl https://api.souslab.site/v1/restaurants/rst_4c1a2b \
  -H "Authorization: Bearer $SOUSLAB_API_KEY"

● 200 OK · 38 ms

GET/v1/restaurants/{restaurant_id}/menu

Restaurant menu

Complete menu for a restaurant, normalized into sections + items + prices.

Path / query	Type	Description
restaurant_idrequired	string	Restaurant ID.

api.souslab.site

curl https://api.souslab.site/v1/restaurants/rst_4c1a2b/menu \
  -H "Authorization: Bearer $SOUSLAB_API_KEY"

● 200 OK · 38 ms

GET/v1/stats/top-cuisines

Top cuisines

Aggregate cuisine counts across the dataset, optionally filtered by state.

Path / query	Type	Description
state	string	Two-letter state code (optional).
limit	integer	Max cuisines (default 20).

api.souslab.site

curl "https://api.souslab.site/v1/stats/top-cuisines?state=NY&limit=10" \
  -H "Authorization: Bearer $SOUSLAB_API_KEY"

● 200 OK · 38 ms

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

City stats

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

Path / query	Type	Description
staterequired	string	Two-letter state code.
cityrequired	string	City name (URL-encoded).

api.souslab.site

curl "https://api.souslab.site/v1/stats/CA/san%20francisco" \
  -H "Authorization: Bearer $SOUSLAB_API_KEY"

● 200 OK · 38 ms