Agents API request shape

The Agents API is composed of two discovery endpoints, one trigger endpoint, and two run-inspection endpoints covered in Runs. All responses are JSON. Authentication is the same Authorization: Bearer $KINDO_API_KEY used elsewhere.

GET /v1/agents/list

Lists agents the API-key holder can see. This endpoint accepts no query parameters and returns the visible agents in a single page, capped at 500 entries. The response does not include a has_more or cursor field; callers that need more than 500 agents in a single organization should reach out to Kindo.

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

Response:

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

Envelope:

Field	Type	Notes
items	array	One entry per accessible agent. See the item-shape table below.
total	integer	Always equal to items.length. This endpoint is non-paginated; total is a convenience field, not a counter. Capped at 500 — see note above.

Item shape:

Field	Type	Notes
agentId	string	UUID. Use it in /v1/agents/{agentId} and runs calls.
name	string	Display name from the Kindo Terminal.
description	string	Free-form description.
createdAt	string	ISO-8601 timestamp.
creatorName	string	Name of the user or group that created the agent.
metadata	object	{ "userPermissions": string[] }. Entries are the actions the caller may perform on this agent — any subset of view, edit, delete, share.

GET /v1/agents/{agentId}

Returns the full agent configuration, including the inputs label list you must match when triggering a run. Optional query parameters paginate and filter the recentRunIds list.

curl https://api.kindo.ai/v1/agents/18d20df4-d9b3-4cb0-a009-9f11ec9c5d3d \
  -H "Authorization: Bearer $KINDO_API_KEY"

Query parameters (all optional):

Parameter	Type	Notes
limit	integer	Maximum number of run IDs to return in recentRunIds. Integer between 1 and 100 (inclusive). Defaults to 20 when any pagination/filter query parameter is supplied.
cursor	string	Opaque pagination cursor returned in nextCursor on the previous response. Pass it back unchanged to fetch the next page. The encoding is internal and may change — do not parse, modify, or construct cursors yourself. When combined with startDate/endDate, re-pass the same date filters on every follow-up request; the cursor does not encode them.
startDate	string	Inclusive ISO-8601 lower bound; only runs created at or after this timestamp are returned in recentRunIds.
endDate	string	Inclusive ISO-8601 upper bound; only runs created at or before this timestamp are returned in recentRunIds. When both are supplied, startDate must be less than or equal to endDate.

When no query parameters are supplied, the response shape and legacy run cap are preserved (up to 5 recentRunIds, no nextCursor field). When any of limit, cursor, startDate, or endDate is supplied, the paginated path is used: omitted limit defaults to 20, and the response always includes a nextCursor field, which is null on the last page.

Response:

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

Field	Type	Notes
agentId	string	UUID.
name	string	Display name.
description	string	Free-form description.
inputs	array of strings	Each entry is the label the agent expects in POST /v1/agents/runs. Returned in ascending alphabetical order, not in agent-configuration order.
hasTriggers	boolean	true when the agent has scheduled or event triggers configured. Agents with hasTriggers: true cannot be run via POST /v1/agents/runs — see Errors.
modelsInUse	array of strings	Model IDs this agent currently routes through.
recentRunIds	array of strings	Run IDs ordered newest-first. With no query parameters, capped by the legacy default of 5. With pagination/filter parameters, capped by limit (default 20, max 100) and filtered by startDate/endDate when supplied.
lastRunAtUtc	string | null	ISO-8601 timestamp of the agent’s most recent run, or null if it has never run. Independent of startDate/endDate filters — always reflects the true latest run.
nextCursor	string | null	Present only when one of limit, cursor, startDate, or endDate is supplied. A string cursor when more pages remain; null when the current page is the last.
metadata	object	{ "userPermissions": string[] }. Entries are the actions the caller may perform — any subset of view, edit, delete, share.

POST /v1/agents/runs

Triggers an agent execution.

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" }
    ]
  }'

Request body:

Field	Required	Type	Notes
agentId	Yes	string	An agentId returned by GET /v1/agents/list.
inputs	No	array of objects	Each entry is { "name": string, "value": string }. name must match a label from GET /v1/agents/{agentId}’s inputs. Required labels that are omitted produce a 422; entries with an unrecognized name are silently dropped.

Response (202 Accepted):

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

A 202 means Kindo accepted the trigger and will execute the run asynchronously. Use Runs to poll the result.

See also

• Quickstart — the end-to-end discover → trigger → poll → evals flow.
• Runs — GET /v1/runs/{runId} shape, lifecycle, and GET /v1/runs/{runId}/evals step verdicts.
• Errors — error envelopes for each endpoint.