Sakhai Calls · Cognio Lab LLC

The docs

API version 1 · this page updated 25 September 2026 · openapi.json

One request is one telephone call, in your user's name. What comes back is a written note and one of four words. Never the audio, never a transcript.

1. A key

A phone number is the account. Open api.sakhai.care/signup, or do it by hand:

POST https://api.sakhai.care/api/v1/signup
{"phone": "+14155550123"}
→ 200 {"ok": true, "to": "****0123", "expires_in": 600}

POST https://api.sakhai.care/api/v1/signup/verify
{"phone": "+14155550123", "code": "482913",
 "label": "my assistant", "webhook": "https://you.example/sakhai"}
→ 200 {"key": "sk_sakhai_…", "secret": "…", "name": "t-3f9a1c", "rotated": false}

The key and the signing secret are shown once. The same number again mints a new key and the old one dies — that is how a key is rotated, and how a lost one is recovered. Three codes an hour per number; a code lives ten minutes and five tries.

2. Base URL and authorization

https://api.sakhai.care/api/v1
Authorization: Bearer sk_sakhai_…
Content-Type: application/json

Everything is JSON. The spec is openapi.json (OpenAPI 3.1); paste it into any client generator, or into an assistant that takes a spec.

3. The tasks

GET /tasks returns this catalogue as JSON. Each task is one errand; needs are refused missing; what she asks is roughly how she puts it on the line, and ask is the question you put to your user before you send consent: true — filled in with what they told you.

An arrange task needs for.name — whose name the booking goes in. An ask task does not.

4. Place a call

Gather first, then read back, then consent. Your user will say something short — "call the school, Arjun's out sick Monday" — and will not know what a call needs. That is your job, in conversation: ask for what the task needs and nothing more, one question at a time (the catalogue lists each task's fields; a 400 missing names what is still empty; a 422 no_number means the business could not be found from its name and town, so ask for the number). Then show the three things — the business, its number, and the errand in one sentence — and end with the task's own question: ask in the catalogue is a template you fill — "Shall I ring California High School and report Amy out on Tuesday, September 29?" — never a form's "do you consent". Their yes to that question is what consent: true means. It is never assumed from the first message, and it is never set by you. If your user gives a number where the business can reach them, send it as for.phone; an attendance line or a recorder will ask for one.

POST /calls
{
  "task": "book_table",
  "business": "Piatti",            ← the name; with "phone", or findable with "town"
  "phone": "+19253280525",         ← their number, E.164 or local to "country"
  "town": "Danville",
  "country": "US",
  "tz": "America/Los_Angeles",     ← your user's zone; their hours are judged in it
  "details": {"date": "2026-09-26", "time": "19:00", "party": 2},   ← ISO; she says "Saturday, September 26 at 7 PM"
  "for": {"name": "Moses Rajan", "phone": "+14155550123"},
  "fallback": "any time between six and eight",
  "consent": true,                 ← required, and it is yours
  "webhook": "https://you.example/sakhai",
  "idempotency_key": "order-8812"
}
→ 202
{"id": "c_x9Qk3nLp2aBc", "task": "book_table", "status": "calling",
 "business": "Piatti", "number": "+19253280525",
 "errand": "a table for 2 on 2026-09-26 at 19:00",
 "for": {"name": "Moses Rajan", "phone": "+14155550123"},
 "outcome": null, "created": 1790316639.0, "ended": null, "webhook_delivered": false}

5. Read it back

GET /calls/c_x9Qk3nLp2aBc        the same object, settled or not
GET /calls                       this key's last fifty, newest first: {"calls": [...]}

status runs queued → calling → one of completed, needs_user, failed. A call settles within a few minutes: talking is capped at four, hold at twenty.

6. The webhook

When the call settles, the Call object is POSTed to the call's webhook (else the key's). Three tries — 1, 5 and 25 seconds apart — until you answer with any 2xx. Every POST carries

X-Sakhai-Signature: <unix seconds>.<hex hmac-sha256>

where the HMAC, keyed with your signing secret, is over "<unix seconds>." + the raw body. Verify it, and drop anything more than five minutes old:

import hmac, hashlib, time

def verify(header: str, raw_body: bytes, secret: str) -> bool:
    ts, _, mac = header.partition(".")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    want = hmac.new(secret.encode(), ts.encode() + b"." + raw_body,
                    hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, mac)

7. The outcome

{"id": "c_x9Qk3nLp2aBc", "status": "completed", ...,
 "outcome": {
   "answer": "seven for two, in the name Rajan",   what they said
   "price": "",                                   a price, when one was given
   "conditions": "fifteen minutes' grace",        the small print they said
   "booked": true,                                an arrangement was made
   "confirmed": true,                             …and the other end said it back
   "held_s": 75,                                  seconds on hold
   "via": "phone",
   "answered_by_assistant": false,                their side was a machine
   "left_message": false, "message": "",          a recorder took it (report_absence)
   "reason": ""                                   why needs_user or failed, in a phrase
 }}

A fourth word, wrong result, exists only in our own judged sheet: a person's mark against what the business actually said, never the engine's own. That sheet is where the number on the front page will come from.

8. Errors

Every error is {"error": "<word>", "detail": "<a sentence>"}, with fields when fields are missing and id when a call was opened before the refusal.

9. What is never rung

A pharmacy, a doctor's or dentist's office, a clinic, a hospital, a lab, a vet, an insurer or health plan, a bank or credit union, a tax office, a utility account — anywhere the other end must find your user in its own records first — is refused at submit with 422 identity, and nothing is dialled. She never asks for a date of birth, a member number or a prescription number to try anyway. That is your user's call to make themselves.

The detail of that refusal is a whole answer you can show as it is, and it ends with the line's number — the one you sent, or the one Sakhai looks up on Google Maps by name and town, with the street and today's hours. The same number comes back structured beside it: number (E.164) and tel (a tel: link), so your user can tap it and ring themselves. If you refuse such a line on your own side, still give the person its number — or send the request and Sakhai returns it. Do not collect a date of birth, a member number or a prescription number on your side to try instead; the whole point is that nobody does.

A name for a reservation, a pickup, a stock check or a school's attendance line is a booking name, not a lookup, and stays.

10. Limits

• Three calls on the line per key at once.
• Four minutes talking, twenty on hold; then failed with the reason.
• The business's own hours in your user's zone; never before eight in the morning or after nine at night, whatever the sign says.
• Businesses only. She says on every call that she is an AI calling on someone's behalf and that the call is transcribed.
• The last fifty calls are readable per key; the outcome is kept as words, the transcript is not kept at all.

11. As an MCP server

For Claude, ChatGPT or any MCP host: a single-file server with three tools — make_call, check_call, list_tasks — standard library only, stdio.

{"mcpServers": {"sakhai-calls": {
  "command": "python3", "args": ["/path/to/sakhai_calls_mcp.py"],
  "env": {"SAKHAI_CALLS_URL": "https://api.sakhai.care/api/v1",
          "SAKHAI_CALLS_KEY": "sk_sakhai_…"}}}}

The file is sakhai_calls_mcp.py in the Sakhai server repository; write to support@cogniolab.com for it, or for anything else on this page.