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

​
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, and define a summarySchema to extract structured results. For the full API reference, see the Execute Agent endpoint documentation.