# API: Agents

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/agents` | Agents: built-in ones and your organization's, with state, version, triggers, integrations and run counters | `agents:read` |
| GET | `/v1/policy-decisions` | Policy engine decisions on agent actions, newest first | `agents:read` |
| GET | `/v1/runs` | List runs, newest first | `agents:read` |
| POST | `/v1/runs` | Start an agent run | `agents:write` |
| GET | `/v1/runs/:id` | Get a run with its effect-tagged step trace | `agents:read` |
| POST | `/v1/runs/:id/approve` | Approve the run's pending action and resume it | `approvals:write` |
| POST | `/v1/runs/:id/cancel` | Cancel a run that hasn't finished | `agents:write` |
| POST | `/v1/runs/:id/reject` | Reject the run's pending action; the run ends | `approvals:write` |
| POST | `/v1/runs/:id/replay` | Start a new run with the same agent and input | `agents:write` |

## Examples

### GET /v1/agents

Agents: built-in ones and your organization's, with state, version, triggers, integrations and run counters

```bash
curl -s "https://api.closefinch.com/v1/agents" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/agents`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/policy-decisions

Policy engine decisions on agent actions, newest first

```bash
curl -s "https://api.closefinch.com/v1/policy-decisions" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/policy-decisions`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/runs

List runs, newest first

```bash
curl -s "https://api.closefinch.com/v1/runs" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/runs`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### POST /v1/runs

Start an agent run

```bash
curl -s -X POST "https://api.closefinch.com/v1/runs" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/runs`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### GET /v1/runs/$ID

Get a run with its effect-tagged step trace

```bash
curl -s "https://api.closefinch.com/v1/runs/$ID" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/runs/${id}`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### POST /v1/runs/$ID/cancel

Cancel a run that hasn't finished

```bash
curl -s -X POST "https://api.closefinch.com/v1/runs/$ID/cancel" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/runs/${id}/cancel`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### POST /v1/runs/$ID/replay

Start a new run with the same agent and input

```bash
curl -s -X POST "https://api.closefinch.com/v1/runs/$ID/replay" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/runs/${id}/replay`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

Request and response schemas: [https://www.closefinch.com/openapi.json](https://www.closefinch.com/openapi.json). All resources: [API reference](https://www.closefinch.com/docs/api).