Skip to main content
POST
/
v1
/
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.
​
name
string
required
Agent name (1-100 characters)
​
description
string
Agent description (max 500 characters)
​
pvc_size
string
default:"1Gi"
Persistent volume size (e.g., “1Gi”, “5Gi”)
​
anthropic_api_key
string
Anthropic API key for the agent. If omitted, your stored key is used
​
output_token_balance
number
default:"1000000"
Initial output token balance (default: 1M tokens ≈ $15 at Sonnet pricing)
​
system_prompt
string
Custom system prompt for the agent
​
system_prompt_type
string
default:"append"
How to apply the system prompt: replace or append
​
session_mode
string
default:"ephemeral"
Session lifecycle mode: ephemeral (fresh session per trigger) or persistent (continuous context)
​
warmth_window_ms
number
Idle grace period (ms) before pod scales to zero. Min: 300000 (5 min). null = never scale down.
​
discord_bot_token
string
Discord bot token for per-agent Discord integration (max 200 chars)
​
slack_bot_token
object
Slack credentials: { bot_token, signing_secret, app_token }
​
telegram_bot_token
string
Telegram bot token for per-agent Telegram integration (max 200 chars)
​
configuration
object
Agent configuration options (see below)
​
initial_files
array
Files to create in the agent workspace on deploy

​
Configuration Object

FieldTypeDefaultDescription
timeout_secondsnumber3600Task timeout in seconds
modelstring-Model name to use (overrides default)
mcp_serversobject{}MCP server configurations
memory_configobject-Memory configuration
compactionobject-Context compaction configuration
custom_envobject-Custom environment variables (max 20 entries, string values only)
unread_reminder_interval_msnumber120000How often (ms) to remind agent about unread messages. Min: 10000, Max: 3600000
hook_messagesobject-Custom lifecycle prompt templates

​
Memory Configuration

FieldTypeDefaultDescription
typestringhierarchicalMemory type (hierarchical or flat)
max_size_mbnumber1024Maximum memory size in MB
persistencestringpersistentMemory persistence (ephemeral or persistent)

​
Compaction

FieldTypeDefaultDescription
enabledbooleantrueEnable context compaction
threshold_triggernumber120000Input token threshold to trigger compaction (50000-180000)
modelstringclaude-haiku-4-5-20251001Model used for summarization
instructionsstring-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.
HookDescriptionTemplate Variables
channel_message_receivedPrompt when new messages arrive{{message_count}}, {{channel_sections}}, {{message_ids}}
unread_message_reminderPeriodic reminder for unread messages{{message_count}}
interruptPrompt when messages interrupt active session{{message_count}}, {{channel_sections}}
session_restartMessage injected when agent pod restarts-
compaction_summarizeInstructions for compaction summarization{{transcript}}
compaction_continuationPrompt after compaction to continue work{{summary}}
session_resume_fallbackFallback 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:
FieldDescription
bot_tokenSlack bot token (xoxb-…)
signing_secretSlack signing secret for webhook verification
app_tokenSlack app-level token (xapp-…) for Socket Mode

​
Initial Files

FieldTypeRequiredDescription
pathstring✅File path in the agent workspace
contentstring✅File content
encodingstring❌Content encoding: utf-8 (default) or base64

​
Session Mode

Controls how an agent handles new triggers with respect to the current session:
ModeBehavior
ephemeral (default)Each trigger starts a fresh session. Gives clean per-run analytics and discrete session history.
persistentNew 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

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