Agent

GET/api/v1/agents

List_agents

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Query Parameters

q?string

Full-text search query applied to display name and description.

page?integer

1-indexed page number.

Formatint64

Range0 <= value

page_size?integer

Page size (max 100).

Formatint64

Range0 <= value

sort_by?string

Sort field (created_at, display_name, key).

sort_order?string

Sort order (asc or desc).

Value in

"asc"
"desc"

visibility?string

Filter by visibility (private, organization).

Value in

"private"
"organization"

status?string

Filter by status (active, disabled).

Value in

"active"
"disabled"

filter?array<string>

Additional filter expressions in the form field:operator:value.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/agents"

{  "agents": [    {      "agent_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "description": "string",      "display_name": "string",      "key": "string",      "org_id": "string",      "owner_id": "string",      "profile_url": "string",      "status": "active",      "updated_at": "2019-08-24T14:15:22Z",      "visibility": "private"    }  ],  "pagination": {    "has_more": true,    "page": 0,    "page_size": 0,    "total": 0  }}

POST/api/v1/agents

Create_agent

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

agent_toml*string

Raw agent.toml content (identity, tone, tools, skills, model, etc.)

compaction_toml?|

Raw compaction.toml content.

description*string

One-line description of what the agent does.

display_name*string

Human-readable display name.

intent_toml?|

Raw intent.toml content.

key*string

Agent key (slug format: lowercase alphanumeric + hyphens).

memory_toml?|

Raw memory.toml content.

org_id?|

Organization ID (required when visibility = organization).

procedures?|

Procedure runbooks by mode name.

profile_url?|

Profile image URL.

prompt_text*string

The system prompt text for the agent.

rag_toml?|

Raw rag.toml content.

shield_toml?|

Raw shield.toml content.

visibility?null|

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/agents" \  -H "Content-Type: application/json" \  -d '{    "agent_toml": "string",    "description": "string",    "display_name": "string",    "key": "string",    "prompt_text": "string"  }'

{  "agent_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "display_name": "string",  "key": "string"}

POST/api/v1/agents/resolve

Batch_resolve_agents

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

keys*array<string>

Agent keys to resolve in a single round-trip.

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/agents/resolve" \  -H "Content-Type: application/json" \  -d '{    "keys": [      "string"    ]  }'

{  "missing": [    "string"  ],  "resolved": [    {      "agent_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "description": "string",      "display_name": "string",      "key": "string",      "org_id": "string",      "owner_id": "string",      "profile_url": "string",      "status": "active",      "updated_at": "2019-08-24T14:15:22Z",      "visibility": "private",      "agent_toml": "string",      "compaction_toml": "string",      "intent_toml": "string",      "memory_toml": "string",      "procedures": null,      "prompt_text": "string",      "rag_toml": "string",      "shield_toml": "string"    }  ]}

GET/api/v1/agents/resolve/{key}

Resolve_agent

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

key*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/agents/resolve/string"

{  "agent_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "description": "string",  "display_name": "string",  "key": "string",  "org_id": "string",  "owner_id": "string",  "profile_url": "string",  "status": "active",  "updated_at": "2019-08-24T14:15:22Z",  "visibility": "private",  "agent_toml": "string",  "compaction_toml": "string",  "intent_toml": "string",  "memory_toml": "string",  "procedures": null,  "prompt_text": "string",  "rag_toml": "string",  "shield_toml": "string"}

GET/api/v1/agents/{agent_id}

Get_agent

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

agent_id*string

Query Parameters

view?string

Response detail level: "full" (default, includes prompt/TOML payloads) or "summary" (metadata only).

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/agents/string"

{  "agent_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "description": "string",  "display_name": "string",  "key": "string",  "org_id": "string",  "owner_id": "string",  "profile_url": "string",  "status": "active",  "updated_at": "2019-08-24T14:15:22Z",  "visibility": "private",  "agent_toml": "string",  "compaction_toml": "string",  "intent_toml": "string",  "memory_toml": "string",  "procedures": null,  "prompt_text": "string",  "rag_toml": "string",  "shield_toml": "string"}

DELETE/api/v1/agents/{agent_id}

Delete_agent

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

agent_id*string

Response Body

curl -X DELETE "https://example.com/api/v1/agents/string"

Empty

PUT/api/v1/agents/{agent_id}

Update_agent

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

agent_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

agent_toml?|

Updated agent.toml content.

compaction_toml?|

Updated compaction.toml content.

description?|

Updated description.

display_name?|

Updated display name.

intent_toml?|

Updated intent.toml content.

memory_toml?|

Updated memory.toml content.

org_id?|

Updated organization ID.

procedures?|

Updated procedure runbooks by mode name.

profile_url?|

Updated profile image URL.

prompt_text?|

Updated system prompt text.

rag_toml?|

Updated rag.toml content.

shield_toml?|

Updated shield.toml content.

status?null|

visibility?null|

Response Body

`application/json`

curl -X PUT "https://example.com/api/v1/agents/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "agent_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "description": "string",  "display_name": "string",  "key": "string",  "org_id": "string",  "owner_id": "string",  "profile_url": "string",  "status": "active",  "updated_at": "2019-08-24T14:15:22Z",  "visibility": "private",  "agent_toml": "string",  "compaction_toml": "string",  "intent_toml": "string",  "memory_toml": "string",  "procedures": null,  "prompt_text": "string",  "rag_toml": "string",  "shield_toml": "string"}

Agent

200application/json

201application/json

400

409

200application/json

400

200application/json

404

200application/json

404

204

403

404

200application/json

403

404

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`