StateSet API Docs

Start with one service and a request whose result you can inspect. Once authentication and read access work, follow that service’s guide to create and update resources. For a complete local starting point, use Your First Operation. It creates a known order and stock fixture, verifies it from a second process, and generates the configuration and task prompt for an AI agent to inspect those same records.

Choose your interface

You want to	Use	Setup
Operate commerce data inside your application	Embedded iCommerce library	Embedded engine and language bindings
Call a service from your backend	REST	API directory for the host, header and key
Give an AI agent tools	MCP	MCP servers for service-specific connection settings
Work through commerce tasks in a terminal	iCommerce CLI	CLI quickstart

Each service has its own API contract. Use the endpoint’s request body and authentication header; the embedded library’s methods and objects are a separate interface.

Make a first request from your application

The examples below read the ResponseCX workspace. They use standard HTTP libraries and need a ResponseCX API key with agents:read. Create a key in Settings → API keys and export it in the terminal that will run your application:

export RESPONSECX_API_KEY="rcx_your_key"

JavaScript
Python
curl

Use Node.js 18 or later. Save this as workspace.mjs and run node workspace.mjs.

const apiKey = process.env.RESPONSECX_API_KEY;
if (!apiKey) throw new Error('Set RESPONSECX_API_KEY first');

const response = await fetch('https://response.stateset.com/api/v1/workspace', {
  headers: { Authorization: `Bearer ${apiKey}` },
  signal: AbortSignal.timeout(10000),
});
const body = await response.text();
if (!response.ok) {
  throw new Error(`ResponseCX returned HTTP ${response.status}: ${body}`);
}

const workspace = JSON.parse(body);
console.log('Agents:', workspace.agent_count);
console.log('Next action:', workspace.next_action);

Save this as workspace.py and run python3 workspace.py. No third-party packages are required.

import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("RESPONSECX_API_KEY")
if not api_key:
    raise SystemExit("Set RESPONSECX_API_KEY first")

request = urllib.request.Request(
    "https://response.stateset.com/api/v1/workspace",
    headers={"Authorization": f"Bearer {api_key}"},
)
try:
    with urllib.request.urlopen(request, timeout=10) as response:
        workspace = json.load(response)
except urllib.error.HTTPError as error:
    detail = error.read().decode("utf-8", errors="replace")
    raise SystemExit(f"ResponseCX returned HTTP {error.code}: {detail}")
except urllib.error.URLError as error:
    raise SystemExit(f"Could not reach ResponseCX: {error.reason}")

print("Agents:", workspace["agent_count"])
print("Next action:", workspace["next_action"])

curl --silent --show-error --fail-with-body \
  https://response.stateset.com/api/v1/workspace \
  --header "Authorization: Bearer $RESPONSECX_API_KEY"

--fail-with-body requires curl 7.76 or later. It preserves the error body and returns a nonzero exit code when the server responds with an HTTP error.

Success: the response includes agent_count, an agents array, and next_action. Counts and suggestions depend on your workspace. See the workspace contract for the complete response, then follow the ResponseCX quickstart to create an agent.

Build your first write

Read the endpoint’s Request body, Access, and Status codes sections.
Create one resource and save its returned ID. Use that ID in later requests.
Read it back and verify the fields you changed.
Where the endpoint supports idempotency, save one key per intended operation and reuse it with the same payload after a timeout. Changing the payload requires a new operation and key.
Follow the service’s activation or deployment steps after configuration is complete.

For ResponseCX, create an agent supports an Idempotency-Key; update an agent has a different contract. Check support per endpoint before building a general retry wrapper.

Handle failures deliberately

Result	What to check	Next step
`400` or `422`	Response body and the endpoint’s schema	Correct the named field or conflict before resubmitting
`401`	Host, authentication header and exported credential	Correct the credential; keep API keys in your backend
`403`	Endpoint scope and organization access	Use a key authorized for this operation
`404`	Base URL, path prefix and resource ID	Verify all three against the same service and workspace
`409`	Service-specific error code	Inspect the conflict; it may require a different action rather than a retry
`429`	Rate-limit information in the response	Wait before retrying and preserve the operation’s idempotency key
Timeout or `5xx`	Host status and whether a write completed	Read the resource or use the endpoint’s documented replay behavior

Error bodies vary by service. The cross-engine error guide shows which field to parse; the support checklist lists the information needed to investigate a failing request. The error-handling guide adds a runnable example and explains how to distinguish a retryable failure from an unresolved write or business rejection.

Follow a complete integration

For local commerce, start with the customer workflow, then run the integration test suite to verify stock and retry behavior in isolated databases.

Customer support agent

Create and inspect a ResponseCX agent, then add knowledge, rules and tools.

System integration

Connect Shopify and NetSuite and inspect a sync run.

Durable automation

Configure, start and inspect a workflow through the Temporal Engine.

Policy-controlled action

Evaluate a refund policy and verify the result before executing the action.

Last modified on September 20, 2026

Get started

Build your first integration

Operate and improve

Resources and support

Platform

Using the APIs

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce Engine

StateSet iCommerce EDI Engine

StateSet Mail

StateSet iCommerce Voice Engine

StateSet iCommerce NSR Engine

AI Agents

StateSet Agents

StateSet iCommerce Sandbox Engine

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Apps & Consoles

Tools

Developer Guide

Choose your interface

Make a first request from your application

Build your first write

Handle failures deliberately

Follow a complete integration

Customer support agent

System integration

Durable automation

Policy-controlled action

​Choose your interface

​Make a first request from your application

​Build your first write

​Handle failures deliberately

​Follow a complete integration

Customer support agent

System integration

Durable automation

Policy-controlled action

Choose your interface

Make a first request from your application

Build your first write

Handle failures deliberately

Follow a complete integration