Agents API request shape

The Agents API is composed of two discovery endpoints plus one trigger endpoint, alongside the run-status endpoint 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.

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

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	Most-recent run IDs for quick polling without listing.
lastRunAtUtc	string | null	ISO-8601 timestamp of the last run, or null if it has never run.
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 four-step end-to-end flow.
• Runs — GET /v1/runs/{runId} shape and lifecycle.
• Errors — error envelopes for each endpoint.