Record what the agent should have said

Stores a preference pair. When response_id is given, the customer message and the actual reply are read from the stored response rather than taken from the…

POST /api/v1/evals

cURL

curl --request POST \
  --url 'https://response.stateset.com/api/v1/evals' \
  --header "Authorization: Bearer $RESPONSECX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "response_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "preferred_output": "string",
  "user_message": "string",
  "non_preferred_output": "string",
  "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Two-Person Tent",
  "description": "Two-person tent, green — replacement for damaged pole set.",
  "reason_type": "string",
  "customer_impact": "string"
}'

201

{
  "object": "eval",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Two-Person Tent",
  "type": "standard",
  "status": "pending",
  "description": "Two-person tent, green — replacement for damaged pole set.",
  "user_message": "string",
  "preferred_output": "string",
  "non_preferred_output": "string",
  "reason_type": "string",
  "customer_impact": "string",
  "response_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ticket_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-08-31T14:22:05Z",
  "updated_at": "2026-08-31T14:22:05Z"
}

Stores a preference pair. When response_id is given, the customer message and the actual reply are read from the stored response rather than taken from the request, so the recorded pair is authentic.

Request body

CreateEval

response_id · string (uuid)

preferred_output · string · required

user_message · string

non_preferred_output · string

agent_id · string (uuid)

name · string

description · string

reason_type · string

customer_impact · string

Response

object

object · string · required

id · string (uuid) · required

name · string,null · required

From the stored eval_name.

type · string,null · required

Defaults to preference on create.

status · string,null · required

Defaults to pending on create.

description · string,null · required

user_message · string,null · required

The customer message to replay. Copied from the source response when response_id was supplied.

preferred_output · string,null · required

The reply the agent should have given.

non_preferred_output · string,null · required

The reply that was actually given. Copied from the source response when response_id was supplied.

reason_type · string,null · required

customer_impact · string,null · required

response_id · string,null (uuid) · required

agent_id · string,null (uuid) · required

ticket_id · string,null · required

Stored as a string; derived from the source response when not supplied.

created_at · string,null (date-time) · required

updated_at · string,null (date-time) · required

Status codes

Code	Meaning
201	The created eval. When response_id was supplied, user_message, non_preferred_output and ticket_id come from the stored response, not the request.
400	Invalid request. issues names the offending field(s).
401	Missing, invalid, or expired API key.
403	The key lacks a required scope.
404	Not found, or not in the organization that owns the key.
409	Conflict — either the creation ceiling was reached for this organization (agent_limit_reached), or a request with the same Idempotency-Key is still in flight (idempotency_in_progress); retry the latter after the first attempt settles.
422	The Idempotency-Key was already used with a DIFFERENT request body (idempotency_key_reused). Reuse a key only to retry the identical request.
429	Rate limit exceeded.

Access

Required scope	responses:write
Rate limit	30 requests per minute

cURL

curl --request POST \
  --url 'https://response.stateset.com/api/v1/evals' \
  --header "Authorization: Bearer $RESPONSECX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "response_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "preferred_output": "string",
  "user_message": "string",
  "non_preferred_output": "string",
  "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Two-Person Tent",
  "description": "Two-person tent, green — replacement for damaged pole set.",
  "reason_type": "string",
  "customer_impact": "string"
}'

201

{
  "object": "eval",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Two-Person Tent",
  "type": "standard",
  "status": "pending",
  "description": "Two-person tent, green — replacement for damaged pole set.",
  "user_message": "string",
  "preferred_output": "string",
  "non_preferred_output": "string",
  "reason_type": "string",
  "customer_impact": "string",
  "response_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ticket_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-08-31T14:22:05Z",
  "updated_at": "2026-08-31T14:22:05Z"
}