Set a client up from your own code

Authentication

Every request carries the client's API key as a bearer token. The client creates it in their dashboard under Account → API keys; it is shown once. The key identifies the tenant, so no endpoint takes a tenant id — you cannot reach another account's data by construction, not by a check somebody remembered to write.

curl https://sipmind.net/api/v1/agent/config \
  -H "Authorization: Bearer sk-tenant-YOUR_KEY"

Quickstart: zero to answering

Four calls. The client registers themselves and gives you a key; everything after that is yours.

curl -X PATCH https://sipmind.net/api/v1/agent/config \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "business_context": "Dental clinic in Almaty. Mon-Sat 9-19. Cleaning 15000 KZT, implant from 250000 KZT. Address: Abay 15.",
    "welcome_message": "Hi, you have reached Brightwater Dental. How can I help?",
    "timezone": "Asia/Almaty"
  }'

curl -X POST https://sipmind.net/api/v1/documents \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"content": "Teeth whitening — $350, takes about 60 minutes…"}'

curl -X POST https://sipmind.net/api/v1/channels/telegram \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"bot_token": "123456:AA..."}'

# WhatsApp, when the number already sits on a Meta app you manage.
# phone_number_id is the numeric id from WhatsApp Manager — not the phone number.
curl -X POST https://sipmind.net/api/v1/channels/whatsapp \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"phone_number_id": "1236893399497040", "access_token": "EAA..."}'

# check every channel at once, including the half-connected ones
curl https://sipmind.net/api/v1/channels -H "Authorization: Bearer $KEY"

curl "https://sipmind.net/api/v1/leads?updated_since=2026-08-01T00:00:00Z" \
  -H "Authorization: Bearer $KEY"

# → {"leads": [...], "count": 12,
#    "next_updated_since": "2026-08-12T09:14:02.881Z", "has_more": false}

Keeping in sync

Lists are ordered by updated_at ascending and cursored on it. Store the next_updated_since you get back and pass it in next time; keep going while has_more is true.

Ascending is not a style choice. Newest-first with an offset loses rows: while you page through, new rows land at the top and push the boundary, so page two repeats some and skips others. With an ascending cursor a changed row moves to the end — which is where your next poll meets it.

Let your AI assistant do it

SIPmind speaks MCP, so Claude, Cursor, Codex or any MCP client can set a client up and read their data in plain language: “describe this clinic to the agent from their website, connect the Telegram bot, load the price list, ask the agent what a cleaning costs, and show me last week's leads.” Thirty-six tools cover configuring the agent — down to the facts it must say word for word — trying it the way a customer would, hiring AI employees and giving each one its own line, outbound calling, channels, the knowledge base, the Instagram comment→DM funnel, who a conversation is handed to and when they are in, webhooks, and leads, pipelines, conversations, contacts and companies.

Connect by address — nothing to install

The server lives at https://sipmind.net/mcp.

• Claude (claude.ai or the desktop app). Settings → Connectors → Add custom connector, paste the address, then sign in to SIPmind and press Allow. You choose Full or Read only; the connection appears in Account → API keys, where it can be switched off.
• Claude Code. With a key from Account → API keys:

claude mcp add --transport http sipmind https://sipmind.net/mcp \
  --header "Authorization: Bearer sk-tenant-YOUR_KEY"

• Cursor — .cursor/mcp.json:

{
  "mcpServers": {
    "sipmind": {
      "url": "https://sipmind.net/mcp",
      "headers": { "Authorization": "Bearer sk-tenant-YOUR_KEY" }
    }
  }
}

Or run it on your machine

One file, no dependencies, any Python 3.10+ — the same tools as the address above:

curl -O https://sipmind.net/mcp/sipmind_mcp.py

Claude Code — .mcp.json in that folder:

{
  "mcpServers": {
    "sipmind": {
      "command": "python3",
      "args": ["./sipmind_mcp.py"],
      "env": { "SIPMIND_API_KEY": "sk-tenant-YOUR_KEY" }
    }
  }
}

Claude Desktop — the same entry in claude_desktop_config.json, with the full path to the file in args. Codex — ~/.codex/config.toml:

[mcp_servers.sipmind]
command = "python3"
args = ["/full/path/to/sipmind_mcp.py"]
env = { SIPMIND_API_KEY = "sk-tenant-YOUR_KEY" }

If the first call answers that your Python cannot verify certificates, that is your machine's trust store, not us: run Install Certificates.command (macOS python.org builds) or pip install certifi.

Which key

A Full key sets things up. A Read only key — Account → API keys → Access — pulls leads, conversations and reports and changes nothing: the right one for an export, or for an assistant that should only look.

Try the agent before a customer does

ask_agent (REST: POST /api/v1/agent/test) sends what a customer would write and returns the agent's reply, built exactly as a live chat builds it — same prompt, knowledge base and tools. Nothing is sent, saved or booked: the tools the agent chose come back in would_call — for example submit_lead with the name and phone it would have saved — and are not run; the reply is then what the agent writes once they succeed, and tools_simulated says the success was a stand-in. Pass employee_id to try an AI employee while it is still a draft. It spends model tokens, so it takes a Full key.

curl -X POST https://sipmind.net/api/v1/agent/test \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"message": "How much is a cleaning? I am Anna, +77001234567", "channel": "whatsapp"}'
# → {"reply": "…", "would_call": [{"tool": "submit_lead", "arguments": {"name": "Anna", …}}], …}

Two things a browser has to do once. Connecting an Instagram account is a consent Meta requires a human to grant on screen, and a WhatsApp Business Account is shared with us the same way — so those are one click in the dashboard, not an API call. Everything that happens after the connection is code.

Events pushed to you

Polling is the reliable path; events are the fast one. Subscribe and we POST to your endpoint when something happens. A new account receives lead.created only, so name the events you want.

PUT /api/v1/events/subscription
{
  "url": "https://your-endpoint.example/hook",
  "events": ["lead.created", "lead.stage_changed", "call.ended"],
  "signing_secret": "<16+ characters you choose>"
}

The secret is write-only: we report whether one is set, never its value. Then every delivery looks like this.

POST https://your-endpoint.example/hook
X-SIPmind-Event: lead.created
X-SIPmind-Signature: sha256=<hmac of the raw body with your secret>

{
  "event": "lead.created",
  "tenant_id": "0de00000-…",
  "occurred_at": "2026-08-13T04:12:07.881Z",
  "data": {
    "lead_id": "9f2c…", "contact_id": "3a71…",
    "name": "Anna", "phone": "+77001234567", "email": "",
    "source": "whatsapp", "stage": "new", "message": "…"
  }
}

Verify the signature against the raw body before trusting it. We retry a 5xx or a timeout three times with growing gaps; a 4xx is treated as your endpoint saying "don't", and we stop.

Endpoints

Full request and response shapes: the OpenAPI schema — point your generator at it.

Things worth knowing before you build

What the API does not do yet

So you can plan around it rather than discover it:

• Creating an account. Clients register themselves; you work with their key.
• Connecting Instagram, and a WhatsApp number that is not yet on a Meta app you manage — those run through the dashboard's one-click flow, because the consent happens on Meta's side and needs a browser.
• Booking: the calendar settings, appointments and practitioners are set in the dashboard.
• CRM tasks, and creating or editing companies — companies can be read.
• Deleting contacts, calls or conversations. Ask us and we will do it — a partner key should not be able to erase a client's history.

Need one of these? Write to [email protected] — this list is ordered by what people ask for.