# Execute agent
Source: https://docs.kaizenautomation.com/api-reference/agents/execute-agent
post /agents/execute
Executes an agent with optional content.
# Get session
Source: https://docs.kaizenautomation.com/api-reference/agents/get-session
post /agents/sessions/get
Reads the state of a session started by POST /agents/execute: whether it is running, waiting in line, or finished, where it sits in its queue, and how much work that queue is holding. Cheap enough to poll while waiting for enqueued work to start.
# Get session archive download URL
Source: https://docs.kaizenautomation.com/api-reference/agents/get-session-archive-download-url
post /agents/session/getFileArchiveUrl
Returns a signed download URL for the completed file archive associated with a session.
# List agent messages
Source: https://docs.kaizenautomation.com/api-reference/agents/list-agent-messages
post /agents/session/messages/list
Lists messages in a thread with pagination. Returns messages in a simplified format with user, assistant, and tool messages.
# Pause session
Source: https://docs.kaizenautomation.com/api-reference/agents/pause-session
post /agents/sessions/pause
Pauses a session, whether it has started or not. A session that is running stops where it is and hands back the slot it was holding, so the next session in line can start; a session still waiting in line leaves the line. Either way it ends up Paused, and can be picked back up by sending it another message. Pausing a session that is already paused does nothing.
# Complete login authentication
Source: https://docs.kaizenautomation.com/api-reference/authentication/complete-login-authentication
post /authentication/completeLogin
Completes login authentication using browser context login info external ID by saving browser cookies and updating authentication status
# Submit 2FA code
Source: https://docs.kaizenautomation.com/api-reference/authentication/submit-2fa-code
post /authentication/submitTwoFactorAuthCode
Verifies a two-factor authentication code for an ongoing authentication session
# Get browser session recording
Source: https://docs.kaizenautomation.com/api-reference/browser-sessions/get-browser-session-recording
post /browsers/getSessionRecording
Retrieves the recording data for a specific browser session
# Get execution
Source: https://docs.kaizenautomation.com/api-reference/executions/get-execution
post /executions/get
Retrieves a single execution by ID for the current organization
# List executions
Source: https://docs.kaizenautomation.com/api-reference/executions/list-executions
post /executions/list
Retrieves all executions for the current organization with optional filtering
# Retry execution
Source: https://docs.kaizenautomation.com/api-reference/executions/retry-execution
post /executions/retry
Retries a completed or failed workflow execution by creating a new execution with a new session
# Create a file
Source: https://docs.kaizenautomation.com/api-reference/files/create-a-file
post /files/create
Upload a file using multipart/form-data.
# Get file
Source: https://docs.kaizenautomation.com/api-reference/files/get-file
post /files/get
Retrieves a single file by ID for the current organization
# Run single block
Source: https://docs.kaizenautomation.com/api-reference/instructor/run-single-block
post /instructor/executions/runBlock
Executes a single block by ID or name within an instructor execution context. Provide either blockId or blockName to identify the block.
# Create a login
Source: https://docs.kaizenautomation.com/api-reference/logins/create-a-login
post /logins/create
Creates a new login with required credentials
# Delete a login
Source: https://docs.kaizenautomation.com/api-reference/logins/delete-a-login
post /logins/delete
Deletes a login and all associated data
# Get login password
Source: https://docs.kaizenautomation.com/api-reference/logins/get-login-password
post /logins/getPassword
Returns the decrypted password for a login. Gated by a LaunchDarkly feature flag per organization.
# List logins
Source: https://docs.kaizenautomation.com/api-reference/logins/list-logins
post /logins/list
Retrieves all logins with optional filtering by name or username
# Update a login
Source: https://docs.kaizenautomation.com/api-reference/logins/update-a-login
post /logins/update
Updates an existing login with optional credentials
# Event
Source: https://docs.kaizenautomation.com/api-reference/webhooks/event
webhook events
Webhook triggered when an event occurs
## Secure your endpoint
Verify that all webhook requests are generated by Kaizen by checking the signature in each request's `X-Webhooks-Signature` header.
### Verify the signature
Each webhook request includes these headers:
* `X-Webhooks-Signature`: HMAC signature (includes version prefix)
* `X-Webhooks-Timestamp`: Unix timestamp in seconds
* `X-Webhooks-Id`: Unique identifier for this webhook delivery
To verify a signature:
1. Extract the signature from `X-Webhooks-Signature` (remove the version prefix)
2. Get the timestamp from `X-Webhooks-Timestamp`
3. Get the webhook ID from `X-Webhooks-Id`
4. Read the raw request body as a string (before JSON parsing)
5. Construct the signed payload: `{webhookId}.{timestamp}.{raw_body}`
6. Compute HMAC-SHA256 of the signed payload using your decoded secret
7. Compare the computed signature with the received signature using constant-time comparison
### Code Examples
```javascript Node.js theme={null}
const crypto = require('crypto');
function verifyWebhookSignature(
webhookId,
payload,
signature,
timestamp,
secret
) {
const signedPayload = `${webhookId}.${timestamp}.${payload}`;
const keyBytes = Buffer.from(secret, 'base64url');
const expectedSignature = crypto
.createHmac('sha256', keyBytes)
.update(signedPayload, 'utf8')
.digest('hex');
if (signature.length !== expectedSignature.length) {
return false;
}
return crypto.timingSafeEqual(
Buffer.from(signature, 'hex'),
Buffer.from(expectedSignature, 'hex')
);
}
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const webhookId = req.headers['x-webhooks-id'];
const signatureHeader = req.headers['x-webhooks-signature'];
const timestamp = req.headers['x-webhooks-timestamp'];
if (!webhookId || !signatureHeader || !timestamp) {
return res.status(401).json({ error: 'Missing required headers' });
}
const signature = signatureHeader.replace(/^v\d+=/, '');
const payload = req.body.toString();
const webhookSecret = process.env.WEBHOOK_SECRET;
if (
!webhookSecret ||
!verifyWebhookSignature(
webhookId,
payload,
signature,
timestamp,
webhookSecret
)
) {
return res.status(401).json({ error: 'Invalid signature' });
}
const event = JSON.parse(payload);
// Process the webhook event
res.status(200).json({ received: true });
});
```
```python Python theme={null}
import base64
import hmac
import hashlib
import os
from flask import Flask, request
def verify_webhook_signature(webhook_id: str, payload: str, signature: str, timestamp: str, secret: str) -> bool:
signed_payload = f"{webhook_id}.{timestamp}.{payload}"
key_bytes = base64.urlsafe_b64decode(secret + '==')
expected_signature = hmac.new(
key_bytes,
signed_payload.encode('utf-8'),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected_signature)
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])
def webhook():
webhook_id = request.headers.get('X-Webhooks-Id', '')
signature_header = request.headers.get('X-Webhooks-Signature', '')
timestamp = request.headers.get('X-Webhooks-Timestamp', '')
if not webhook_id or not signature_header or not timestamp:
return {'error': 'Missing required headers'}, 401
signature = signature_header.split('=', 1)[1] if '=' in signature_header else signature_header
payload = request.get_data(as_text=True)
webhook_secret = os.environ.get('WEBHOOK_SECRET')
if not webhook_secret or not verify_webhook_signature(webhook_id, payload, signature, timestamp, webhook_secret):
return {'error': 'Invalid signature'}, 401
# Process the webhook event
return {'received': True}, 200
```
# Execute a workflow
Source: https://docs.kaizenautomation.com/api-reference/workflows/execute-a-workflow
post /workflows/execute
Executes a workflow with the specified login and parameters
# Execute a workflow synchronously
Source: https://docs.kaizenautomation.com/api-reference/workflows/execute-a-workflow-synchronously
post /workflows/executeSync
Executes a workflow with the specified login and parameters and waits for completion
# Execute multiple workflows in a batch
Source: https://docs.kaizenautomation.com/api-reference/workflows/execute-multiple-workflows-in-a-batch
post /workflows/executeBatch
Creates a batch execution with multiple workflow executions
# Update a workflow
Source: https://docs.kaizenautomation.com/api-reference/workflows/update-a-workflow
post /workflows/update
Updates workflow fields like name and authentication requirement
# Authentication
Source: https://docs.kaizenautomation.com/authentication
Description of core concepts exposed by the Kaizen Platform.
One of the most challenging barriers to reliable browser automation is managing user authentication: maintaining logins, keeping track of sessions, automating 2FA, loading cookies, and handling timely re-authentication. Kaizen handles all of this on your behalf.
# Automated Session Management
Kaizen continuously manages authentication sessions on your behalf. It will automatically handle:
* Automatic login using credentials you've securely stored.
* Session persistence between executions.
* Smart re-authentication that only occurs when needed to run an [execution](core-concepts/executions) for a [workflow](core-concepts/workflow).
# Two-Factor Authentication
Many portals require 2FA (One-Time Password) authentication as part of their login process. Kaizen supports allows developers to automate 2FA to consistently provide a logged in session for their workflow.
## Configuring 2FA
2FA is configured per [Login](core-concepts/logins). Some end users might not have 2FA enabled, while others do. Kaizen allows developers to specify:
* Whether 2FA is enabled for a given Login
* What method of 2FA delivery is used (e.g. email, SMS)
When 2FA is enabled for a [Login](core-concepts/logins), Kaizen supports two primary workflows to complete authentication for a page.
## Automating 2FA
There are two approaches developers can use to automate 2FA on the Kaizen platform.
### TOTP-Based 2FA Automation
The primary method Kaizen supports for automating two-factor authentication is through Time-based One-Time Password (TOTP) tokens. This approach uses a shared secret key to generate time-synchronized verification codes, similar to those provided by authenticator apps like Google Authenticator or Authy.
When you set up an item with TOTP-based 2FA:
1. Kaizen securely stores the TOTP secret key
2. During login flows, Kaizen automatically generates the current valid token
3. The system enters this token into the appropriate field to complete authentication
To set up TOTP-based 2FA for your items, please contact the Kaizen team.
### API-Based 2FA Completion
Another way to complete 2FA authentication for an [Item](core-concepts/items) is to forward all received 2FA codes to the [submit 2FA code for verification](api-reference/submit-2fa-code-for-verification) endpoint provided by Kaizen. Developers can receive 2FA codes through email and SMS, and simply forward the extracted code to this endpoint.
# Creating a Skill from a Template
Source: https://docs.kaizenautomation.com/cookbook/creating-a-skill-from-a-template
Learn how to create a new skill from one of the built-in templates, using a payer enrollment template as an example.
## Overview
Skills teach your agents how to perform a task. Instead of starting from a blank
document, you can build a skill from a template — a ready-to-edit outline for a
common workflow, such as a payer enrollment or credentialing process. This guide
walks through creating a skill from the **BCBS North Carolina Individual
Practitioner Enrollment** template.
## Step 1: Open the Skills page
From the sidebar, click **Skills**, then click the **+ New skill** button in the
skills panel.
![Skills page with the New skill button in the left sidebar]()
## Step 2: Browse the template catalog
The **Create a skill** dialog opens with the template catalog. You can start
blank or pick a template — everything stays editable after the skill is created.
Use the search-friendly list to scroll through templates, or narrow it down with
the theme tags at the top. Click **+N more** to expand the full list of themes.
![Create a skill dialog showing the template catalog and theme tags]()
## Step 3: Filter by theme
Click a theme tag to show only matching templates. For example, selecting
**payer-enrollment** narrows the catalog to payer enrollment templates like the
BCBS provider enrollment workflows.
![Template catalog filtered by the payer-enrollment theme]()
## Step 4: Preview the template
Click a template to select it. A preview opens showing the template's purpose,
variables, and step-by-step outline, and the skill name is pre-filled with the
template name — edit it if you want a different name.
![Template preview for the BCBS North Carolina enrollment template with the Build from template button]()
## Step 5: Build the skill
Click **Build from template**. A new agent session opens in plan mode: the
agent picks up the template and starts drafting the skill from its outline.
![Agent session in plan mode drafting the skill from the selected template]()
Once the agent finishes, the new skill appears in your skills list. From there
you can review the draft, tweak the steps, and fill in any
organization-specific details before putting the skill to work.
## Tips
* Templates are starting points — every section of the generated skill remains
editable.
* Theme tags can be combined with scrolling the catalog to quickly find the
right workflow (for example `credentialing`, `provider-enrollment`, or a
specific payer).
* If none of the templates fit, choose **Blank skill** to start from an empty
document instead.
# Listing Agent Messages via API
Source: https://docs.kaizenautomation.com/cookbook/listing-agent-messages
Learn how to retrieve paginated agent conversation messages using the Kaizen API, including user messages, assistant replies, and tool call results.
This guide walks you through using the Kaizen API to list messages from an agent conversation thread. The endpoint returns messages in a simplified format with pagination support.
## Overview
The `/agents/session/messages/list` endpoint lets you retrieve messages from a conversation thread. This is useful when you want to:
* Display conversation history in an external UI
* Process or analyze past agent interactions
* Build integrations that react to agent conversation content
## Prerequisites
Before you begin, make sure you have:
1. A Kaizen API key (found in your organization settings)
2. A thread ID from an existing agent conversation
## Authentication
All API requests require a Bearer token in the `Authorization` header:
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Listing Messages
Send a POST request with the thread `id` to retrieve messages. The endpoint returns up to 1000 messages per page.
### Request
```bash theme={null}
curl --request POST \
--url https://api.kaizenautomation.com/agents/session/messages/list \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"id": "agent_conversation_thread_abc123"
}'
```
### Response
```json theme={null}
{
"messages": [
{
"role": "user",
"parts": [
{
"type": "text",
"text": "Go to example.com and extract the main heading"
}
]
},
{
"role": "assistant",
"parts": [],
"toolCalls": [
{
"id": "agent_conversation_thread_messages_content_part_abc123",
"type": "function",
"function": {
"name": "NavigateToUrl",
"arguments": {
"url": "https://example.com"
}
}
}
]
},
{
"role": "tool",
"toolCallId": "agent_conversation_thread_messages_content_part_abc123",
"parts": [
{
"type": "text",
"text": "Successfully navigated to https://example.com"
}
]
},
{
"role": "assistant",
"parts": [
{
"type": "text",
"text": "The main heading on example.com is \"Example Domain\"."
}
]
}
],
"total": 4
}
```
## Pagination
The endpoint supports offset-based pagination. Use the `limit` and `offset` parameters to page through results.
### Parameters
| Parameter | Type | Default | Description |
| --------- | ------ | ------- | ---------------------------------------------- |
| `id` | string | - | **Required.** External ID of the thread. |
| `limit` | number | 1000 | Maximum messages to return (1-1000). |
| `offset` | number | 0 | Number of messages to skip from the beginning. |
### Example: Fetching the Second Page
```bash theme={null}
curl --request POST \
--url https://api.kaizenautomation.com/agents/session/messages/list \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"id": "agent_conversation_thread_abc123",
"limit": 1000,
"offset": 1000
}'
```
Use the `total` field in the response to determine how many pages exist.
## Message Types
Every message has a `role` field indicating who sent it.
### User Messages
Sent by the user to instruct the agent. Contains an array of content parts.
```json theme={null}
{
"role": "user",
"parts": [
{ "type": "text", "text": "Extract the product details" },
{ "type": "file", "fileId": "files_abc123" }
]
}
```
### Assistant Messages
Sent by the agent. There are two variants:
**Text reply** -- the agent responds with text content:
```json theme={null}
{
"role": "assistant",
"parts": [
{ "type": "text", "text": "Here are the product details I found..." }
]
}
```
**Tool call** -- the agent invokes one or more tools:
```json theme={null}
{
"role": "assistant",
"parts": [],
"toolCalls": [
{
"id": "content_part_id",
"type": "function",
"function": {
"name": "ClickElement",
"arguments": { "elementDescription": "Submit button" }
}
}
]
}
```
### Tool Messages
Results returned by a tool invocation. The `toolCallId` links back to the corresponding tool call.
```json theme={null}
{
"role": "tool",
"toolCallId": "content_part_id",
"parts": [{ "type": "text", "text": "Button clicked successfully" }]
}
```
### Developer Messages
System-level messages generated during the conversation (e.g., file downloads completed, CAPTCHA solving events, tab creation). These provide context about background operations.
```json theme={null}
{
"role": "developer",
"parts": [{ "type": "text", "text": "Downloads completed: report.pdf" }]
}
```
## Content Part Types
Each message contains an array of `parts`. The supported types are:
| Type | Fields | Description |
| ------ | -------- | ------------------------------- |
| `text` | `text` | Plain text content. |
| `file` | `fileId` | Reference to an uploaded file. |
| `json` | `data` | Structured key-value JSON data. |
## Summary
The List Messages API gives you paginated access to full agent conversation history. Use it to build custom UIs, analyze agent behavior, or integrate agent results into downstream systems.
# Setting Up Email 2FA Forwarding from Gmail
Source: https://docs.kaizenautomation.com/cookbook/setting-up-email-2fa-forwarding
Learn how to forward two-factor authentication (2FA) code emails from Gmail to Kaizen so your workflows can automatically handle email-based verification.
This guide walks you through setting up email forwarding in Gmail to automatically send 2FA verification code emails to Kaizen. This enables your automation workflows to receive and process email-based two-factor authentication codes.
## Overview
Many websites send verification codes via email as part of their two-factor authentication process. By forwarding these emails to Kaizen, your workflows can automatically extract and use these codes during login, eliminating the need for manual intervention.
## Prerequisites
Before you begin, make sure you have access to the Gmail account that receives the 2FA verification emails you want to forward to Kaizen.
## Step-by-Step Setup
### Step 1: Open Gmail Settings
In Gmail, click the gear icon in the top right corner to open Quick settings, then click "See all settings" to access the full settings page.
![Gmail Quick settings panel with See all settings button highlighted]()
### Step 2: Navigate to Filters and Create a New Filter
In the Settings page, click on the "Filters and Blocked Addresses" tab. Scroll down to the bottom of the page and click "Create a new filter".
![Gmail Settings showing Filters and Blocked Addresses tab with Create a new filter link]()
### Step 3: Set Filter Criteria
In the filter creation dialog, enter the email address that sends your 2FA codes in the "From" field. This should be the sender address of the verification emails from the service you want to automate (for example, `noreply@example.com`).
After entering the sender address, click "Create filter" to proceed to the next step.
![Gmail filter criteria dialog with From field and Create filter button]()
### Step 4: Enable Email Forwarding
In the filter actions dialog, check the "Forward it to:" checkbox. You will need to add the Kaizen forwarding address if you haven't already.
The forwarding address to use is: **[codes@mfa.kaizenautomation.com](mailto:codes@mfa.kaizenautomation.com)**
![Gmail filter actions showing Forward it to checkbox selected]()
If you haven't added the forwarding address before, click "Add forwarding
address" to add `codes@mfa.kaizenautomation.com` as a forwarding destination.
Gmail will send a verification email to confirm the forwarding address.
### Step 5: Create the Filter
After selecting the forwarding option and choosing the Kaizen forwarding address, click "Create filter" to save your filter.
![Gmail filter actions dialog with Create filter button]()
### Step 6: Contact Kaizen to Verify Setup
After creating the filter, reach out to the Kaizen team to confirm that we have received a verification email from Gmail. This step ensures that the forwarding is properly configured and that Kaizen can receive your 2FA emails.
The forwarding setup is not complete until the Kaizen team confirms receipt of
the Gmail verification email. Please contact us to verify your setup before
relying on email-based 2FA in your workflows.
## Using Email 2FA in Your Logins
Once the forwarding is set up and verified, you can configure your logins in Kaizen to use Email as the two-factor authentication method. When your workflow encounters a 2FA challenge, Kaizen will automatically retrieve the verification code from the forwarded email.
## Troubleshooting
If your 2FA emails are not being forwarded correctly, check the following:
1. Verify that the filter is active in your Gmail Filters and Blocked Addresses settings
2. Ensure the "From" address in your filter exactly matches the sender of the 2FA emails
3. Confirm that `codes@mfa.kaizenautomation.com` is listed as a verified forwarding address in Gmail
4. Contact the Kaizen team if you continue to experience issues
## Summary
By setting up email forwarding with Gmail filters, you can automate the handling of email-based 2FA codes in your Kaizen workflows. This eliminates manual code entry and enables fully automated authentication flows for services that use email verification.
# Triggering Agent Chat Messages via API
Source: https://docs.kaizenautomation.com/cookbook/triggering-agent-chat-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.
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](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) |
When `kaizenVersion` is not provided, the organization's default Kaizen
version is used.
## 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" }
}
}
}'
```
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, 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).
# Core Concepts
Source: https://docs.kaizenautomation.com/core-concepts
Description of core concepts exposed by the Kaizen Platform.
## Login
A Login represents a customer's login credentials and configuration for a specific website. Logins store all the necessary information to authenticate with a website.
A login has the following properties:
* Authentication URL: The entry point for the login process.
* Home URL: The URL of the website's home page after successful authentication.
* Login Configuration: This represents the required credentials to login to the website.
* The format of credentials expected (e.g. username/password, email/phone, etc.).
* Available 2FA methods (e.g. SMS, email, TOTP, etc.).
## Workflow
A Workflow is a browser-based automation that simulates user actions on a website or web application. Workflows are used to navigate throughout websites, extract data, or complete forms. Workflows operate on specific logins to perform authenticated actions.
## Execution
An Execution is a run of an automation on a specific website using a specific login.
Executions are performed by Kaizen workflows that simulate user actions in a browser. This can include logging in, navigating to pages, extracting data, or performing actions.
An execution has the following properties:
* Login ID: The ID of the login used to authenticate the session.
* Workflow ID: The ID of the workflow being executed.
* Parameters: A set of values used within a single run of an automation. For example, a parameter might specify the customer ID for which a order entry form must be completed.
# Slack
Source: https://docs.kaizenautomation.com/integrations/slack
Connect Kaizen to Slack to trigger agent tasks directly from your workspace.
## Overview
The Slack integration lets your team interact with Kaizen agents without leaving Slack. Mention **@Kaizen** in any channel or thread to start an agent session. The agent responds in-thread with results and a link to the full session in the Kaizen web app.
Key capabilities:
* Trigger agent tasks by mentioning @Kaizen in any message
* Send files and images as context for the agent
* Continue conversations in-thread to provide follow-up instructions
## Prerequisites
* A Kaizen account with an organization
* Slack workspace admin permissions (to approve the app install)
## Setup
Navigate to **Apps** in the Kaizen dashboard.
Click **Add App** and select **Slack** from the list.
Give the app a name (e.g. "Production Slack") so your team can identify it.
Click **Connect via Slack**. An OAuth popup opens — review the requested
permissions and authorize Kaizen in your Slack workspace.
Once authorized, the app status shows as **Active** in the dashboard.
## Usage
### Mentioning @Kaizen
1. Invite the **Kaizen** bot to the channel you want to use it in.
2. Tag **@Kaizen** in a message with your request.
3. Kaizen creates a thread and responds with a link to the live session.
### Sending files
Attach files or images to your message when mentioning @Kaizen. Files are downloaded and made available to the agent during execution.
Individual files must be under 20 MB.
### Thread conversations
Reply in a Kaizen thread and tag **@Kaizen** to send follow-up messages. You must mention @Kaizen in every reply — the agent only processes messages it is explicitly tagged in. The agent continues within the same session context, so you can refine your request or provide additional information without starting over.
# Introduction
Source: https://docs.kaizenautomation.com/introduction
Documentation for the Kaizen Automation API
## Overview
The Kaizen API allows you to programmatically interact with the Kaizen Automation Platform. This reference provides details about the available endpoints, request parameters, and response formats.
## Base URL
All API requests should be made to the following base URL:
```
https://api.kaizenautomation.com
```
## Authentication
All API endpoints are authenticated using Bearer tokens. Include your API key in the Authorization header:
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## API Endpoints
The Kaizen API is organized around the following resources:
Manage authentication and 2FA verification
Start and manage workflow executions
Create and manage logins for pages
Event notifications for workflow state changes