API Overview

The Kindo API provides programmatic access to all platform capabilities, including chat completions, model listing, agents, integrations, and administration.

Domains

Kindo uses two API domains:

Domain	Endpoints	Auth header
`llm.kindo.ai`	Chat completions (`/v1/chat/completions`, `/v1/completions`)	`Authorization: Bearer` or `api-key`
`api.kindo.ai`	Chat Actions (`/v1/responses`), conversations (`/v1/conversations`)	`Authorization: Bearer`
`api.kindo.ai`	Models, agents, and all other endpoints	`x-api-key`

Note: the llm.kindo.ai domain is OpenAI-compatible — standard OpenAI SDKs work out of the box.

Getting Your API Key

Sign in to the Kindo Terminal.
Open Settings (gear icon) > API.
Copy your API key.

You can also view the exact model names available to your organization under Settings > Kindo API > Available Models.

For self-hosted installations, replace llm.kindo.ai and api.kindo.ai with your API endpoint(s).

Core Endpoints

Chat Completions

POST llm.kindo.ai/v1/chat/completions

Send a message to an AI model. This endpoint is OpenAI-compatible.

curl -X POST https://llm.kindo.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [
      { "role": "user", "content": "Explain Kubernetes pod security policies." }
    ]
  }'

Supports streaming via "stream": true.

List Models

GET api.kindo.ai/v1/models

Returns all models available to your organization in the standard OpenAI models-list format.

curl https://api.kindo.ai/v1/models \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet-4-5-20250929",
      "object": "model",
      "created": 0,
      "owned_by": "kindo"
    }
  ]
}

Use the id value as the model parameter in chat completion requests.

Agent Endpoints

Use these endpoints to discover your agentId and the exact input labels required before running an agent.

List Agents

GET api.kindo.ai/v1/agents/list

Returns all agents available to your organization.

curl https://api.kindo.ai/v1/agents/list \
  -H "x-api-key: YOUR_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": {}
    }
  ],
  "total": 1
}

Get Agent Details

GET api.kindo.ai/v1/agents/{agentId}

Returns agent configuration details, including the expected inputs labels.

curl https://api.kindo.ai/v1/agents/YOUR_AGENT_ID \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "agentId": "18d20df4-d9b3-4cb0-a009-9f11ec9c5d3d",
  "name": "Daily Security Scan",
  "description": "Runs the daily vulnerability check workflow.",
  "inputs": ["query"],
  "hasTriggers": true,
  "modelsInUse": ["claude-sonnet-4-5-20250929"],
  "recentRunIds": ["7a7ced7d-95a8-416f-95bb-5c0ff3599f53"],
  "lastRunAtUtc": "2026-03-12T15:00:00.000Z",
  "metadata": {}
}

Run Agent

POST api.kindo.ai/v1/agents/runs

Trigger an agent execution programmatically.

curl -X POST https://api.kindo.ai/v1/agents/runs \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "agentId": "YOUR_AGENT_ID", "inputs": [{ "name": "query", "value": "Run the daily security scan" }] }'

Request body:

{
  "agentId": "YOUR_AGENT_ID",
  "inputs": [
    {
      "name": "query",
      "value": "Run the daily security scan"
    }
  ]
}

Notes:

inputs is optional.
Each input name must exactly match the input label shown in the agent UI.

Response (202 Accepted):

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

Get Run Result

GET api.kindo.ai/v1/runs/{runId}

Poll a run until it completes.

curl https://api.kindo.ai/v1/runs/YOUR_RUN_ID \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "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": "Security scan complete. No critical findings.",
  "status": "success"
}

status can be one of: cancelled, failure, in_progress, success.

Chat Actions API

The Chat Actions API provides an agentic conversation interface following the OpenAI Responses API spec. Kindo built-in tools (shell, web search, browser, file operations, and more) are always enabled by default. You can also connect MCP integrations and define client-side function tools. Use tool_choice with allowed_tools to restrict which tools the model can use per-request.

Note: the Responses API uses api.kindo.ai with Authorization: Bearer authentication.

Create Response

POST api.kindo.ai/v1/responses

Send a message and get an agentic response. Auto-creates a conversation on the first call, or continues an existing one via the conversation field.

curl -X POST https://api.kindo.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "claude-sonnet-4-5",
    "input": "What is the capital of France?"
  }'

Response:

{
  "id": "resp_abc123_1",
  "object": "response",
  "status": "completed",
  "model": "claude-sonnet-4-5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "The capital of France is Paris." }],
      "status": "completed"
    }
  ],
  "output_text": "The capital of France is Paris.",
  "conversation": { "id": "conv_abc123" },
  "tools": [
    { "type": "shell" },
    { "type": "web_search" },
    { "type": "computer" }
  ]
}

