Agent API Reference
Expose Reshape agent intelligence to your server. Send a message, get a structured response —
message, accuracy, reasoning, actions, widgets.
You render it. Server-to-server only.
Overview
API Key Auth
Tenant-scoped keys in the x-api-key header. Server-to-server only — keys never go to a browser.
Sessions
Server-side, opaque context. Create once, pass session_id on every turn. Idle TTL resets each call.
Structured Response
message is always present. accuracy, reasoning, actions, widgets are optional — absent means not produced this turn.
Call Flow
validation
response generation
knowledge
Getting Started
Five steps to send your first message. Every step maps to an API call.
GET /v1/healthGET /v1/agentsagent_id values you'll use in all subsequent calls. Only agents your key is scoped to are returned.POST /v1/sessionsuser_id if you want the agent to remember the user across future sessions (coming in a future release). Store the returned session_id server-side. Without user_id, context is scoped to this session only.POST /v1/agent/respondsession_id, agent_id, and message on every turn. The agent maintains conversation context. Repeat for each user message.DELETE /v1/sessions/{session_id}Authentication
x-api-key: rxk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Every request to /agent/respond validates three things in sequence:
A session created for agent A cannot be used to call agent B. Mismatch returns SESSION_TENANT_MISMATCH.
AgentResult
Every successful POST /agent/respond returns an AgentResult. message and request_id are always present. All other fields are absent when not produced — never null.
Streaming
Pass "stream": true in the request body to receive a text/event-stream response. Each SSE data: line is a JSON StreamChunk. The stream ends with a done chunk carrying the complete AgentResult.
// Incremental text data: {"type":"text_delta","delta":"For high-speed packaging"} data: {"type":"text_delta","delta":", I recommend the S7-1500..."} // Reasoning (extended thinking models) data: {"type":"reasoning_delta","delta":"User needs high-speed..."} // Suggested next action data: {"type":"action","action":{"label":"Compare with S7-300","prompt":"..."}} // Widget (future release) data: {"type":"widget","widget":{"widget_type":"product_display",...}} // Final — complete AgentResult data: {"type":"done","result":{"request_id":"...","message":"...","feedback":{...}}}
type it doesn't recognise.
Error Codes
agent_id.POST /sessions.request_id in support requests.Rate Limits & Retry
The API enforces per-tenant rate limits. When exceeded, requests return 429 Too Many Requests with error code RATE_LIMITED.
| Error code | Recommended action |
|---|---|
| RATE_LIMITED | Back off and retry. Respect the Retry-After header if present. |
| AGENT_RUNTIME_UNAVAILABLE | Retry with exponential back-off (e.g. 1s, 2s, 4s). Likely a transient cold-start or capacity issue. |
| AGENT_RUNTIME_TIMEOUT | The request was not processed — safe to retry. If the problem persists, contact your Reshape account team. |
| INTERNAL_ERROR | Do not retry automatically. Include request_id when reporting to Reshape support. |
Zero-side-effect endpoint. No session or agent call is triggered.
Use this to confirm your API key is accepted and that your server can reach the API before going live. Also suitable for load balancer health checks and uptime monitors.
| Field | Type | Description |
|---|---|---|
| statusrequired | string | Always "ok" when the service is healthy |
| versionrequired | string | API version string |
curl https://YOUR_API_BASE_URL/v1/health \ -H "x-api-key: rxk_live_xxxx"
{
"status": "ok",
"version": "1.0.0"
}
Returns all agents the API key's tenant has access to. Use the agent_id values from this response in all subsequent calls.
| Field | Type | Description |
|---|---|---|
| agentsrequired | array | List of agent summaries |
| agents[].agent_idrequired | string | Stable identifier — use in all other calls |
| agents[].namerequired | string | Display name |
| agents[].statusrequired | enum | available or unavailable |
curl https://YOUR_API_BASE_URL/v1/agents \ -H "x-api-key: rxk_live_xxxx"
{
"agents": [
{
"agent_id": "siemens-reshape",
"name": "Siemens Industrial Automation Expert",
"description": "Expert in Siemens PLCs, drives...",
"status": "available"
}
]
}
Creates a new server-side session locked to (tenant, agent_id). The returned session_id must be passed on every /agent/respond call.
Conversation context is scoped to the session only — a new session always starts fresh. Pass user_id to associate the session with a user; cross-session memory (returning users getting personalised context) is coming in a future release.
| Field | Type | Description |
|---|---|---|
| agent_idrequired | string | Agent this session is locked to |
| user_idoptional | string | Your user identifier — reserved for cross-session memory (coming in a future release) |
| ttl_secondsoptional | integer | Idle TTL 60–86400s. Default: 3600 (1 hour). Resets on each turn. |
curl -X POST https://YOUR_API_BASE_URL/v1/sessions \ -H "x-api-key: rxk_live_xxxx" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "siemens-reshape", "user_id": "user_abc123", "ttl_seconds": 3600 }'
{
"session_id": "sess_01j9xkzp4f8q2w3e",
"agent_id": "siemens-reshape",
"expires_at": "2026-06-18T15:00:00Z"
}
Check whether a session is still alive before sending a message. Use this to proactively detect expiry and create a new session if needed — avoids a failed user-facing turn caused by an unexpected SESSION_EXPIRED on /agent/respond.
| Field | Type | Description |
|---|---|---|
| session_idrequired | string | Session ID to check |
| Field | Type | Description |
|---|---|---|
| session_idrequired | string | Echoed session identifier |
| agent_idrequired | string | Agent this session is locked to |
| expires_atrequired | datetime | ISO-8601 expiry timestamp |
| ttl_remaining_secondsrequired | integer | Seconds until session expires at time of call |
curl \ https://YOUR_API_BASE_URL/v1/sessions/sess_01j9xkzp4f8q2w3e \ -H "x-api-key: rxk_live_xxxx"
{
"session_id": "sess_01j9xkzp4f8q2w3e",
"agent_id": "siemens-reshape",
"expires_at": "2026-06-22T15:00:00Z",
"ttl_remaining_seconds": 843
}
Terminates a session immediately. Subsequent calls using this session_id return SESSION_NOT_FOUND.
Call this when the end-user explicitly ends a conversation or logs out. Sessions also expire automatically via the idle TTL.
| Field | Type | Description |
|---|---|---|
| session_idrequired | string | Session ID to terminate |
curl -X DELETE \ https://YOUR_API_BASE_URL/v1/sessions/sess_01j9xkzp4f8q2w3e \ -H "x-api-key: rxk_live_xxxx"
The core endpoint. Sends one turn of conversation to the agent and returns a structured AgentResult.
Triple validation enforced on every call: API key tenant + agent_id + session_id must all be consistent.
Widgets are absent in the initial release — field is simply not present. Coming in a future release.
| Field | Type | Description |
|---|---|---|
| session_idoptional | string | From POST /sessions. Omit on first turn — API auto-creates a session and returns session_id in the response. Required on all subsequent turns. |
| agent_idrequired | string | Must match session's agent |
| messagerequired | string | End-user's message. Max 32 768 chars. |
| streamoptional | boolean | Default false. Set true for SSE stream. |
| Field | Type | Notes |
|---|---|---|
| request_idrequired | string | Correlation ID for this turn |
| session_idoptional | string | Only present when the session was auto-created on this call (i.e. session_id was omitted from the request). Store this and pass it on all subsequent turns. |
| messagerequired | string | Agent's text response — always present |
| accuracyoptional | object | score (0–1) + label (high/medium/low) |
| reasoningoptional | object | summary — extended thinking trace |
| actionsoptional | array | Suggested next actions with label + prompt |
| widgetsoptional | array | Structured UI components. Absent in initial release — coming in a future version. |
| feedbackoptional | object | feedback_token for POST /feedback |
curl -X POST \ https://YOUR_API_BASE_URL/v1/agent/respond \ -H "x-api-key: rxk_live_xxxx" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "siemens-reshape", "message": "Best PLC for high-speed packaging?" }'
{
"request_id": "req_01j9xkzp4f8q2w3f",
"session_id": "sess_01j9xkzp4f8q2w3e", // auto-created — store and reuse
"message": "For high-speed packaging, I recommend the SIMATIC S7-1500 T-CPU...",
"accuracy": { "score": 0.92, "label": "high" },
"actions": [{ "label": "Compare with S7-300", "prompt": "Compare S7-1500 vs S7-300" }],
"feedback": { "feedback_token": "fb_tok_x9z2k1m" }
}
curl -X POST \ https://YOUR_API_BASE_URL/v1/agent/respond \ -H "x-api-key: rxk_live_xxxx" \ -H "Content-Type: application/json" \ -d '{ "session_id": "sess_01j9xkzp4f8q2w3e", "agent_id": "siemens-reshape", "message": "How does it compare to the S7-300?" }'
{
"code": "SESSION_EXPIRED",
"message": "Session has expired. Create a new session.",
"request_id": "req_01j9xkzp4f8q2w3g"
}
Optional endpoint. Captures end-user rating for a specific turn. The feedback_token from AgentResult.feedback binds the rating to the correct turn without exposing internal IDs.
Feedback is used for agent quality monitoring and continuous improvement.
| Field | Type | Description |
|---|---|---|
| feedback_tokenrequired | string | From AgentResult.feedback.feedback_token |
| ratingrequired | enum | thumbs_up or thumbs_down |
| commentoptional | string | End-user free text. Max 2048 chars. |
curl -X POST \ https://YOUR_API_BASE_URL/v1/feedback \ -H "x-api-key: rxk_live_xxxx" \ -H "Content-Type: application/json" \ -d '{ "feedback_token": "fb_tok_x9z2k1m", "rating": "thumbs_up", "comment": "Very accurate, exactly what I needed." }'