StateSet API Docs

Prefer the app? Sign up and test your first support agent, then return here for REST automation. Create a ResponseCX agent, read back its configuration, and learn how to activate and deactivate it. Every request uses https://response.stateset.com/api/v1.

Looking for orders, inventory or payments? Start with the embedded commerce engine. For other services, use the API directory.

Before you start

You need:

A ResponseCX workspace and an API key from Settings → API keys, with agents:read and agents:write.
A terminal with Bash, curl 7.76 or later, and jq for reading JSON.
The same terminal session for the commands below so environment variables remain available.

curl --version
jq --version
export RESPONSECX_API_KEY="rcx_your_key"
export RESPONSECX_API_URL="https://response.stateset.com/api/v1"

If you need workspace access, start with brand onboarding or contact the team. The examples use --fail-with-body so an HTTP error exits unsuccessfully while preserving the server’s explanation.

Step 1 — Check your key

List the agents your key can access:

curl --silent --show-error --fail-with-body \
  "$RESPONSECX_API_URL/agents" \
  --header "Authorization: Bearer $RESPONSECX_API_KEY"

A new workspace has an empty data array. A workspace with existing agents returns those agents. This is an abbreviated empty response:

{
  "object": "list",
  "data": [],
  "has_more": false
}

Success: HTTP 200 and a JSON list. Resolve a 401 or 403 using troubleshooting before continuing.

Step 2 — Create an inactive agent

Choose a key for this creation attempt. Keep the same key and request body if you retry it; choose a new key when you intentionally create another agent.

export AGENT_CREATE_KEY="docs-support-agent-1"

curl --silent --show-error --fail-with-body \
  --request POST "$RESPONSECX_API_URL/agents" \
  --header "Authorization: Bearer $RESPONSECX_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $AGENT_CREATE_KEY" \
  --data '{
    "name": "Quickstart Support",
    "type": "customer_service",
    "role": "Customer Support Specialist",
    "instructions": "Help customers with orders and returns. Ask for missing information. Escalate when you cannot verify an answer.",
    "activated": false
  }' \
  --output agent.json &&
  jq . agent.json

Success: the initial creation returns HTTP 201 with an id and activated: false. The response is saved in agent.json. It includes fields such as:

{
  "object": "agent",
  "id": "3f9c2a10-7b4e-4d8a-9c1e-5a2b8d7f6e01",
  "name": "Quickstart Support",
  "type": "customer_service",
  "activated": false
}

Save your returned ID, then verify that it is present:

AGENT_ID=$(jq -er '.id | select(type == "string" and length > 0)' agent.json) &&
  export AGENT_ID &&
  printf 'Created agent: %s\n' "$AGENT_ID"

If extraction fails, inspect agent.json for the error and stop here. Do not substitute the illustrative ID above. The create endpoint documents the full request, response and idempotency errors.

Step 3 — Read back what you created

curl --silent --show-error --fail-with-body \
  "$RESPONSECX_API_URL/agents/${AGENT_ID:?Create an agent and save its ID first}" \
  --header "Authorization: Bearer $RESPONSECX_API_KEY"

Success: the response ID matches AGENT_ID, the instructions match your request, and activated is false. You have created a configuration; this walkthrough has not yet connected a customer channel or sent a customer message. Ask the workspace what to configure next:

curl --silent --show-error --fail-with-body \
  "$RESPONSECX_API_URL/workspace" \
  --header "Authorization: Bearer $RESPONSECX_API_KEY"

Inspect agents for your new agent and next_action for the workspace’s suggested next step. The workspace endpoint also reports rule, function and eval counts for each agent.

Step 4 — Activate when ready

Use the links below to add knowledge, tools, rules and evals appropriate to your use case. When the configuration is ready, activate your agent:

curl --silent --show-error --fail-with-body \
  --request PATCH \
  "$RESPONSECX_API_URL/agents/${AGENT_ID:?Create an agent and save its ID first}" \
  --header "Authorization: Bearer $RESPONSECX_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "activated": true }'

Success: HTTP 200 with the same agent ID and activated: true. Activation changes the agent’s state; use the ResponseCX platform guide to continue with channel setup and operation.

Deactivate your quickstart agent

When you finish experimenting, set activated back to false. This keeps its configuration available for further testing:

curl --silent --show-error --fail-with-body \
  --request PATCH \
  "$RESPONSECX_API_URL/agents/${AGENT_ID:?Create an agent and save its ID first}" \
  --header "Authorization: Bearer $RESPONSECX_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "activated": false }'

Next steps

Add knowledge

Give your agent FAQs, policies and product information.

Connect a tool

Configure a function for an operation such as looking up an order.

Add rules

Define the behavior and escalation rules for your use case.

Create an eval

Record expected behavior so you can check it after configuration changes.

Troubleshooting

Symptom	What it means	What to do
`401 Unauthorized`	Missing, invalid or expired key	Check the environment variable and the `Authorization: Bearer` header
`403 Forbidden`	Key lacks the endpoint’s scope	Reads need `agents:read`; creating and updating need `agents:write`
`400` with `issues`	Invalid request fields	Read the field errors; provide a nonempty `name` and the documented agent `type`
`404` reading or updating an agent	ID is missing or belongs to another organization	Use the ID from your successful create response and the same workspace key
`409 agent_limit_reached`	Workspace has reached its creation limit	Inspect existing agents and contact your workspace administrator
`409 idempotency_in_progress`	A request with this key is still running	Wait for it to settle before retrying with the same key and body
`422 idempotency_key_reused`	The same key was used with a different body	Restore the original body for a retry; choose a new key for a new creation
`429 Too Many Requests`	Endpoint rate limit reached	Wait before retrying; reuse the creation key and body
`jq` fails to extract an ID	`agent.json` does not contain a successful agent response	Inspect the response and resolve its error before continuing

Check whether the key exists without printing its value:

if [ -n "${RESPONSECX_API_KEY:-}" ]; then
  printf 'RESPONSECX_API_KEY is set\n'
else
  printf 'Set RESPONSECX_API_KEY in this terminal\n'
fi

Still stuck? Use the support checklist to share the method, path, status code and a redacted response.

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

ResponseCX Quickstart

Before you start

Step 1 — Check your key

Step 2 — Create an inactive agent

Step 3 — Read back what you created

Step 4 — Activate when ready

Deactivate your quickstart agent

Next steps

Add knowledge

Connect a tool

Add rules

Create an eval

Troubleshooting

​Before you start

​Step 1 — Check your key

​Step 2 — Create an inactive agent

​Step 3 — Read back what you created

​Step 4 — Activate when ready

​Deactivate your quickstart agent

​Next steps

Add knowledge

Connect a tool

Add rules

Create an eval

​Troubleshooting

Before you start

Step 1 — Check your key

Step 2 — Create an inactive agent

Step 3 — Read back what you created

Step 4 — Activate when ready

Deactivate your quickstart agent

Next steps

Troubleshooting