> ## 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.

# Response Public API (v1)

> The API-key-authenticated /api/v1 surface — agents, rules, functions, settings, knowledge, responses, and analytics.

# Response Public API (v1)

A public, API-key-authenticated REST surface for building and tuning ResponseCX agents
programmatically. It is the same surface the [remote MCP server](/stateset-response/response-mcp)
exposes as tools.

## Authentication

Pass an `rcx_` API key as a Bearer token:

```bash theme={null}
curl https://your-response-host/api/v1/agents \
  -H "Authorization: Bearer $RESPONSE_API_KEY"
```

Identity, organization, and scopes are derived **strictly from the key** — every route is
gated on scopes and rate-limited. Existing session auth still works and falls through the
guard.

### Scopes

| Scope             | Grants                                               |
| ----------------- | ---------------------------------------------------- |
| `agents:read`     | Read agents, settings, rules, functions              |
| `agents:write`    | Create and update agents, rules, functions, settings |
| `responses:read`  | Read responses                                       |
| `responses:write` | Write responses                                      |
| `knowledge:read`  | Read and search knowledge                            |
| `knowledge:write` | Add knowledge                                        |
| `analytics:read`  | Read analytics summaries                             |

## Endpoints

### Agents

| Method        | Path                            | Purpose                                        |
| ------------- | ------------------------------- | ---------------------------------------------- |
| `GET`         | `/api/v1/agents`                | List agents                                    |
| `POST`        | `/api/v1/agents`                | Create an agent                                |
| `GET`         | `/api/v1/agents/{id}`           | Get one agent                                  |
| `PATCH`       | `/api/v1/agents/{id}`           | Update an agent                                |
| `POST`        | `/api/v1/agents/provision`      | Build a complete agent in one atomic call      |
| `GET`/`PATCH` | `/api/v1/agents/{id}/settings`  | Read and configure model and behavior settings |
| `GET`/`POST`  | `/api/v1/agents/{id}/rules`     | Read back and add an agent's rules             |
| `GET`/`POST`  | `/api/v1/agents/{id}/functions` | Read back and add an agent's functions         |

### Rules and functions

| Method           | Path                     | Purpose                     |
| ---------------- | ------------------------ | --------------------------- |
| `PATCH`/`DELETE` | `/api/v1/rules/{id}`     | Update or retire a rule     |
| `PATCH`/`DELETE` | `/api/v1/functions/{id}` | Update or retire a function |

### Knowledge

| Method | Path                       | Purpose               |
| ------ | -------------------------- | --------------------- |
| `POST` | `/api/v1/knowledge`        | Add knowledge, scoped |
| `POST` | `/api/v1/knowledge/search` | Semantic search       |

### Responses and analytics

| Method | Path                        | Purpose                |
| ------ | --------------------------- | ---------------------- |
| `GET`  | `/api/v1/responses`         | List responses         |
| `GET`  | `/api/v1/responses/{id}`    | Get one response       |
| `GET`  | `/api/v1/analytics/summary` | Analytics summary      |
| `GET`  | `/api/v1/workspace`         | Describe the workspace |

## Provisioning an agent in one call

`POST /api/v1/agents/provision` creates an agent together with its settings, rules, functions,
and knowledge atomically — either the whole agent exists or none of it does. This is the path
to prefer when an external system or agent is building a ResponseCX agent from scratch, since
it avoids leaving a half-configured agent behind on a failed step.

## Validation errors that teach

Every route returns **per-field issues** rather than a single opaque message, so a caller —
especially an automated one — can correct the request without guessing:

```json theme={null}
{
  "error": "validation_failed",
  "issues": [
    { "path": "settings.model", "message": "unknown model 'gpt-9'" },
    { "path": "rules[0].condition", "message": "expected a vocabulary term" }
  ]
}
```

## Discovering the vocabulary

Rules and functions are written against a controlled vocabulary. Rather than guessing at the
grammar, call:

* `GET /api/v1/workspace` — what exists in this workspace.
* The `describe_vocabulary` tool or `vocabulary` resource on the
  [MCP server](/stateset-response/response-mcp) — the legal terms for rule conditions.

## Related

* [Response MCP Server](/stateset-response/response-mcp)
* [ResponseCX](/stateset-response/stateset-responsecx)