Getting Started

How the platform works

Sarufi is organized around a hierarchy of resources. Understanding how they connect makes every API call obvious.

Workspace
└── Chatbot
    ├── Flows          ← conversation logic (state machine)
    │   └── States → Transitions → Actions (API calls, LLM, etc.)
    ├── Knowledge Bases ← documents for AI-powered answers
    └── Integrations   ← channels: WhatsApp, Web widget, SMS, API
         │
         ▼
    Conversations (one per user session, per channel)
    └── Messages       ← user input + bot response pairs

The request path for an end-user message:

User (WhatsApp / Web / SMS / API)
  │  sends message
  ▼
Channel gateway
  │  routes to chatbot
  ▼
Conversation engine
  ├── loads current conversation state
  ├── evaluates flow transitions
  ├── runs state actions (API calls, LLM turns, …)
  └── renders reply messages
  │
  ▼
Bot reply delivered back to user

Key concepts

Concept	What it is
Workspace	Your top-level account. Holds API keys and all chatbots.
Chatbot	A single bot instance with its own flows, channels, and settings.
Flow	A state machine that drives conversations. Each chatbot has one active (published) flow.
State	A point in a conversation — defines what the bot says and what happens next.
Integration	A connected channel (WhatsApp number, web widget, SMS line) or external tool.
Conversation	A session between one user and the chatbot, scoped to a channel.
Knowledge Base	A collection of documents the chatbot can search to answer questions.

---

Quick start

Get your workspace details in 30 seconds:

cURL

curl -X GET https://api.sarufi.io/api/dev/v1/me \
  -H "Authorization: Bearer <your-api-key>"

Python

import requests

response = requests.get(
    "https://api.sarufi.io/api/dev/v1/me",
    headers={"Authorization": "Bearer <your-api-key>"},
)
print(response.json())

JavaScript

const response = await fetch("https://api.sarufi.io/api/dev/v1/me", {
  headers: { "Authorization": "Bearer <your-api-key>" },
});
const data = await response.json();

{
  "workspace": {
    "id": "01JMXYZ...",
    "name": "My Workspace"
  },
  "api_key": {
    "key": "sk_live_...",
    "created_at": "2026-01-15T10:00:00Z"
  }
}

Get your API key

Go to your Sarufi workspace → Settings → API Keys to generate your developer API key.

---

Base URL

Use https://api.sarufi.io/api/dev/v1 as the primary API base URL. The developers.sarufi.io host points to the same API version and can be used as an equivalent alias.

Base URL
https://api.sarufi.io/api/dev/v1
https://developers.sarufi.io/api/dev/v1

All endpoints are organized under the path /api/dev/v1.

---

Rate limits

Limits are counted per API key, in three separate buckets. Every endpoint in a bucket shares that bucket's count.

Bucket	Endpoints	Limit
Reads	Every GET (workspace, chatbots, flows, conversations, integrations, knowledge bases, analytics)	60 requests per 60 seconds
Writes	Every POST, PUT, PATCH and DELETE on those resources, including publishing a flow and sending an outbound message	30 requests per 60 seconds
Chat	Creating a chat session and sending a message to it (Chat API)	600 requests per 60 seconds

If you exceed a limit you receive 429 Too Many Requests with detail Too many requests. Please try again later. and a Retry-After header giving the seconds to wait.

---

Request format

• Content-Type: application/json for all requests with a body
• Accept: application/json
• All timestamps are ISO 8601 UTC strings

---

Response format

Successful responses return JSON with the resource data. Paginated list endpoints return:

{
  "items": [...],
  "next_cursor": "opaque-string-or-null",
  "total": 42
}

Pass cursor in subsequent requests to page through results.

---

Error responses

Status	Meaning
400	Bad request — validation error in request body
401	Unauthorized — missing or invalid API key
403	Forbidden — action not permitted for this workspace
404	Not found — resource does not exist
409	Conflict — resource already exists
422	Unprocessable entity — schema validation failed
429	Too Many Requests — rate limit exceeded
500	Internal server error

Error bodies include a detail field:

{
  "detail": "Chatbot with this name already exists in workspace."
}