Skip to main content
This guide walks you through using the Kaizen API to programmatically trigger agent chat messages. You can send simple text prompts, reference reusable skills, or combine both to create consistent, repeatable agent executions.

​
Overview

The Execute Agent endpoint lets you start an agent execution via API. This is useful when you want to:
  • Trigger agent tasks from external systems or scripts
  • Automate recurring agent tasks with consistent instructions
  • Seed agent executions with predefined skills for repeatable behavior

​
Prerequisites

Before you begin, make sure you have:
  1. A Kaizen API key (found in your organization settings)
  2. An agent configured in the Kaizen dashboard

​
Authentication

All API requests require a Bearer token in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Sending a Text Prompt

The simplest way to trigger an agent execution is to send a text prompt in the content array. This is equivalent to typing a message in the agent chat UI.

​
Request

curl --request POST \
  --url https://api.kaizenautomation.com/agents/execute \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "content": [
      {
        "type": "text",
        "text": "Go to example.com and extract the main heading"
      }
    ]
  }'

​
Response

{
  "executionId": "exec_abc123",
  "status": "running"
}
The executionId can be used with the Get Execution endpoint to check the status of your execution.
The agentId field is optional. If omitted, the backend will automatically get or create an agent for your organization.

​
Seeding an Execution with a Skill

Skills are reusable sets of instructions that you can attach to agent executions. By referencing a skill in your request, you ensure the agent reads the same skill content every time, making executions consistent and repeatable.

​
Finding Your Skill IDs

You can find your skill IDs on the Skills page in the Kaizen dashboard.

​
Request

To seed an execution with a skill, add a skill item to the content array alongside your text prompt: 
curl --request POST \
  --url https://api.kaizenautomation.com/agents/execute \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "content": [
      {
        "type": "text",
        "text": "Process the latest invoice from the portal"
      },
      {
        "type": "skill",
        "id": "your_skill_id_here"
      }
    ]
  }'
When a skill is referenced, the agent will read the skill content and use it as context for the execution. This is especially useful for:
  • Standardizing how the agent navigates a specific website
  • Providing step-by-step instructions that should be followed every time
  • Ensuring consistent data extraction across multiple executions

​
Sending Structured JSON Data

You can pass structured JSON data in the content array using the json type. This data is rendered as a key-value table in the agent chat UI and persisted as input.json in the session folder, making it available to the agent during execution.

​
Request

curl --request POST \
  --url https://api.kaizenautomation.com/agents/execute \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "content": [
      {
        "type": "text",
        "text": "Process this provider attestation"
      },
      {
        "type": "json",
        "data": {
          "providerName": "Dr. Jane Smith",
          "npiNumber": "1234567890",
          "specialty": "Internal Medicine",
          "licenseState": "CA",
          "isActive": true
        }
      }
    ]
  }'
The JSON data will:
  • Appear as a formatted key-value table in the chat UI under the user message
  • Be saved as input.json in the agent’s session folder for the agent to read during execution
  • Be included as text in the conversation history so the model can see the parameters
You can combine json parts with text and skill parts in the same request.

​
Extracting Structured Results

You can optionally pass a summarySchema to define a JSON Schema for the execution result. This tells the agent to extract structured data matching your schema at the end of the execution. 
curl --request POST \
  --url https://api.kaizenautomation.com/agents/execute \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "content": [
      {
        "type": "text",
        "text": "Go to example.com and extract the product details"
      },
      {
        "type": "skill",
        "id": "your_skill_id_here"
      }
    ],
    "summarySchema": {
      "type": "object",
      "properties": {
        "productName": { "type": "string" },
        "price": { "type": "number" },
        "availability": { "type": "string" }
      }
    }
  }'
The summarySchema overrides the agent-level result schema for this execution only. If you have a default schema configured on the agent, the per-request schema takes precedence.

​
Summary

The Execute Agent API gives you full programmatic control over agent executions. Use text prompts for ad-hoc tasks, reference skills for consistent repeatable behavior, pass structured JSON data for parameterized workflows, and define a summarySchema to extract structured results. For the full API reference, see the Execute Agent endpoint documentation.