Skip to content
Kindo Kindo Docs

Agents API quickstart

The Agents API is Kindo’s control-plane surface for discovering agents your organization has configured, triggering a run, and polling the run for its result. It is HTTP+JSON only — there is no SDK shim; any HTTP client works.

The flow is:

  1. GET /v1/agents/list — find the agentId you want to run.
  2. GET /v1/agents/{agentId} — inspect the expected inputs labels.
  3. POST /v1/agents/runs — trigger a run, receive a runId.
  4. GET /v1/runs/{runId} — poll until status is terminal.

Prerequisites

  • A Kindo API key (see Authentication).
  • At least one agent configured for your organization in the Kindo Terminal.

1. Discover an agentId

Terminal window
curl https://api.kindo.ai/v1/agents/list \
  -H "Authorization: Bearer $KINDO_API_KEY"

This endpoint accepts no query parameters and returns the visible agents in a single page, capped at 500 entries. See Request shape → GET /v1/agents/list for the cap and envelope details.

{
  "items": [
    {
      "agentId": "18d20df4-d9b3-4cb0-a009-9f11ec9c5d3d",
      "name": "Daily Security Scan",
      "description": "Runs the daily vulnerability check workflow.",
      "createdAt": "2026-03-10T18:45:23.000Z",
      "creatorName": "Security Team",
      "metadata": { "userPermissions": ["view", "edit"] }
    }
  ],
  "total": 1
}

2. Fetch the input schema

GET /v1/agents/{agentId} returns the agent’s configuration, including the inputs array — the exact labels you must use when triggering a run.

Terminal window
curl https://api.kindo.ai/v1/agents/18d20df4-d9b3-4cb0-a009-9f11ec9c5d3d \
  -H "Authorization: Bearer $KINDO_API_KEY"
{
  "agentId": "18d20df4-d9b3-4cb0-a009-9f11ec9c5d3d",
  "name": "Daily Security Scan",
  "description": "Runs the daily vulnerability check workflow.",
  "inputs": ["query"],
  "hasTriggers": false,
  "modelsInUse": ["claude-sonnet-4-5-20250929"],
  "recentRunIds": ["7a7ced7d-95a8-416f-95bb-5c0ff3599f53"],
  "lastRunAtUtc": "2026-03-12T15:00:00.000Z",
  "metadata": { "userPermissions": ["view", "edit"] }
}

Each name in the run request’s inputs array must match one of the strings in this inputs list exactly.

3. Trigger a run

Terminal window
curl -X POST https://api.kindo.ai/v1/agents/runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KINDO_API_KEY" \
  -d '{
    "agentId": "18d20df4-d9b3-4cb0-a009-9f11ec9c5d3d",
    "inputs": [
      { "name": "query", "value": "Run the daily security scan" }
    ]
  }'

The endpoint responds 202 Accepted with the runId:

{
  "runId": "7a7ced7d-95a8-416f-95bb-5c0ff3599f53"
}

4. Poll the run

Terminal window
curl https://api.kindo.ai/v1/runs/7a7ced7d-95a8-416f-95bb-5c0ff3599f53 \
  -H "Authorization: Bearer $KINDO_API_KEY"
{
  "runId": "7a7ced7d-95a8-416f-95bb-5c0ff3599f53",
  "agentId": "18d20df4-d9b3-4cb0-a009-9f11ec9c5d3d",
  "createdAtUtc": "2026-03-12T15:00:00.000Z",
  "endedAtUtc": "2026-03-12T15:00:08.000Z",
  "result": "{\"role\":\"assistant\",\"parts\":[{\"type\":\"text\",\"text\":\"Security scan complete. No critical findings.\"}]}",
  "status": "success"
}

result is a JSON-encoded string of the final assistant message payload — parse with JSON.parse to recover the structured { role, parts, ... } object. It is null while in_progress, always null on failure or cancelled, and also null on success when the run produced no assistant payload.

status is one of in_progress, success, failure, or cancelled. Anything other than in_progress is terminal; keep polling while status is in_progress. See Runs for the full lifecycle.

Next steps

  • Request shape — every field on every endpoint.
  • Runs — run lifecycle, polling cadence, and how runs relate to conversations.
  • Errors — common error envelopes.