Developer Reference

Saathi Bot API v1

A server-to-server REST API for integrating Saathi Bot into your own backend, CRM, or automation pipeline. All endpoints return JSON. Streaming is supported for chat responses.

v1.0REST · JSONSSE StreamingBYOK · Server-side only

Authentication

All v1 API requests must include your Saathi Bot API key in the Authorization header. Find your key in Dashboard → Settings → API Keys.

Server-side only. Never include your API key in client-side JavaScript, mobile app bundles, or public repositories. Your key grants full access to your bots and data.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxx

Base URL

https://saathi-bot.vercel.app/api/v1

All endpoints below are relative to this base URL. HTTPS is required on all requests.

List Bots

GET/api/v1/bots

Returns a list of all bots belonging to the authenticated organisation. Results are ordered by creation date (newest first).

curl -X GET \
  "https://saathi-bot.vercel.app/api/v1/bots" \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Response

{
  "bots": [
    {
      "id": "e4b2d1c0-1234-4567-89ab-cdef01234567",
      "org_id": "a1b2c3d4-0000-0000-0000-000000000000",
      "name": "Support Assistant",
      "public_id": "bot_9182ab34cd56ef7890",
      "welcome_message": "Hello! How can I help you today?",
      "fallback_message": "I couldn't find an answer to that. Would you like to reach our team?",
      "handoff_url": "https://example.com/contact",
      "system_instructions": "Be concise and polite.",
      "theme": { "primary": "#0f766e" },
      "confidence_threshold": 0.7,
      "content_version": 1,
      "is_active": true,
      "created_at": "2026-09-01T09:00:00Z",
      "updated_at": "2026-09-01T09:00:00Z"
    }
  ]
}

Chat

Streaming SSE

POST/api/v1/bots/:botId/chat

Sends a message to a bot and streams the reply as Server-Sent Events (SSE). Each event contains a token field with a partial text chunk. A final [DONE] event signals the end of the response.

Request Body

message

stringrequired

The user's message text. Minimum 1 character, maximum 2,000 characters.

conversationId

string

Existing conversation UUID to continue a multi-turn chat. Max 128 characters. Omit to start a new conversation.

visitorId

string

A stable identifier for the end-user (e.g. your CRM contact ID). Max 128 characters. Defaults to an API-client UUID.

curl -X POST \
  "https://saathi-bot.vercel.app/api/v1/bots/e4b2d1c0-1234-4567-89ab-cdef01234567/chat" \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "What is your refund policy?",
    "visitorId": "user_crm_42"
  }'

SSE Response Stream

data: {"token": "Our refund "}

data: {"token": "policy allows "}

data: {"token": "returns within 30 days."}

data: [DONE]

Final event metadata

The last non-DONE event may include a conversationId field to continue the chat:

data: {"conversationId": "conv_01hjabc123", "token": ""}

Error Responses

All errors return a consistent JSON envelope with a machine-readable code and human-readable message.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please slow down.",
    "retryAfter": 60
  }
}

400bad_request

Invalid or missing request body parameters

401unauthorized

Missing or invalid API key

402quota_exceeded

Organisation monthly message quota exhausted

403forbidden

API key does not have access to this bot

404not_found

Bot not found or is inactive

429rate_limited

Per-IP, per-visitor, or per-bot rate limit hit. Retry after the Retry-After header value (seconds).

503upstream_unavailable

AI provider (Gemini / Groq) is temporarily unavailable

Rate Limits

The API enforces layered rate limits to protect service quality:

Per-IP: 60 requests/minute
Per-visitor: 30 messages/minute
Per-bot: 300 messages/minute
Org monthly quota: Varies by plan — exhausting it returns 402

When rate-limited, the response includes a Retry-After header in seconds.

SDKs & Support

Official SDKs are not yet available. The API is vanilla REST and works with any HTTP client (curl, axios, fetch, httpx, etc.). For integration help, file an issue on GitHub or email support@saathibot.com.