1
Create your key
Open Settings → API in your Sadakio account and get your sk_ key in seconds. The raw key is shown only once, so store it somewhere safe.
</> Developers
Sadakio Web API: build your own loyalty stack
Stamps, points or 5% cashback? Define your programme in the panel and read its data from the API: guest list, visit feed, returning-guest metrics. Connect it to your POS, or build your own product on top of Sadakio.
$ curl https://api.sadakio.com/api/v1/guests \
-H "Authorization: Bearer sk_YOUR_KEY"
{
"data": [{
"id": 184,
"name": "Elif T.",
"masked_phone": "+••••••••4579",
"visits_count": 12,
"last_visit": "2026-09-16T08:31:00Z"
}],
"next_cursor": null
}
Your first request in 3 steps
2
Make your first request
Call the /api/v1/guests endpoint with curl. The responses are your own business’s data, and phone numbers come back masked.
3
Integrate from the contract
Hand the open OpenAPI 3.0 file (openapi.yaml) to your tooling or your AI assistant and generate the integration in minutes.
Endpoints you can use today
Base URL: https://api.sadakio.com/api/v1. All of them are read endpoints and work with the read scope.
GET/guestsGuest list: search, updated_since, masked phones
GET/guests/{id}One guest in detail, with their cards and programme types
GET/visitsVisit feed: date filters, cursor pagination
GET/stats/retentionReturning-guest summary: 7 / 30 / 365-day windows or your own date range
GET/openapi.yamlOpen OpenAPI 3.0 contract, no key needed
Roadmap not live yet
Write endpoints and webhooks are forward-looking items. This page lists only what works today. The MCP server is live now, below.
Let your AI assistant connect directly
The Sadakio MCP server is live. Claude, Cursor or any other MCP client reads your café’s own data with one line. Nothing to install, the command fetches the package itself. The server only reads and changes nothing.
npx sadakio-mcp # Node 18 and up uvx sadakio-mcp # Python 3.10 and up
Paste it into your client’s config file, add your key, done
{
"mcpServers": {
"sadakio": {
"command": "npx",
"args": ["-y", "sadakio-mcp"],
"env": { "SADAKIO_API_KEY": "sk_YOUR_KEY" }
}
}
}
MCPlist_guestsGuest list: search and pagination, masked phones
MCPget_guestOne guest in detail, with their cards and programme type
MCPlist_visitsVisit feed: date filters
MCPget_retentionReturning-guest summary: 7 / 30 / 365-day windows or your own date range
Pick your language and connect
curl "https://api.sadakio.com/api/v1/stats/retention?period=month" \ -H "Authorization: Bearer sk_YOUR_KEY"
const r = await fetch("https://api.sadakio.com/api/v1/stats/retention?period=month", {
headers: { Authorization: "Bearer " + process.env.SADAKIO_API_KEY }
});
const { data } = await r.json();
console.log(data.returned_guests, data.returned_visits);
import os, requests
r = requests.get(
"https://api.sadakio.com/api/v1/stats/retention",
params={"period": "month"},
headers={"Authorization": f"Bearer {os.environ['SADAKIO_API_KEY']}"},
)
data = r.json()
60 requests per second and 10,000 per day, per key. The remaining quota comes back in the X-RateLimit-Limit / Remaining / Reset headers. Branch on the HTTP status code: on a 429, wait and retry. The Retry-After header can also appear on successful responses and is not a slow-down signal on its own.
Paste it to your assistant and let it build the rest
If you use Cursor, ChatGPT or Claude, copy this ready-made prompt and your assistant reads the OpenAPI contract and writes the integration for you.
Build an integration with the Sadakio Web API. Contract: https://api.sadakio.com/api/v1/openapi.yaml, summary: https://sadakio.com/llms.txt My key comes from Settings → API (Authorization: Bearer). Write me a service that fetches the guest list and reports the guests who have gone quiet.
Security & data privacy
Key = fingerprint
The raw key is shown once. The server stores only its sha256 digest, and a revoked key answers 401.
Business isolation
Each key reaches only the data of the business it is bound to. A guest id from another business answers 404.
Masked phones
Phones come back in the masked_phone field with only the last 4 digits visible (for example +••••••••4579). Responses include other fields such as the name, so keep your key secret.
Fair limits
60 requests per second and 10,000 per day per key. Keyless access to the documentation is protected per IP as well.
Frequently asked questions
How do I access the Sadakio API?
Create your sk_ key under Settings → API in your business account and call the https://api.sadakio.com/api/v1 endpoints with an Authorization: Bearer header.
Which endpoints exist today?
GET /guests (guest list), GET /guests/{id} (one guest with their cards), GET /visits (visit feed) and GET /stats/retention (returning-guest summary). The full contract is at /api/v1/openapi.yaml.
What should I do on a 429?
You hit the rate limit. Branch on the HTTP status code: on a 429, wait and retry. The X-RateLimit-* headers show the remaining quota. A Retry-After header can also appear on successful responses and is not a slow-down signal on its own.
Are guest phone numbers returned in the clear?
No. Phone numbers come back masked in the masked_phone field and only the last 4 digits are visible (for example +••••••••4579). Responses include other fields such as the guest name, and the data belongs only to the business the key is bound to.
What does returned_guests mean?
The number of guests who joined before the chosen window and visited again inside it. week/month/year are rolling 7/30/365-day windows. It is return analytics, not a revenue guarantee.
How do I connect my AI assistant?
The Sadakio MCP server is live. In Claude, Cursor or any other MCP client, define the npx sadakio-mcp or uvx sadakio-mcp command and add your key. The assistant sees four tools: list_guests, get_guest, list_visits, get_retention. The server only reads.
What is planned?
Write endpoints and webhooks are forward-looking items. This page lists only what works today.
Make your first request today
Business account, API key and open contract, all in minutes.