API reference
Authentication
The headers every API call needs: X-Api-Key and X-Agent-Id, plus the optional X-Llm-Key, X-Request-Id and X-Perf-Timing.
Reference2 min readUpdated 23 October 2026
The API authenticates with your secret key in the X-Api-Key header. There is no Authorization: Bearer scheme and no OAuth: send the key as it is, over HTTPS, from your server.
Request headers
| Header | Required | What it does |
|---|---|---|
X-Api-Key | Yes | Your secret key, sk-so-…. Missing: 401 MISSING_API_KEY. Wrong or inactive: 401 INVALID_API_KEY |
X-Agent-Id | For chat and ingest | The agent's UUID. You can send agent_id in the JSON body instead; the header wins if both are sent. Missing: 400 MISSING_AGENT_ID |
Content-Type | Yes (JSON bodies) | application/json |
X-Llm-Key | No | A model provider key used for this request only, instead of the agent's saved key |
X-Request-Id | No | Your correlation id (8 to 128 characters of letters, digits and ._:-). See Request ids |
X-Perf-Timing | No | Send 1 to get a timing breakdown in the done event |
Which agents a key can reach
A secret key reaches every agent on its account and nothing else. An agent id from another account is answered with 404 AGENT_NOT_FOUND, the same as an id that doesn't exist, so ids can't be probed. A paused agent answers 403 AGENT_INACTIVE unless the body sets "allow_unpublished": true (for testing).
Example
curl -N https://api.sentientone.ai/v1/chat/stream \ -H "Content-Type: application/json" \ -H "X-Api-Key: $SENTIENTONE_API_KEY" \ -H "X-Agent-Id: $AGENT_ID" \ -d '{"message": "Where is order 10482?"}'Key checks are cached
To keep requests fast, a valid key is remembered for up to 60 seconds. If a key is changed on your account, the old one can keep working for up to a minute.
Authentication for the widget
The website widget authenticates with the agent's publishable key, not your secret key. Sending a secret key on the widget path is refused with 401 SECRET_KEY_NOT_ALLOWED. See Publishable keys.
Can I send the key as a query parameter?
No. Use the X-Api-Key header. (Workflow webhook triggers are different: they take their own wft_ token as a header or ?token=.)
I get 401 INVALID_API_KEY with a key I just copied
Check for a missing character or a trailing space or newline, and that it starts with sk-so-. A pk-so- key only works on the widget.
Still stuck?
Email us with what you tried and any request id. A person replies.