> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent API

> Trigger Kapso Agent runs, inspect sessions, handle approvals, and receive lifecycle webhooks from your own code.

Trigger agent runs through the Platform API with your project API key. Runs execute asynchronously: create a run, then poll it or receive lifecycle events through [project webhooks](/docs/platform/webhooks/project-webhooks#kapso-agent-run-events).

Base URL: `https://api.kapso.ai/platform/v1`. Authenticate with the `X-API-Key` header. Full endpoint reference: [Kapso Agent API](/api/platform/v1/kapso-agent/agent-runs/create-a-run).

## List modes

```bash theme={null}
curl "https://api.kapso.ai/platform/v1/kapso-agent/modes" \
  -H "X-API-Key: YOUR_API_KEY"
```

Returns every mode. Only modes whose `available_invocations` includes `api` accept runs: built-in modes with the API trigger enabled, and [custom modes](/docs/kapso-agent/modes) with the `api` surface. Get one mode with `GET /kapso-agent/modes/:mode`.

## List sessions

List the sessions for a built-in or custom mode:

```bash theme={null}
curl "https://api.kapso.ai/platform/v1/kapso-agent/modes/api/sessions?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"
```

Sessions are ordered by most recent activity. Results include only API runs created with the same API key.

```json theme={null}
{
  "data": [
    {
      "conversation_id": "880e8400-e29b-41d4-a716-446655440003",
      "title": "Webhook delivery investigation",
      "status": "active",
      "created_at": "2026-08-21T14:30:00Z",
      "run_count": 3,
      "latest_run": {
        "run_id": "990e8400-e29b-41d4-a716-446655440004",
        "status": "completed",
        "created_at": "2026-08-21T14:35:00Z"
      },
      "last_activity_at": "2026-08-21T14:35:00Z"
    }
  ],
  "paging": {
    "next": "NEXT_CURSOR",
    "previous": null,
    "cursors": {
      "before": "PREVIOUS_CURSOR",
      "after": "NEXT_CURSOR"
    }
  }
}
```

`limit` defaults to 20 and has a maximum of 100. Pass `paging.next` as `after` to get the next page.

## Get a session

Get a session and its runs:

```bash theme={null}
curl "https://api.kapso.ai/platform/v1/kapso-agent/sessions/CONVERSATION_ID?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"
```

The response contains the session in `data.session` and its newest API runs in `data.runs`. Pagination applies only to the runs.

The session-level `run_count` and `latest_run` describe the full session, not only the current page.

Session history omits the `result` for each run. Get a run by its `run_id` when you need the completed result.

## Create a run

```bash theme={null}
curl -X POST "https://api.kapso.ai/platform/v1/kapso-agent/runs" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "api",
    "input": { "prompt": "Inspect the failed webhook delivery from this morning" },
    "metadata": { "ticket_id": "T-1234" }
  }'
```

Response (`202 Accepted`):

```json theme={null}
{
  "data": {
    "run_id": "990e8400-e29b-41d4-a716-446655440004",
    "conversation_id": "880e8400-e29b-41d4-a716-446655440003",
    "status": "queued",
    "mode": "api",
    "kind": "ask",
    "prompt": "Inspect the failed webhook delivery from this morning",
    "provider_model": "gpt-5.5",
    "reasoning_effort": "medium",
    "error_message": null,
    "ai_cost_microdollars": 0,
    "result": null,
    "pending_approval": null,
    "created_at": "2026-08-21T14:30:00Z",
    "started_at": null,
    "paused_at": null,
    "finished_at": null,
    "status_url": "/platform/v1/kapso-agent/runs/990e8400-e29b-41d4-a716-446655440004"
  }
}
```

* `input.prompt` is required for the generic trigger. `findings-investigator` uses an optional `input.finding_id` instead - without it, the run investigates the next eligible finding - and doesn't accept `conversation_id`.
* Triggering a mode that doesn't accept API runs returns `422`.
* Pass `conversation_id` to continue an existing session. It only works for sessions created with the same API key and the same mode.
* `metadata` is stored on the run and echoed back in webhooks.
* Requests are not idempotent - repeating one creates a new run.
* There's no model parameter. Runs use the model configured for the mode, or the project default.

## Poll a run

```bash theme={null}
curl "https://api.kapso.ai/platform/v1/kapso-agent/runs/RUN_ID" \
  -H "X-API-Key: YOUR_API_KEY"
```

Statuses: `queued`, `running`, `paused`, `waiting_for_approval`, `completed`, `failed`, `cancelled`.

A completed run includes a `result`:

```json theme={null}
{
  "result": {
    "type": "message",
    "message_id": "770e8400-e29b-41d4-a716-446655440002",
    "content": "The delivery failed with a 401..."
  }
}
```

Only runs created via the API with the same API key can be retrieved or controlled. Anything else returns `404`.

## Control a run

```bash theme={null}
curl -X POST "https://api.kapso.ai/platform/v1/kapso-agent/runs/RUN_ID/cancel" \
  -H "X-API-Key: YOUR_API_KEY"
```

`POST /kapso-agent/runs/:id/pause`, `/resume`, and `/cancel`. Invalid transitions (for example, cancelling a completed run) return `409`.

## Approvals

When a run needs approval its status becomes `waiting_for_approval` and `pending_approval` is set:

```json theme={null}
{
  "pending_approval": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "status": "pending",
    "tool_name": "send_whatsapp_message",
    "parameters": { "to": "+15551234567" },
    "created_at": "2026-08-21T14:31:00Z"
  }
}
```

Approve or reject:

```bash theme={null}
curl -X POST "https://api.kapso.ai/platform/v1/kapso-agent/runs/RUN_ID/approvals/APPROVAL_ID/approve" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Webhooks

Subscribe to [Kapso Agent run events](/docs/platform/webhooks/project-webhooks#kapso-agent-run-events) instead of polling:

* `kapso_agent.run.approval_required`
* `kapso_agent.run.completed`
* `kapso_agent.run.failed`
* `kapso_agent.run.cancelled`

These fire only for runs triggered through the API. Dashboard and Slack runs don't emit them.

```json theme={null}
{
  "id": "3c0f1a5b9d8e7f6a4b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a",
  "event": "kapso_agent.run.completed",
  "created_at": "2026-08-21T14:35:00Z",
  "data": {
    "run_id": "990e8400-e29b-41d4-a716-446655440004",
    "session_id": "880e8400-e29b-41d4-a716-446655440003",
    "status": "completed",
    "agent": { "type": "mode", "id": "api" },
    "result": { "type": "message", "content": "..." },
    "metadata": { "ticket_id": "T-1234" },
    "created_at": "2026-08-21T14:30:00Z",
    "started_at": "2026-08-21T14:30:05Z",
    "finished_at": "2026-08-21T14:35:00Z",
    "status_url": "/platform/v1/kapso-agent/runs/990e8400-e29b-41d4-a716-446655440004"
  }
}
```

`id` is a deterministic SHA-256 hash of the run, event, and approval, so redeliveries carry the same id. Failed and cancelled runs include `error` with `code` (`run_failed` or `run_cancelled`) and `message`. Deliveries are signed with HMAC-SHA256 like all project webhooks - see [webhook security](/docs/platform/webhooks/security).