Skip to content
These docs are a preview of Self-Managed Kindo 2026.11, an upcoming release.

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.

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.
Terminal window
curl -X POST https://api.kindo.ai/v1/agents/create \
-H "Authorization: Bearer $KINDO_API_KEY" \
-H "Content-Type: application/json" \
-d @agent.json

For 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.

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.

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.

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.

StatusCause
400The 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.
401Missing, malformed, or revoked API key.
403Your 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.