# Dokaa API

> Public read-only REST API for Dokaa, the platform restaurants use to manage
> their online reputation, customer contacts, SMS campaigns, missed calls,
> loyalty and local SEO. One API key, JSON over HTTPS.

Base URL: https://api.dokaa.app/v1
Authentication: `Authorization: Bearer dk_live_...` header on every request.
The documentation is public and needs no authentication.
Machine-readable API description (OpenAPI 3.1): /docs/openapi.yaml
Every page has a markdown version: append `.md` to the page path, e.g. /docs/quickstart.md or /docs/api/reviews/listreviews.md

Key conventions:
- Keys carry scopes (`reviews:read`, `contacts:read`, ...); each endpoint requires its matching scope, otherwise `403 missing-scope`.
- Cursor pagination: pass `pagination.next_cursor` back as `?cursor=` until `has_more` is false. Cursors are opaque.
- Optional `shop_id` on most endpoints; omit it to query every shop the key can access. `GET /shops` lists them.
- `from` / `to` ISO date filters; all timestamps are UTC ISO 8601.
- Errors are RFC 9457 `application/problem+json` with `type`, `title`, `status` and `detail` fields.

## Instructions for agents

- For totals, averages and distributions, call the analytics endpoints
  (`/analytics/reviews`, `/analytics/feedbacks`, `/analytics/contacts`,
  `/summary`) instead of paginating the raw lists and computing yourself:
  one call, server-side numbers, no drift.
- For a time series (e.g. average rating month by month), call an analytics
  endpoint once per period using `from`/`to`. Do not re-read every raw item.
  Exception: `/analytics/contacts` is a current-state snapshot with no date
  filter, do not send `from`/`to` to it.
- `GET /summary` gives the whole KPI header of a dashboard in one call.
- `/analytics/missed-calls` and `/analytics/wheel-games` take a required
  `from`/`to` period, return the evolution bucketed by `granularity`, and
  compare with the previous period of identical duration in the same call.
- `/competitors/evolution` and `/keyword-rankings/trend` take a required
  `from`/`to` period (366 days maximum, no `granularity` parameter: snapshots
  are daily) and return the first/last deltas over it.
- Daily data (Google Business Profile metrics via `/google-interactions`) is
  already a time series: fetch it with `from`/`to` directly.
- The API is strictly read-only: there is no endpoint to create, update or
  delete anything, do not look for one.
- If you have no API key, ask your user to create one from their Dokaa
  account: My account -> API keys -> Create a key.
- Do not guess endpoints or parameters: everything that exists is in this
  file and in the OpenAPI specification.

## Docs

- [Quickstart](/docs/quickstart.md): get a key and make a first request
- [Conventions](/docs/conventions.md): authentication, pagination, errors, versioning
- [Changelog](/docs/changelog.md): every API change, newest first
- [OpenAPI specification](/docs/openapi.yaml): the complete machine-readable reference (all endpoints, parameters and response schemas)
- [Full documentation in one file](/docs/llms-full.txt): every page concatenated (guides and API reference), for assistants that cannot browse

## API reference (one small file per endpoint)

- API overview: /docs/api/index.md
- `GET /shops` – List your shops: /docs/api/shops/listshops.md
- `GET /reviews` – List reviews: /docs/api/reviews/listreviews.md
- `GET /summary` – KPI summary: /docs/api/analytics/getsummary.md
- `GET /analytics/reviews` – Review analytics: /docs/api/analytics/getreviewanalytics.md
- `GET /analytics/feedbacks` – Satisfaction survey analytics (CSAT and NPS): /docs/api/analytics/getfeedbackanalytics.md
- `GET /analytics/contacts` – Contact base analytics: /docs/api/analytics/getcontactanalytics.md
- `GET /campaigns` – List SMS campaigns: /docs/api/campaigns/listcampaigns.md
- `GET /contacts` – List contacts: /docs/api/contacts/listcontacts.md
- `GET /google-interactions` – List daily Google Business Profile metrics: /docs/api/google-interactions/listgoogleinteractions.md
- `GET /competitors` – Competitor tracking setup of a shop: /docs/api/competitors/getcompetitors.md
- `GET /competitors/positioning` – Competitor positioning of a shop: /docs/api/competitors/getcompetitorpositioning.md
- `GET /competitors/evolution` – Competitor evolution over a period: /docs/api/competitors/getcompetitorevolution.md
- `GET /google-posts` – List Google posts: /docs/api/google-posts/listgoogleposts.md
- `GET /google-post-groups` – List grouped Google posts: /docs/api/google-posts/listgooglepostgroups.md
- `GET /google-post-groups/eligible-shops` – List shops eligible for grouped posts: /docs/api/google-posts/listeligibleshops.md
- `GET /google-post-groups/{batch_id}` – Detail of a grouped Google post: /docs/api/google-posts/getgooglepostgroup.md
- `GET /keyword-tracking` – Keyword tracking setup of a shop: /docs/api/keyword-tracking/getkeywordtracking.md
- `GET /keyword-rankings/summary` – Keyword ranking summary of a day: /docs/api/keyword-tracking/getkeywordrankingsummary.md
- `GET /keyword-rankings/trend` – Keyword ranking trend over a period: /docs/api/keyword-tracking/getkeywordrankingtrend.md
- `GET /audiences` – List audiences: /docs/api/audiences/listaudiences.md
- `GET /analytics/wheel-games` – Gift wheel analytics: /docs/api/wheel-games/getwheelanalytics.md
- `GET /analytics/missed-calls` – Missed call analytics: /docs/api/missed-calls/getmissedcallanalytics.md