Skip to main content
POST
/
agents
/
execute
Execute agent
curl --request POST \
  --url https://api.kaizenautomation.com/agents/execute \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": "<string>",
  "content": [
    {
      "type": "<string>",
      "text": "<string>"
    }
  ],
  "archiveSessionFiles": false,
  "summarySchema": {}
}
'
{
  "sessionId": "<string>",
  "executionId": "<string>",
  "status": "<string>"
}

Body

application/json

Request parameters for executing an agent

​
agentId
string

Optional - the backend will automatically get or create an agent.

​
content
object[]

Optional content array. If provided, this will be used as the initial message. Each item must have a type field with one of the following values:

  • text — Plain text content. Requires a text string field.
  • file — A previously uploaded file. Requires an id string field with the file external ID.
  • skill — A skill to inject into the prompt. Requires an id string field with the agent_fs_node external ID.
  • json — Structured key-value data. Requires a data object field. Rendered as a table in the UI and persisted as input.json.
​
archiveSessionFiles
boolean
default:false

When true, request a background archive of the thread session files after the execution reaches a terminal state.

​
summarySchema
object

Optional JSON Schema for per-execution summary extraction. Overrides the agent-level result schema for this execution only.

​
kaizenVersion
enum<string>

Kaizen version tier to use for this execution. Determines the default model based on your organization’s model alias configuration for the selected tier.

  • Full — Uses the model configured for Kaizen Full (typically a frontier model).
  • Lite — Uses the model configured for Kaizen Lite (typically a smaller, faster model).

When not provided, the organization’s default Kaizen version is used.

Available options:
Full,
Lite

Response

Agent execution started successfully

Response after starting agent execution

​
sessionId
string
required

ID of the session started for this execution

​
executionId
string
required

ID of the execution

​
status
string
required

Current status of the execution