ReshapeX · RxCore

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.

Base URL: https://YOUR_API_BASE_URL/v1
Auth: x-api-key header
OpenAPI 3.1
Preview

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

Your Server
Holds API key
RxCore API
Auth + session
validation
ReshapeX Agent
Reasoning +
response generation
Knowledge Base
Product & domain
knowledge

Getting Started

Five steps to send your first message. Every step maps to an API call.

1
Get your API key from Reshape
Issued per tenant via the ReshapeX Deployment Admin screen. Store it server-side — never in a browser or mobile app.
2
Validate connectivity — GET /v1/health
Confirm your key is accepted and your server can reach the API before going live. Zero side effects.
3
Discover your agents — GET /v1/agents
Returns the agent_id values you'll use in all subsequent calls. Only agents your key is scoped to are returned.
4
Create a session — POST /v1/sessions
One session per conversation. Pass user_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.
5
Send turns — POST /v1/agent/respond
Pass session_id, agent_id, and message on every turn. The agent maintains conversation context. Repeat for each user message.
✕
End the conversation — DELETE /v1/sessions/{session_id}
Call on user logout or explicit conversation end. Sessions also expire automatically after the idle TTL (default 1 hour).

Authentication

Header
HTTP
x-api-key: rxk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Triple Validation

Every request to /agent/respond validates three things in sequence:

tenant
+
agent_id
+
session_id

A session created for agent A cannot be used to call agent B. Mismatch returns SESSION_TENANT_MISMATCH.

Server-to-server only. API keys must never be embedded in browser code or mobile apps. All requests must originate from your backend server.

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.

{
  "request_id": "req_01j9xkzp...", REQUIRED
  "message": "For high-speed packaging, I recommend...", REQUIRED
  "accuracy": { "score": 0.92, "label": "high" }, optional // only when agent produces confidence
  "reasoning": { "summary": "..." }, optional // agent reasoning trace, when available
  "actions": [ { "label": "Compare with S7-300", "prompt": "..." } ], optional
  "widgets": [ ... ], optional // future release
  "feedback": { "feedback_token": "fb_tok_x9z2k1m" } optional
}
Forward compatibility: Clients must ignore unknown fields. New optional fields may be added in minor versions without a breaking change.

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.

Chunk types
SSE stream
// 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":{...}}}
Unknown chunk types must be ignored. Reshape may add new chunk types in future versions. A robust client skips chunks whose type it doesn't recognise.

Error Codes

INVALID_API_KEY
Key doesn't exist, has been revoked, or is malformed.
API_KEY_SCOPE_MISMATCH
Key is valid but not scoped to the requested agent_id.
SESSION_EXPIRED
Idle TTL elapsed. Create a new session via POST /sessions.
SESSION_TENANT_MISMATCH
Triple validation failed — session belongs to a different tenant or agent.
SESSION_NOT_FOUND
Session ID doesn't exist or was deleted.
AGENT_NOT_FOUND
Agent ID not found or not accessible by this tenant.
AGENT_RUNTIME_UNAVAILABLE
Agent runtime is temporarily unavailable (e.g. cold-start or capacity issue). Retry with exponential back-off.
AGENT_RUNTIME_TIMEOUT
Agent did not return a response within the maximum allowed time. The request was not processed — safe to retry. If the problem persists, contact your Reshape account team.
RATE_LIMITED
Per-tenant rate limit exceeded. Back off and retry.
INVALID_REQUEST
Request body failed schema validation.
INTERNAL_ERROR
Unexpected server error. Include 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.

Current limits
Rate limit values are provisioned per tenant. Contact your Reshape account team for the limits that apply to your integration.
Retry guidance
Error codeRecommended 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.
System
GET /health Liveness check & API key validation ▶
Description

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.

Response fields
FieldTypeDescription
statusrequired string Always "ok" when the service is healthy
versionrequired string API version string
Responses
200Service healthy, API key valid
401Invalid or missing API key
503Service unavailable
Request
curl
curl https://YOUR_API_BASE_URL/v1/health \
  -H "x-api-key: rxk_live_xxxx"
Response
JSON
{
  "status": "ok",
  "version": "1.0.0"
}
Agents
GET /agents List available agents ▶
Description

Returns all agents the API key's tenant has access to. Use the agent_id values from this response in all subsequent calls.

Response fields
FieldTypeDescription
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
Responses
200OK — agent list returned
401Invalid or missing API key
500Internal error
Request
curl
curl https://YOUR_API_BASE_URL/v1/agents \
  -H "x-api-key: rxk_live_xxxx"
Response
JSON
{
  "agents": [
    {
      "agent_id": "siemens-reshape",
      "name": "Siemens Industrial Automation Expert",
      "description": "Expert in Siemens PLCs, drives...",
      "status": "available"
    }
  ]
}
Sessions
POST /sessions Create a session ▶
Description

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.

Request body
FieldTypeDescription
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.
Responses
201Session created
400Invalid request body
401Invalid or missing API key
404Agent not found or inaccessible
Request
curl
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
  }'
Response
JSON
{
  "session_id": "sess_01j9xkzp4f8q2w3e",
  "agent_id": "siemens-reshape",
  "expires_at": "2026-06-18T15:00:00Z"
}
GET /sessions/{session_id} Get session status ▶
Description

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.

Path parameter
FieldTypeDescription
session_idrequired string Session ID to check
Response fields
FieldTypeDescription
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
Responses
200Session is alive — status returned
401Invalid or missing API key
404Session not found or already expired
Request
curl
curl \
  https://YOUR_API_BASE_URL/v1/sessions/sess_01j9xkzp4f8q2w3e \
  -H "x-api-key: rxk_live_xxxx"
Response
JSON
{
  "session_id": "sess_01j9xkzp4f8q2w3e",
  "agent_id": "siemens-reshape",
  "expires_at": "2026-06-22T15:00:00Z",
  "ttl_remaining_seconds": 843
}
DEL /sessions/{session_id} Delete a session ▶
Description

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.

Path parameter
FieldTypeDescription
session_idrequired string Session ID to terminate
Responses
204Session deleted — no body
401Invalid or missing API key
404Session not found
Request
curl
curl -X DELETE \
  https://YOUR_API_BASE_URL/v1/sessions/sess_01j9xkzp4f8q2w3e \
  -H "x-api-key: rxk_live_xxxx"
Returns 204 No Content on success — no response body.
Agent
POST /agent/respond Send a message — get a structured response ▶
Description

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.

Request body
FieldTypeDescription
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.
Response — AgentResult
FieldTypeNotes
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
Responses
200OK — AgentResult or SSE stream
400Invalid request body
401Invalid or missing API key
404Agent or session not found
410Session expired — create a new session
429Rate limited
503Agent runtime unavailable or timed out — see error code
Request — first call (no session yet)
curl
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?"
  }'
Response — first call (session auto-created)
JSON
{
  "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" }
}
Request — subsequent turn (pass session_id)
curl
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?"
  }'
Session expired error
JSON · 410
{
  "code": "SESSION_EXPIRED",
  "message": "Session has expired. Create a new session.",
  "request_id": "req_01j9xkzp4f8q2w3g"
}
Feedback
POST /feedback Submit thumbs-up / thumbs-down for a turn ▶
Description

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.

Request body
FieldTypeDescription
feedback_tokenrequired string From AgentResult.feedback.feedback_token
ratingrequired enum thumbs_up or thumbs_down
commentoptional string End-user free text. Max 2048 chars.
Responses
204Feedback recorded — no response body
400Invalid request or expired token
401Invalid or missing API key
Request
curl
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."
  }'
Returns 204 No Content on success — no response body.