Create Custom Agent V1

Create a custom agent. Configurations stick until deleted. Use PATCH to flip is_active rather than re-creating to preserve audit history.

POST /api/v1/custom-agents

cURL

curl --request POST \
  --url 'https://api.computer.stateset.app/api/v1/custom-agents' \
  --header "X-API-Key: $STATESET_COMPUTER_USE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Two-Person Tent",
  "description": "Two-person tent, green — replacement for damaged pole set.",
  "system_prompt_extension": "string",
  "agent_type": "custom",
  "skills": [
    "string"
  ],
  "tool_permissions": [
    "string"
  ],
  "default_params": {},
  "trigger_config": {}
}'

201

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Two-Person Tent",
  "description": "Two-person tent, green — replacement for damaged pole set.",
  "system_prompt_extension": "string",
  "agent_type": "string",
  "skills": [
    "string"
  ],
  "tool_permissions": [
    "string"
  ],
  "default_params": {},
  "trigger_config": {},
  "is_active": true,
  "is_sandbox": true,
  "created_at": "2026-08-31T14:22:05Z",
  "updated_at": "2026-08-31T14:22:05Z"
}

Create a custom agent.

Configurations stick until deleted. Use PATCH to flip is_active rather than re-creating to preserve audit history.

Request body

CustomAgentRequest

name · string · required

Human-readable agent name (≤128 chars).

description · string,null

Free-form description (≤4 KB). Surfaces in the dashboard list view.

system_prompt_extension · string,null

Text appended to the platform’s default system prompt for this agent’s runs (≤16 KB). Use to give the agent persistent persona or domain-specific instructions.

agent_type · string

Tag for this agent’s runs; default ‘custom’. Free-form.

skills · string[]

Skill IDs or names to register on each run (≤100 entries).

tool_permissions · string[]

Allow-list of tool names this agent may use; empty = full default tool set. Useful for sandboxing untrusted prompts.

default_params · object

Params merged into every /trigger call invoking this agent.

trigger_config · object

Optional trigger metadata — e.g. {type: 'scheduled', cron: '0 9 * * *'}. Free-form; the worker reads documented keys.

Response

CustomAgentSummary

id · string · required

name · string · required

description · string,null · required

system_prompt_extension · string,null · required

agent_type · string · required

skills · string[] · required

tool_permissions · string[] · required

default_params · object · required

trigger_config · object · required

is_active · boolean · required

is_sandbox · boolean · required

created_at · string · required

updated_at · string · required

Status codes

Code	Meaning
201	Successful Response
422	Validation Error

cURL

curl --request POST \
  --url 'https://api.computer.stateset.app/api/v1/custom-agents' \
  --header "X-API-Key: $STATESET_COMPUTER_USE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Two-Person Tent",
  "description": "Two-person tent, green — replacement for damaged pole set.",
  "system_prompt_extension": "string",
  "agent_type": "custom",
  "skills": [
    "string"
  ],
  "tool_permissions": [
    "string"
  ],
  "default_params": {},
  "trigger_config": {}
}'

201

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Two-Person Tent",
  "description": "Two-person tent, green — replacement for damaged pole set.",
  "system_prompt_extension": "string",
  "agent_type": "string",
  "skills": [
    "string"
  ],
  "tool_permissions": [
    "string"
  ],
  "default_params": {},
  "trigger_config": {},
  "is_active": true,
  "is_sandbox": true,
  "created_at": "2026-08-31T14:22:05Z",
  "updated_at": "2026-08-31T14:22:05Z"
}