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.

Paginating and filtering recentRunIds

The agent endpoint accepts optional limit, cursor, startDate, and endDate query parameters to page through and date-filter the recentRunIds list. When any of these is supplied, the paginated path uses a default limit of 20 and the response adds a nextCursor field: a string when more pages remain, null on the last page. Calls without query parameters keep the legacy response shape and legacy run cap.

Terminal window
curl "https://api.kindo.ai/v1/agents/18d20df4-d9b3-4cb0-a009-9f11ec9c5d3d?limit=2&startDate=2026-03-12T00:00:00Z" \
  -H "Authorization: Bearer $KINDO_API_KEY"

Note: for brevity, this example omits the unchanged agent-config fields (name, description, inputs, hasTriggers, modelsInUse, and metadata) shown above. The response shape is the same as the non-paginated example, plus nextCursor.

{
  "agentId": "18d20df4-d9b3-4cb0-a009-9f11ec9c5d3d",
  "recentRunIds": [
    "7a7ced7d-95a8-416f-95bb-5c0ff3599f53",
    "3c1f4e2a-19b8-4d5e-8a2f-b6d1e0c4f7a9"
  ],
  "lastRunAtUtc": "2026-03-12T15:00:00.000Z",
  "nextCursor": "<opaque-cursor-token>"
}

Pass the returned nextCursor back as ?cursor=… to fetch the next page. When you paginate a date-filtered list, re-pass the same startDate/endDate on every follow-up request — the cursor does not encode the date filters, and dropping them silently changes the page slice. lastRunAtUtc is independent of the filters — it always reflects the agent’s true most recent run. See Request shape → GET /v1/agents/{agentId} for the full parameter and response contract.

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.

5. Fetch evaluation results (optional)

If the agent has step-level objectives configured, you can retrieve per-step verdicts once the run completes:

Terminal window
curl https://api.kindo.ai/v1/runs/7a7ced7d-95a8-416f-95bb-5c0ff3599f53/evals \
  -H "Authorization: Bearer $KINDO_API_KEY"
{
  "runId": "7a7ced7d-95a8-416f-95bb-5c0ff3599f53",
  "result": "pass",
  "steps": [
    {
      "stepNumber": 1,
      "name": "Run the daily security scan",
      "result": "pass",
      "explanation": "Kindo completed the scan and found no critical vulnerabilities."
    }
  ]
}

result is one of pass, fail, pending, skipped, or unknown. See Runs → GET /v1/runs/{runId}/evals for the full field reference.

Next steps

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