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

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

curl -X POST https://api.kindo.ai/v1/agents/create \
  -H "Authorization: Bearer $KINDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @agent.json

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.",
  "dashboardId": null,
  "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": "MODEL_ID",
          "displayName": "Model"
        },
        "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.

model.id is the model’s Kindo ID, which is different from the id that GET /v1/models returns. To get it, download an agent that uses the model and copy the step’s model.id. If Kindo doesn’t recognize the ID, or you can’t use that model, the step uses Kindo’s default agent step model and the request still succeeds.

Response

201 Created:

{ "agentId": "0c4b1f44-8a2e-4d55-9b71-3f1c2e6a9d10" }

Pass agentId to POST /v1/agents/runs to run the agent.

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

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