> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaizenautomation.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggering Agent Chat Messages via API

> Learn how to programmatically trigger agent executions using the Kaizen API, including how to send text prompts and seed executions with skills.

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](/api-reference/agents/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](https://app.kaizenautomation.com)

## Authentication

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

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "executionId": "exec_abc123",
  "status": "running"
}
```

The `executionId` can be used with the [Get Execution](/api-reference/executions/get-execution) endpoint to check the status of your execution.

<Note>
  The `agentId` field is optional. If omitted, the backend will automatically
  get or create an agent for your organization.
</Note>

## 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](https://app.kaizenautomation.com/skills) in the Kaizen dashboard.

### Request

To seed an execution with a skill, add a `skill` item to the `content` array alongside your text prompt:

```bash theme={null}
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

```bash theme={null}
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.

## Choosing a Kaizen Version

By default, the agent uses the model configured for your organization's default Kaizen version. You can override this on a per-execution basis with the `kaizenVersion` parameter:

```bash theme={null}
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"
      }
    ],
    "kaizenVersion": "Lite"
  }'
```

| Version | Description                                                                   |
| ------- | ----------------------------------------------------------------------------- |
| `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) |

<Note>
  When `kaizenVersion` is not provided, the organization's default Kaizen
  version is used.
</Note>

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

```bash theme={null}
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" }
      }
    }
  }'
```

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

## 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, select a Kaizen version tier with `kaizenVersion`, and define a `summarySchema` to extract structured results. For the full API reference, see the [Execute Agent endpoint documentation](/api-reference/agents/execute-agent).