# Dotlas Data API

REST access to Dotlas restaurant-intelligence data, for clients and agents. It exposes the same coverage as the Dotlas MCP server over plain HTTP.

## Authentication

Every request requires an organization API key:

    Authorization: Bearer dl_live_<key>

Keys are provisioned by Dotlas (no self-service issuance). Every response is automatically scoped to the markets (countries) and brands your organization is entitled to. Requesting one outside your scope returns 403.

## Conventions

- Base URL: `https://api.dotlas.com/v1`
- OpenAPI 3.1 contract (generate a typed client from it): `GET /v1/openapi.json`
- Errors are JSON: `{ "error": { "code": "...", "message": "..." } }`.
  - `401` unauthenticated (missing/invalid key), `403` forbidden (out of your org's scope),
    `404` not found, `429` rate limited (with a `Retry-After` header).
- Pagination: list endpoints return `{ data: [...], pageInfo: { nextCursor, hasMore } }`.
  Pass `cursor=<nextCursor>` to fetch the next page; `limit` bounds the page size.
- Rate limits are per organization, per 10-minute window.
- All monetary values are in each market's own local currency and are never cross-converted.

## Endpoints

### GET /v1/markets

List markets

### GET /v1/brands

Search brands

Parameters:
- `countryCode` (query, required)
- `query` (query)
- `limit` (query)

### GET /v1/brands/{brandSlug}/menu

Get brand menu

Parameters:
- `brandSlug` (path, required)
- `countryCode` (query, required)

### GET /v1/brands/{brandSlug}/outlets

List brand outlets

Parameters:
- `brandSlug` (path, required)
- `countryCode` (query, required)
- `limit` (query)
- `cursor` (query)

### GET /v1/brands/{brandSlug}/items/{itemId}/price-history

Get item price history

Parameters:
- `brandSlug` (path, required)
- `itemId` (path, required)
- `countryCode` (query, required)
- `from` (query)
- `to` (query)
- `limit` (query)
- `cursor` (query)

### GET /v1/brands/{brandSlug}/menu/sections

Get menu sections

Parameters:
- `brandSlug` (path, required)
- `countryCode` (query, required)
- `status` (query)
- `city` (query)
- `area` (query)
- `neighbourhoodId` (query)

### GET /v1/brands/{brandSlug}/menu/sections/{section}/items

List items in a section

Parameters:
- `brandSlug` (path, required)
- `section` (path, required)
- `countryCode` (query, required)
- `status` (query)
- `city` (query)
- `area` (query)
- `neighbourhoodId` (query)

### GET /v1/brands/{brandSlug}/items/{itemId}/source-prices

Get item prices by outlet

Parameters:
- `brandSlug` (path, required)
- `itemId` (path, required)
- `countryCode` (query, required)

### GET /v1/brands/{brandSlug}/items/{itemId}/events

Get item menu events

Parameters:
- `brandSlug` (path, required)
- `itemId` (path, required)
- `countryCode` (query, required)
- `from` (query)
- `to` (query)
- `limit` (query)
- `cursor` (query)

### GET /v1/brands/{brandSlug}/search-ranking

Get search ranking

Parameters:
- `brandSlug` (path, required)
- `countryCode` (query, required)
- `searchQuery` (query)
- `city` (query)
- `neighbourhood` (query)
- `neighbourhoodId` (query)
- `source` (query)
- `searchQueryType` (query)
- `searchMode` (query)
- `from` (query)
- `to` (query)
- `limit` (query)
- `cursor` (query)

### GET /v1/brands/{brandSlug}/search-queries

List search queries

Parameters:
- `brandSlug` (path, required)
- `countryCode` (query, required)
- `source` (query)
- `limit` (query)
- `cursor` (query)

### GET /v1/brands/{brandSlug}/delivery-performance

Get delivery performance

Parameters:
- `brandSlug` (path, required)
- `countryCode` (query, required)
- `source` (query)
- `city` (query)
- `area` (query)
- `neighbourhoodId` (query)

### GET /v1/brands/{brandSlug}/outlets/nearby

List nearby outlets

Parameters:
- `brandSlug` (path, required)
- `countryCode` (query, required)
- `lat` (query, required)
- `lng` (query, required)
- `radius` (query)
- `limit` (query)
- `cursor` (query)

### GET /v1/markets/{countryCode}/neighbourhoods

List neighbourhoods

Parameters:
- `countryCode` (path, required)
- `limit` (query)
- `cursor` (query)

### GET /v1/brands/{brandSlug}/competitors

List competitors

Parameters:
- `brandSlug` (path, required)
- `countryCode` (query, required)
- `limit` (query)
- `cursor` (query)

### GET /v1/brands/{brandSlug}/promotions

List promotions

Parameters:
- `brandSlug` (path, required)
- `countryCode` (query, required)
- `type` (query)
- `from` (query)
- `to` (query)
- `restaurantId` (query)
- `limit` (query)
- `cursor` (query)

### GET /v1/brands/{brandSlug}/outlets-feed

List outlet events

Parameters:
- `brandSlug` (path, required)
- `countryCode` (query, required)
- `from` (query)
- `to` (query)
- `limit` (query)
- `cursor` (query)

### GET /v1/brands/{brandSlug}/social-media

List social posts

Parameters:
- `brandSlug` (path, required)
- `countryCode` (query, required)
- `from` (query)
- `to` (query)
- `limit` (query)
- `cursor` (query)

### GET /v1/brands/{brandSlug}/items/recent-events

List items with recent changes

Parameters:
- `brandSlug` (path, required)
- `countryCode` (query, required)
- `from` (query)
- `to` (query)
- `eventType` (query)
- `restaurantId` (query)
- `limit` (query)
- `cursor` (query)

### GET /v1/markets/{countryCode}/cuisines

List cuisines

Parameters:
- `countryCode` (path, required)

### GET /v1/menu-event-types

List menu event types

Parameters:
- `countryCode` (query, required)
- `brandSlug` (query, required)