POST /capture-session
Open a conversation in Tensile. Call once per conversation with a session_id you reuse on every event that follows.
Watch the workflow: Inspect a recorded tool failure · Authored dummy data
See how stored demo events can be inspected in Raw Logs. This clip does not execute the request examples or verify a live API response. Filter authored requests, inspect one failed tool call and read its recorded timeout. An event failure does not establish a customer outcome.
Read matching command examples.
Read the walkthrough transcript
- 00:00 — Filter the loaded requests to Failed. These are authored demo events.
- 00:05 — Inspect one failed tool call. Its identity and latency remain visible.
- 00:10 — Read the recorded timeout. An event failure is separate from a customer outcome.
Registers a conversation (session) in Tensile. Send this once when a conversation begins, then reference the same session_id on every event you capture for it.
POST https://api.withtensile.com/api/v1/capture-sessionAfter session capture, read its conversation and trace, then save a recorded run as evidence. These examples do not run the commands or verify a live SDK/API response. See the command examples.
Headers
| Header | Value | Required |
|---|---|---|
x-api-key | Your API key, sk_... | Yes |
Content-Type | application/json | Yes |
Body
| Field | Type | Required | Description |
|---|---|---|---|
session_id | UUID | Yes | Identifier for this conversation. Reuse it on every event in the conversation. |
user_data | object | Yes | Details about the end user. Must contain user_id. Use a traits object for optional pseudonymous string traits. |
metadata | object | No | Free-form session-level metadata. Allowlist the keys you send. |
timestamp | integer (ms) | No | Epoch milliseconds for when the session started. Set this explicitly. |
client_config | string | No | A label for the client or SDK that produced the session. |
user_data
user_data must include a user_id. Put optional string traits inside user_data.traits. Unknown sibling fields are discarded by the current ingestion decoder.
| Field | Type | Required | Description |
|---|---|---|---|
user_id | string | Yes | Pseudonymous end-user identifier. |
traits | object of strings | No | Optional pseudonymous attributes such as plan or region. |
customer_id | string | No | Optional downstream tenant identifier. |
Request
The IDs and timestamp below are illustrative. Use a current epoch-millisecond timestamp for a new session. The capture path retains an omitted or zero timestamp as zero; it does not substitute the current time. See Quickstart for generated IDs and timestamps.
curl https://api.withtensile.com/api/v1/capture-session \
-H "x-api-key: sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"session_id": "6f9c1b8e-3d2a-4a1f-9c7b-2e5d0a4b1c33",
"user_data": {
"user_id": "user_8f21",
"traits": { "plan": "enterprise", "region": "eu-west" }
},
"timestamp": 1712345678901,
"metadata": {
"source": "web-widget"
},
"client_config": "support-bot/1.4.0"
}'Response
HTTP 202 Accepted confirms acceptance into the ingestion buffer. Check stored
arrival in the app separately.
{
"session_id": "6f9c1b8e-3d2a-4a1f-9c7b-2e5d0a4b1c33"
}