Create Agent

curl --request POST \
  --url https://api.app.shinzo.ai/v1/agent/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "pvc_size": "<string>",
  "anthropic_api_key": "<string>",
  "output_token_balance": 123,
  "system_prompt": "<string>",
  "system_prompt_type": "<string>",
  "session_mode": "<string>",
  "warmth_window_ms": 123,
  "discord_bot_token": "<string>",
  "slack_bot_token": {},
  "telegram_bot_token": "<string>",
  "configuration": {},
  "initial_files": [
    {}
  ]
}
'

POST

agent

create

Create Agent

curl --request POST \
  --url https://api.app.shinzo.ai/v1/agent/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "pvc_size": "<string>",
  "anthropic_api_key": "<string>",
  "output_token_balance": 123,
  "system_prompt": "<string>",
  "system_prompt_type": "<string>",
  "session_mode": "<string>",
  "warmth_window_ms": 123,
  "discord_bot_token": "<string>",
  "slack_bot_token": {},
  "telegram_bot_token": "<string>",
  "configuration": {},
  "initial_files": [
    {}
  ]
}
'

Authentication

Requires JWT token or Platform API key via Authorization: Bearer <token> header.

string

required

Agent name (1-100 characters)

string

Agent description (max 500 characters)

string

default:"1Gi"

Persistent volume size (e.g., “1Gi”, “5Gi”)

string

Anthropic API key for the agent. If omitted, your stored key is used

number

default:"1000000"

Initial output token balance (default: 1M tokens ≈ $15 at Sonnet pricing)

string

Custom system prompt for the agent

string

default:"append"

How to apply the system prompt: replace or append

string

default:"ephemeral"

Session lifecycle mode: ephemeral (fresh session per trigger) or persistent (continuous context)

number

Idle grace period (ms) before pod scales to zero. Min: 300000 (5 min). null = never scale down.

string

Discord bot token for per-agent Discord integration (max 200 chars)

object

Slack credentials: { bot_token, signing_secret, app_token }

string

Telegram bot token for per-agent Telegram integration (max 200 chars)

object

Agent configuration options (see below)

array

Files to create in the agent workspace on deploy

Configuration Object

Field	Type	Default	Description
`timeout_seconds`	number	`3600`	Task timeout in seconds
`model`	string	-	Model name to use (overrides default)
`mcp_servers`	object	`{}`	MCP server configurations
`memory_config`	object	-	Memory configuration
`compaction`	object	-	Context compaction configuration
`custom_env`	object	-	Custom environment variables (max 20 entries, string values only)
`unread_reminder_interval_ms`	number	`120000`	How often (ms) to remind agent about unread messages. Min: 10000, Max: 3600000
`hook_messages`	object	-	Custom lifecycle prompt templates

Memory Configuration

Field	Type	Default	Description
`type`	string	`hierarchical`	Memory type (`hierarchical` or `flat`)
`max_size_mb`	number	`1024`	Maximum memory size in MB
`persistence`	string	`persistent`	Memory persistence (`ephemeral` or `persistent`)

Compaction

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable context compaction
`threshold_trigger`	number	`120000`	Input token threshold to trigger compaction (50000-180000)
`model`	string	`claude-haiku-4-5-20251001`	Model used for summarization
`instructions`	string	-	Custom compaction prompt (max 2000 chars)

Hook Messages

Custom prompts for agent lifecycle events. Each hook supports template variables and has a 5000 character limit.

Hook	Description	Template Variables
`channel_message_received`	Prompt when new messages arrive	`{{message_count}}`, `{{channel_sections}}`, `{{message_ids}}`
`unread_message_reminder`	Periodic reminder for unread messages	`{{message_count}}`
`interrupt`	Prompt when messages interrupt active session	`{{message_count}}`, `{{channel_sections}}`
`session_restart`	Message injected when agent pod restarts	-
`compaction_summarize`	Instructions for compaction summarization	`{{transcript}}`
`compaction_continuation`	Prompt after compaction to continue work	`{{summary}}`
`session_resume_fallback`	Fallback when resuming without user input	-

Custom Environment Variables

