Docs — API Reference/docs/api-reference/agents
Agents
An agent is a saved configuration — model, tools, scopes, approval policy — that you execute repeatedly. Executions are ordinary runs and appear in /v1/runs with full traces; the agent resource is the reusable definition.
[ 01 ]post — /v1/agents
POST
/v1/agentsCreate an agent. Tools and approval gates are declared here, once, not per execution.
| param | type | req | description |
|---|---|---|---|
| name | string | required | Unique name within the project. |
| model | string | required | Usually "y0-agent". Snapshots allowed. |
| instructions | string | required | Standing instructions prepended to every execution. |
| tools | string[] | required | Tool ids the agent may call, e.g. ["email.send", "finance.read"]. |
| approval | object | optional | { required_for: string[] } — tools that halt for human sign-off. |
| max_steps | integer | optional | Default ceiling for executions, 1–16. Defaults to 8. |
[ request ]POST
{
"name": "invoice-chaser",
"model": "y0-agent",
"instructions": "Chase unpaid invoices politely but firmly.",
"tools": ["email.send", "finance.read"],
"approval": { "required_for": ["email.send"] },
"max_steps": 8
}[ response ]200 ok
{
"id": "agt_19c4e2b7",
"object": "agent",
"name": "invoice-chaser",
"model": "y0-agent",
"tools": ["email.send", "finance.read"],
"approval": { "required_for": ["email.send"] },
"created_at": "2026-06-11T07:02:11Z"
}[ 02 ]post — /v1/agents/:id/run
POST
/v1/agents/:id/runExecute the agent. Returns a run; status "awaiting_approval" if a gated tool is reached.
| param | type | req | description |
|---|---|---|---|
| id | string | required | Agent identifier. Path parameter. |
| prompt | string | required | The task for this execution. |
| max_steps | integer | optional | Override the agent's default ceiling for this execution. |
[ request ]POST
{
"prompt": "Chase the three unpaid invoices over 30 days."
}[ response ]200 ok
{
"id": "run_9b11d0a3",
"object": "run",
"agent": "agt_19c4e2b7",
"status": "awaiting_approval",
"pending_actions": [
{ "id": "act_01", "tool": "email.send", "preview": "To: meridian@…" }
]
}[ 03 ]post — /v1/runs/:id/approve
POST
/v1/runs/:id/approveApprove (or reject) pending gated actions; the run resumes immediately.
| param | type | req | description |
|---|---|---|---|
| id | string | required | Run identifier. Path parameter. |
| action_ids | string[] | required | Pending action ids to approve. |
| reject | boolean | optional | Set true to reject instead; the run completes without acting. |
[ request ]POST
{
"action_ids": ["act_01"]
}[ response ]200 ok
{
"id": "run_9b11d0a3",
"object": "run",
"status": "running",
"approved_actions": ["act_01"]
}[ 04 ]get — /v1/agents/:id/runs
GET
/v1/agents/:id/runsList an agent's execution history, newest first.
| param | type | req | description |
|---|---|---|---|
| id | string | required | Agent identifier. Path parameter. |
| limit | integer | optional | 1–100, default 20. Query parameter. |
[ response ]200 ok
{
"object": "list",
"data": [
{ "id": "run_9b11d0a3", "status": "completed", "steps_used": 6 },
{ "id": "run_8a04c771", "status": "completed", "steps_used": 5 }
],
"has_more": false
}More resources