API reference
API overview
What the SentientOne API does, its base URL, the endpoints you'll use and how requests, streams and errors fit together.
Reference2 min readUpdated 23 October 2026
Every agent you build answers on one streaming endpoint. Your server sends a message with your secret key and the agent's id, and reads the reply as server-sent events: the sources the agent found, the tools it called, the answer as it is written, and the token usage at the end. The same API also runs workflows and adds knowledge.
Base URL and format
| Value | |
|---|---|
| Base URL | https://api.sentientone.ai |
| Request bodies | JSON (Content-Type: application/json), except file uploads (multipart) |
| Chat replies | text/event-stream, one data: line per event |
| Errors | One JSON envelope: {"error": {"code", "message", "request_id"}} |
| OpenAPI | https://api.sentientone.ai/docs (Swagger UI) and /redoc |
| Health | GET /health returns {"status": "ok"}; GET /status adds the version |
| CORS | All origins are allowed, but secret keys must never be used from a browser |
Endpoints
| Method and path | Auth | What it does |
|---|---|---|
POST /v1/chat/stream | X-Api-Key + X-Agent-Id | Chat with an agent; streams the reply. See Chat stream |
POST /v1/workflows/run | X-Api-Key | Start a live run of a published workflow. See Workflows API |
POST /v1/ingest/document | X-Api-Key + X-Agent-Id | Add a PDF or text file to an agent's knowledge (50 MB max) |
POST /v1/ingest/website | X-Api-Key + X-Agent-Id | Crawl a website into knowledge |
POST /v1/ingest/snippet, /v1/ingest/qa | X-Api-Key + X-Agent-Id | Add a snippet or a Q&A pair |
DELETE /v1/ingest/source | X-Api-Key + X-Agent-Id | Remove a source and its chunks |
GET /v1/traces, /v1/traces/{trace_id} | X-Api-Key | List and read your traces |
GET /v1/analytics/summary, /v1/analytics/agents/{id} | X-Api-Key | Latency, tokens and errors over 24h, 7d, 30d or 90d |
POST /v1/widget/chat/stream | X-Widget-Key | Used by the website widget only. See Publishable keys |
The knowledge endpoints are described in Add knowledge through the API. Chat is streaming only: there is no endpoint that returns the whole reply as one JSON object, so read the stream and join the delta events.
What happens on a chat request
- The API checks your secret key and that the agent belongs to your account.
- It checks the agent's requests-per-minute limit and spends 1 credit (refunded if the reply fails).
- It opens the stream and sends
metawith the conversation id and trace id. - If the agent has knowledge, it runs hybrid search and sends
sourcesbefore the first word. - The model answers; if it calls MCP tools you get
tool_callandtool_resultevents, for up to 8 rounds. - The answer arrives as
deltaevents, thendonewith the token usage. A failure ends the stream with anerrorevent instead.
Headers you'll see
| Response header | Meaning |
|---|---|
X-Request-Id | Your correlation id, or one the API made. See Request ids |
X-Trace-Id | The request's trace in Tracing |
X-RateLimit-Limit, -Remaining, -Reset | The agent's rate-limit window (chat). See Rate limits |
X-Workflow-Run-Id | The run id (workflow runs) |
Server-Timing | Time spent in the API and upstream, for your browser's dev tools |
Start here
New to the API? Follow the quickstart, then copy a sample from Code examples.
Still stuck?
Email us with what you tried and any request id. A person replies.