API reference
Request ids and correlation
Send X-Request-Id and follow one request through the API, its trace, error reports, your model provider, MCP servers and webhooks.
Reference1 min readUpdated 23 October 2026
Every request has a request id. Send your own in X-Request-Id (or X-Correlation-Id) and the same id appears in your logs, our logs, the error envelope and the calls SentientOne makes on your behalf. That makes a failure in your system one search away from its cause.
Format
| Rule | |
|---|---|
| Accepted | 8 to 128 characters of letters, digits, ., _, : and - (regex ^[A-Za-z0-9._:-]{8,128}$) |
| Otherwise | The API makes one: 32 hex characters (a UUID without dashes) |
| Returned | Always, in the X-Request-Id response header |
Where the id goes
- The
X-Request-Idresponse header, on every response. request_idin every error envelope and every streamerrorevent.- The request's trace and every log line for it.
- Forwarded on the calls SentientOne makes for the request: to your model provider, to your MCP servers and to workflow webhooks.
- The website widget makes a new id for each message and shows it as "Reference" when a reply fails, so visitors can quote it.
Request id and trace id
The request id is for correlating systems. The trace id (X-Trace-Id, and trace_id in meta and done) opens the request in Tracing, with every span: auth, retrieval, each model round and each tool call. Log both.
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" \ -H "X-Request-Id: checkout-7f3a91c2" \ -d '{"message": "Hi"}' -D -Contacting support
Include the request_id (or the widget's Reference) when you email support@sentientone.ai. It's the fastest way for us to find the request.
Still stuck?
Email us with what you tried and any request id. A person replies.