Create an agent
POST /v1/agents/create creates a new agent from an agent definition and
returns the new agent’s ID. Use it to create agents from scripts or other
tools instead of building them in the agent builder.
The new agent belongs to the user who owns the API key, regardless of the
creator value in the definition. If the user belongs to groups, at least
one group must allow agent creation. Users with no groups are allowed to create
agents by default. An admin can manage this permission under
User Groups.
Get a definition
Section titled “Get a definition”An agent definition is a JSON object describing the agent’s settings, inputs, and steps. You can get one in two ways:
- Download an existing agent. In the agent builder header, or in an agent’s row menu on the Agents list, select Download. Send the downloaded file as the request body, as-is or after editing it.
- Write one yourself. Build the JSON from scratch, starting from the example below. A downloaded agent shows every field a definition can contain.
Request
Section titled “Request”curl -X POST https://api.kindo.ai/v1/agents/create \ -H "Authorization: Bearer $KINDO_API_KEY" \ -H "Content-Type: application/json" \ -d @agent.jsonFor the full request schema, expand POST /agents/create in the
interactive API docs and open its request
Schema. You can also find AgentCreateRequestBody under
components.schemas in the OpenAPI JSON.
For self-managed deployments, the same /v1/docs/ paths are served on your
API base URL.
The request body is the definition itself. A minimal agent with one input and one model step:
{ "id": "draft", "displayName": "Alert Triage", "description": null, "systemPrompt": "You triage inbound security alerts.", "sourceWorkflowId": null, "isMockMode": false, "isAvailableAsChildWorkflow": false, "lastGenerationPrompt": null, "creator": { "id": "-", "email": "-" }, "triggers": [], "inputs": [ { "id": "input-1", "type": "TEXT_OR_CONTENT", "displayName": "Alert", "integrationName": null, "templateResolutionName": "alert", "integrationConnectionId": null, "triggerId": null } ], "steps": [ { "id": "step-1", "stepNumber": 1, "displayName": "Triage", "inputIds": ["input-1"], "staticContentIds": [], "llmStep": { "id": "llm-1", "model": { "id": "claude-sonnet-4-6" }, "promptTemplate": "Triage this alert: {{alert}}", "llmInteractionMode": "ACTIONS", "toolServerConfigs": [] } } ], "knowledgeStoreContentIds": []}Kindo assigns fresh IDs to the new agent, its steps, and its inputs. The
top-level id in your definition does not determine the new agent’s ID.
Within the definition, use matching IDs to connect parts. In the example
above, the step’s inputIds: ["input-1"] refers to the input with
id: "input-1". Kindo updates these references to the new IDs automatically,
so the step still uses the same input.
When writing a definition yourself, make each step’s inputIds match declared
input IDs. Kindo drops unmatched step input IDs and clears an unmatched trigger
inputId, so creation can succeed even when those links are missing. Check the
created agent in the builder before using it.
To give a step an integration’s tools, add an entry to its
llmStep.toolServerConfigs with the integration’s ID in
integrationConfigNangoId, for example reliaquest-greymatter. The ID must
match exactly, and the display name doesn’t work. See
Integration IDs for the IDs to use.
Select models
Section titled “Select models”Set the agent’s model with modelId and each model step’s model with
llmStep.model.id. Both accept a model name from
GET /v1/models, shown as API Model Name in
Kindo’s API settings, or the model’s Kindo ID from a downloaded agent. Omit
modelId to use your organization’s default model. A step’s displayName is
optional.
For example, set the agent’s model with:
{ "modelId": "claude-sonnet-4-6" }Or replace a step’s llmStep.model object with:
{ "id": "claude-sonnet-4-6" }Replace the example name with one available to you, including in the full definition above.
If Kindo doesn’t recognize a model, or you can’t use it, the request still
succeeds. A step uses Kindo’s default agent step model, and the agent uses your
organization’s default model. The response lists each one in warnings.
Response
Section titled “Response”201 Created:
{ "agentId": "0c4b1f44-8a2e-4d55-9b71-3f1c2e6a9d10" }When a model fell back, the response also includes
warnings, one entry for each field that fell back. field is modelId or
steps.<index>.llmStep.model.id, requested is the value you sent, and
message quotes it exactly as sent and names the default used:
{ "agentId": "0c4b1f44-8a2e-4d55-9b71-3f1c2e6a9d10", "warnings": [ { "field": "modelId", "requested": "unavailable-model", "message": "Unavailable model name \"unavailable-model\", falling back to the organization's default model" }, { "field": "steps.0.llmStep.model.id", "requested": "unavailable-model", "message": "Unavailable model name \"unavailable-model\", falling back to the default agent step model" } ]}warnings is omitted when no model fell back.
Pass agentId to POST /v1/agents/runs to run
the agent.
What is carried over
Section titled “What is carried over”Triggers don’t run until you turn them on. Every trigger is created turned off,
even if the definition marks it enabled. Turn each one on in the agent
builder before it will run; the API can’t turn triggers on.
An agent created through the API is handled the same way as an agent imported in the app, except that it also accepts model names. Some references are adjusted, for example integration connections you can’t use are left unset, and some make the request fail. See What an Import Carries Over and When an Import Can Fail.
Errors
Section titled “Errors”| Status | Cause |
|---|---|
400 | The body isn’t a valid agent definition, a referenced resource is unavailable to you, or a tool’s integration is not set up on this Kindo deployment. Check each integrationConfigNangoId against Integration IDs. |
401 | Missing, malformed, or revoked API key. |
403 | Your API access is disabled (“API key has been disabled”), or you belong to groups and none allow agent creation. |
See Agents API errors for the error envelope.
