Agents

An agent is a saved configuration: model, instructions, and tools. It does not run on its own; a session uses it. Each session copies the agent’s settings when it is created, so updating an agent affects only sessions created afterwards. Paths are relative to /v1; see the overview for authentication.

Method	Path	Purpose / response
`GET`	`/agents`	List · `SyncCursorPage[Agent]`
`POST`	`/agents`	Create · `Agent`
`DELETE`	`/agents/{agent_id}`	Delete · `AgentDeleted`
`GET`	`/agents/{agent_id}`	Get · `Agent`
`POST`	`/agents/{agent_id}`	Update · `Agent`

POST /agents requires model. Optional fields:

Field	Meaning
`name`	A display name
`instructions`	The system instructions the model follows
`tools`	Function, MCP, and other tool definitions; see function tools and MCP
`multi_agent`	`{"enabled": true, "max_concurrent_subagents": n}` to allow subagents
`reasoning`, `text`, `service_tier`	Model settings; support varies by provider
`metadata`	Your own key-value labels

POST /agents/{agent_id} updates only the fields you send. model is orca/openrouter/<OpenRouter id> for Orca credit or <provider>/<id> with your own key; any other name is rejected with HTTP 400 on model. See models and provider keys.

curl -X POST "$BASE_URL/agents" \
  -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' \
  -d '{"model":"orca/openrouter/your-openrouter-model-id","name":"Research helper","instructions":"Be concise."}'
curl -H "Authorization: Bearer $API_KEY" "$BASE_URL/agents?limit=20"
curl -X POST "$BASE_URL/agents/$AGENT_ID" \
  -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' \
  -d '{"instructions":"Cite sources."}'

List accepts after, limit, and order (asc or desc). Delete returns a deletion object. See Sessions to run an agent.

​Agents

Agents