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-...",
    "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

All three URLs are production endpoints and behave identically — use whichever fits your setup:

Base URL
https://api.sarufi.io/api/dev/v1
https://beta-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

Operation	Limit
Reads	1 request / second
Writes / Updates	1 request / 2 seconds

If you exceed the limit you receive 429 Too Many Requests. The Retry-After header indicates how many 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."
}