Max 20 key-value pairs
Keys and values must be strings
Key max length: 100 chars
Value max length: 10000 chars
Cannot override reserved env vars: AGENT_UUID, DATABASE_URL, HOME, WORKSPACE_PATH, ANTHROPIC_BASE_URL, ANTHROPIC_CUSTOM_HEADERS, ANTHROPIC_API_KEY, SHINZO_API_URL, SHINZO_INTERNAL_API_URL, SHINZO_API_KEY

Slack Bot Token

Required fields when providing Slack credentials:

Field	Description
`bot_token`	Slack bot token (xoxb-…)
`signing_secret`	Slack signing secret for webhook verification
`app_token`	Slack app-level token (xapp-…) for Socket Mode

Initial Files

Field	Type	Required	Description
`path`	string	✅	File path in the agent workspace
`content`	string	✅	File content
`encoding`	string	❌	Content encoding: `utf-8` (default) or `base64`

Session Mode

Controls how an agent handles new triggers with respect to the current session:

Mode	Behavior
`ephemeral` (default)	Each trigger starts a fresh session. Gives clean per-run analytics and discrete session history.
`persistent`	New messages append to the current session, maintaining continuous context across interactions.

Notes:

Compaction and crash recovery ALWAYS resume the existing session regardless of mode
Only new triggers (messages, schedules, webhooks) respect this setting
In ephemeral mode with interrupt queue mode: immediately ends current session
In ephemeral mode with collect queue mode: waits for current turn to end, then starts new session

Example Request

curl -X POST https://api.app.shinzo.ai/v1/agent/create \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-review-agent",
    "description": "Agent for automated code reviews",
    "pvc_size": "5Gi",
    "system_prompt": "You are a senior code reviewer. Be thorough and constructive.",
    "system_prompt_type": "append",
    "session_mode": "ephemeral",
    "output_token_balance": 5000000,
    "configuration": {
      "timeout_seconds": 1800,
      "unread_reminder_interval_ms": 300000,
      "compaction": {
        "enabled": true,
        "threshold_trigger": 100000,
        "instructions": "Focus on preserving code context and reviewer comments."
      },
      "custom_env": {
        "REVIEW_STYLE": "thorough",
        "MAX_FILE_SIZE": "100000"
      }
    },
    "initial_files": [
      {
        "path": "config.json",
        "content": "{\"review_style\": \"thorough\"}"
      }
    ]
  }'

Example Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "code-review-agent",
  "description": "Agent for automated code reviews",
  "status": "active",
  "session_mode": "ephemeral",
  "output_token_balance": 5000000,
  "created_at": "2026-03-09T10:00:00Z",
  "updated_at": "2026-03-09T10:00:00Z",
  "configuration": {
    "timeout_seconds": 1800,
    "unread_reminder_interval_ms": 300000,
    "memory_config": {
      "type": "hierarchical",
      "max_size_mb": 1024,
      "persistence": "persistent"
    },
    "compaction": {
      "enabled": true,
      "model": "claude-haiku-4-5-20251001",
      "threshold_trigger": 100000,
      "instructions": "Focus on preserving code context and reviewer comments."
    }
  },
  "system_prompt": "You are a senior code reviewer. Be thorough and constructive.",
  "system_prompt_type": "append",
  "mcp_servers": [],
  "filesystem_summary": {
    "total_files": 1,
    "total_size_mb": 0.01,
    "last_modified": "2026-03-09T10:00:00Z"
  }
}

Status Codes

Code	Description
`201`	Agent created successfully
`400`	Invalid request (validation error)
`401`	Unauthorized - invalid or missing authentication
`403`	AI Agents feature not enabled for your account

AI Agents Overview List Agents

Overview

Authentication

AI Agents

Agent Messaging

Agent Schedules & Triggers

Agent Channels

Agent Filesystem

MCP Servers

Spotlight

Tokens

Provider Keys

Telemetry

Create Agent

Authentication

Configuration Object

Memory Configuration

Compaction

Hook Messages

Custom Environment Variables

Slack Bot Token

Initial Files

Session Mode

Example Request

Example Response

Status Codes

​Authentication

​Configuration Object

​Memory Configuration

​Compaction

​Hook Messages

​Custom Environment Variables

​Slack Bot Token

​Initial Files

​Session Mode

​Example Request

​Example Response

​Status Codes

Authentication

Configuration Object

Memory Configuration

Compaction

Hook Messages

Custom Environment Variables

Slack Bot Token

Initial Files

Session Mode

Example Request

Example Response

Status Codes