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": [
{}
]
}
'AI Agents
Create Agent
Deploy a new AI agent on the Shinzo Platform.
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 viaAuthorization: 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 appendstring
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. |
- Compaction and crash recovery ALWAYS resume the existing session regardless of mode
- Only new triggers (messages, schedules, webhooks) respect this setting
- In
ephemeralmode withinterruptqueue mode: immediately ends current session - In
ephemeralmode withcollectqueue 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 |