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.

Base URL: https://api.kapso.ai/platform/v1. Authenticate with the X-API-Key header. Full endpoint reference: Kapso Agent API.

List modes

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 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:

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.

{
  "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:

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

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):

{
  "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

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:

{
  "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

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:

{
  "pending_approval": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "status": "pending",
    "tool_name": "send_whatsapp_message",
    "parameters": { "to": "[phone]" },
    "created_at": "2026-08-21T14:31:00Z"
  }
}

Approve or reject:

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 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.

{
  "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.