Create an agent

The created agent

POST /api/v1/agents

cURL

curl --request POST \
  --url 'https://response.stateset.com/api/v1/agents' \
  --header "Authorization: Bearer $RESPONSECX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Two-Person Tent",
  "type": "standard",
  "description": "Two-person tent, green — replacement for damaged pole set.",
  "instructions": "Two-person tent, green — replacement for damaged pole set.",
  "goal": "string",
  "role": "string",
  "activated": true
}'

201

{
  "object": "string",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Two-Person Tent",
  "type": "standard",
  "description": "Two-person tent, green — replacement for damaged pole set.",
  "activated": true,
  "goal": "string",
  "role": "string",
  "updated_at": "2026-08-31T14:22:05Z",
  "instructions": "Two-person tent, green — replacement for damaged pole set.",
  "settings": {
    "object": "string",
    "configured": true
  }
}

Request body

CreateAgent

name · string · required

type · string · required

One of: assistant, customer_service, sales.

description · string

instructions · string

The system prompt / persona.

goal · string

role · string

activated · boolean

Response

Agent

object · string

id · string

name · string,null

type · string,null

description · string,null

activated · boolean

goal · string,null

role · string,null

updated_at · string,null

instructions · string,null

Present on single-agent reads and writes only.

settings · AgentSettingsOut

Show AgentSettingsOut

object · string

configured · boolean

False when no settings row exists yet (fields are all null).

Status codes

Code	Meaning
201	The created agent
400	Invalid request. issues names the offending field(s).
401	Missing, invalid, or expired API key.
403	The key lacks a required scope.
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	agents:write
Rate limit	30 requests per minute

cURL

curl --request POST \
  --url 'https://response.stateset.com/api/v1/agents' \
  --header "Authorization: Bearer $RESPONSECX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Two-Person Tent",
  "type": "standard",
  "description": "Two-person tent, green — replacement for damaged pole set.",
  "instructions": "Two-person tent, green — replacement for damaged pole set.",
  "goal": "string",
  "role": "string",
  "activated": true
}'

201

{
  "object": "string",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Two-Person Tent",
  "type": "standard",
  "description": "Two-person tent, green — replacement for damaged pole set.",
  "activated": true,
  "goal": "string",
  "role": "string",
  "updated_at": "2026-08-31T14:22:05Z",
  "instructions": "Two-person tent, green — replacement for damaged pole set.",
  "settings": {
    "object": "string",
    "configured": true
  }
}