RxCore Agent API — Reference

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://api.reshapex.ai/v1

Auth: x-api-key header

OpenAPI 3.1

M1 Draft — June 26

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

Customer Server

Holds API key

RxCore API

Auth + Session
validation

AgentCore Runtime

AWS Bedrock
LangGraph agent

RAG / KB

Product knowledge
vector search

Getting Started

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

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.

Validate connectivity — GET /v1/health

Confirm your key is accepted and your server can reach the API before going live. Zero side effects.

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.

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. Store the returned session_id server-side.

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.

Response Envelope

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 // extended thinking models only

"actions": [ { "label": "Compare with S7-300", "prompt": "..." } ], optional

"widgets": [ ... ], optional // M3 scope, absent in M2

"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 (M3 scope)
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

AgentCore runtime has no deployed endpoint (migration in progress).

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.

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

Field	Type	Description
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://api.reshapex.ai/v1/health \
  -H "x-api-key: rxk_live_xxxx"

Response

JSON

{
  "success": true,
  "result": {
    "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

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`

Responses

200OK — agent list returned

401Invalid or missing API key

500Internal error

Request

curl

curl https://api.reshapex.ai/v1/agents \
  -H "x-api-key: rxk_live_xxxx"

Response

JSON

{
  "success": true,
  "result": {
    "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.

If user_id is provided, the agent carries persistent memory across sessions for that user — returning users get personalised context.

Request body

Field	Type	Description
agent_idrequired	string	Agent this session is locked to
user_idoptional	string	Your user identifier — enables cross-session memory
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://api.reshapex.ai/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

{
  "success": true,
  "result": {
    "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

Field	Type	Description
session_idrequired	string	Session ID to check

Response fields

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

Responses

200Session is alive — status returned

401Invalid or missing API key

404Session not found or already expired

Request

curl

curl \
  https://api.reshapex.ai/v1/sessions/sess_01j9xkzp4f8q2w3e \
  -H "x-api-key: rxk_live_xxxx"

Response

JSON

{
  "success": true,
  "result": {
    "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

Field	Type	Description
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://api.reshapex.ai/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 (M3) are absent in M2 Q&A responses — field is simply not present.

Request body

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.

Response — AgentResult

Field	Type	Notes
request_idrequired	string	Correlation ID for this turn
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	M3 Absent in M2
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

Request (non-streaming)

curl

curl -X POST \
  https://api.reshapex.ai/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": "Best PLC for high-speed packaging?"
  }'

Response

JSON

{
  "success": true,
  "result": {
    "request_id": "req_01j9xkzp4f8q2w3f",
    "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 for packaging"
      }
    ],
    "feedback": {
      "feedback_token": "fb_tok_x9z2k1m"
    }
  }
}

Session expired error

JSON · 410

{
  "success": false,
  "error": {
    "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

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.

Responses

200Feedback recorded

400Invalid request or expired token

401Invalid or missing API key

Request

curl

curl -X POST \
  https://api.reshapex.ai/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."
  }'

Response

JSON

{
  "success": true
}