> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ResponseCX API

> Build and operate CX agents — 38 endpoints on response.stateset.com, generated from the spec the server publishes.

The ResponseCX public API builds and operates customer-experience agents: their rules, their
tools, the knowledge they answer from, and the record of what they actually said.

|          |                                                               |
| -------- | ------------------------------------------------------------- |
| Base URL | `https://response.stateset.com/api/v1`                        |
| Auth     | `Authorization: Bearer rcx_…`                                 |
| Spec     | `GET /api/v1/openapi` — the server publishes its own document |

<Note>
  This reference is generated from that document, so it matches the running service rather than a
  copy kept beside it. Every page names the scope a key needs and the endpoint's per-minute rate
  limit, both of which come from the spec.
</Note>

## Where to start

<CardGroup cols={2}>
  <Card title="Workspace" icon="compass" href="/api-reference/responsecx/workspace-list">
    One call that reports what exists and suggests a next action. Start here rather than guessing
    at the shape of an empty account.
  </Card>

  <Card title="Provision an agent" icon="wand-sparkles" href="/api-reference/responsecx/agents-provision-create">
    Settings, rules, functions and knowledge in a single atomic call.
  </Card>

  <Card title="Read real conversations" icon="messages-square" href="/api-reference/responsecx/conversations-list">
    What customers asked and how the agent answered — read these before changing an agent, and
    after, to check the change held.
  </Card>

  <Card title="Close the loop" icon="target" href="/api-reference/responsecx/evals-create">
    Record what the agent should have said. An eval becomes a regression case rather than a note.
  </Card>
</CardGroup>

## Your first call

Orientation before anything else — `workspace` reports what exists and what to do next, so you
are not guessing at the shape of an account you have not seen.

```bash cURL theme={null}
curl --request GET \
  --url 'https://response.stateset.com/api/v1/workspace' \
  --header 'Authorization: Bearer rcx_YOUR_API_KEY'
```

Creating an agent takes an idempotency key, so a retry after a timeout returns the first result
rather than a second agent:

```bash cURL theme={null}
curl --request POST \
  --url 'https://response.stateset.com/api/v1/agents' \
  --header 'Authorization: Bearer rcx_YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 4f1c2b90-first-agent' \
  --data '{"name": "Support", "type": "customer_service"}'
```

## The build → verify loop

The API is shaped around one cycle, and the endpoints are most useful in this order:

1. **Orient** — `GET /workspace` reports what is configured and what is missing.
2. **Build** — `POST /agents/provision`, or the individual rule, function and knowledge endpoints.
3. **Verify** — `POST /agents/{id}/evals/run` replays the suite against a change.
4. **Observe** — `GET /conversations` and `GET /analytics/agents` show what happened in production.
5. **Correct** — `POST /evals` records the reply that should have been sent, which feeds step 3.

<Tip>
  The six endpoints that create something — an agent, a provisioned agent, a rule, a function, an
  eval, a knowledge document — take an `Idempotency-Key` header. Retrying with the same key returns
  the original result rather than creating a second one. Updates and runs do not take it.
</Tip>

## Scopes

Every endpoint declares the scope its key must carry. Across the 38:

| Scope             | Endpoints |
| ----------------- | --------- |
| `agents:read`     | 11        |
| `agents:write`    | 10        |
| `responses:read`  | 6         |
| `knowledge:write` | 4         |
| `responses:write` | 3         |
| `analytics:read`  | 2         |
| `knowledge:read`  | 2         |

## Related

* [ResponseCX MCP server](/stateset-response/response-mcp) — the same surface as agent tools
* [StateSet ResponseCX](/stateset-response/responsecx-autonomy) — what the product does