Parameters:

Parameter	Required	Description
`model`	Yes	Model name (e.g. `claude-sonnet-4-5`)
`input`	Yes	String or array of input items
`conversation`	No	Conversation ID to continue
`instructions`	No	System-level instructions
`tools`	No	MCP integrations and function tool definitions. Kindo built-in tools are always enabled by default.
`tool_choice`	No	`"auto"` (default), `"none"`, or `{ "type": "allowed_tools", "tools": [...] }` to restrict to a subset of available tools per-request
`stream`	No	`true` for Server-Sent Events
`metadata`	No	Arbitrary key-value pairs

Function Tools

Function tools let clients define tools that the model can call, but execution happens client-side. When the model calls a function tool, the response has status: "incomplete" — send the result back to continue.

# Step 1: Send request with tools and tool_choice
curl -X POST https://api.kindo.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "claude-sonnet-4-5",
    "input": "What is the weather in SF?",
    "tools": [
      { "type": "mcp", "server_label": "linear" },
      {
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {
          "type": "object",
          "properties": { "location": { "type": "string" } },
          "required": ["location"]
        }
      }
    ],
    "tool_choice": {
      "type": "allowed_tools",
      "mode": "auto",
      "tools": [
        { "type": "function", "name": "get_weather" }
      ]
    }
  }'

Response (status incomplete):

{
  "status": "incomplete",
  "incomplete_details": { "reason": "tool_use" },
  "output": [{
    "type": "function_call",
    "call_id": "toolu_abc123",
    "name": "get_weather",
    "arguments": "{\"location\":\"San Francisco, CA\"}"
  }],
  "conversation": { "id": "conv_xyz789" }
}

# Step 2: Send function result back
curl -X POST https://api.kindo.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "claude-sonnet-4-5",
    "conversation": "conv_xyz789",
    "input": [{
      "type": "function_call_output",
      "call_id": "toolu_abc123",
      "output": "{\"temperature\": 68, \"unit\": \"fahrenheit\"}"
    }],
    "tools": [{
      "type": "function",
      "name": "get_weather",
      "description": "Get current weather",
      "parameters": {
        "type": "object",
        "properties": { "location": { "type": "string" } },
        "required": ["location"]
      }
    }]
  }'

OpenAI SDK Compatibility

Point the OpenAI SDK at your Kindo endpoint:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.kindo.ai/v1",
    api_key="YOUR_API_KEY",
)

response = client.responses.create(
    model="claude-sonnet-4-5",
    input="Explain Kubernetes pod security policies.",
)

print(response.output_text)

Get Response

GET api.kindo.ai/v1/responses/{response_id}

Retrieve a previously created response.

curl https://api.kindo.ai/v1/responses/resp_abc123_1 \
  -H "Authorization: Bearer YOUR_API_KEY"

List Input Items

GET api.kindo.ai/v1/responses/{response_id}/input_items

List all input items for a response.

curl https://api.kindo.ai/v1/responses/resp_abc123_1/input_items \
  -H "Authorization: Bearer YOUR_API_KEY"

Conversations API

List Conversation Items

GET api.kindo.ai/v1/conversations/{conversation_id}/items

List all items in a conversation — messages, tool calls, and function calls.

curl https://api.kindo.ai/v1/conversations/conv_abc123/items \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Conversation Item

GET api.kindo.ai/v1/conversations/{conversation_id}/items/{item_id}

Get a specific item from a conversation.

curl https://api.kindo.ai/v1/conversations/conv_abc123/items/msg_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"

Request and Response Format

All requests and responses use JSON. The API follows REST conventions:

Method	Purpose
`GET`	Retrieve resources
`POST`	Create resources or trigger actions
`PUT`	Update resources
`DELETE`	Remove resources

Rate Limits

API requests are subject to your organization’s rate limits. If you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header.

Security

DLP — The same Data Loss Prevention filters that protect the UI also apply to API requests.
Audit logging — All API calls are recorded in your organization’s audit trail.
RBAC — API keys inherit the permissions of the user who created them.

Error Handling

The API returns standard HTTP status codes:

Code	Meaning
`200`	Success
`400`	Bad request — check your request body
`401`	Unauthorized — check your API key
`403`	Forbidden — insufficient permissions
`404`	Resource not found
`429`	Rate limited — retry after the specified delay
`500`	Server error — contact support if persistent

Error responses include a JSON body with a message field describing the issue.

Next Steps

First API Call for a hands-on quickstart
OpenAPI spec for the full api.kindo.ai endpoint reference
Glossary for API-related terminology