Skip to main content
POST
/
v1
/
agent
/
update
/
{id}
Update Agent
curl --request POST \
  --url https://api.app.shinzo.ai/v1/agent/update/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "pvc_size": "<string>",
  "system_prompt": "<string>",
  "system_prompt_type": "<string>",
  "output_token_balance": 123,
  "session_mode": "<string>",
  "warmth_window_ms": 123,
  "discord_bot_token": "<string>",
  "slack_bot_token": {},
  "telegram_bot_token": "<string>",
  "configuration": {},
  "files": {}
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.shinzo.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication

Requires JWT token or Platform API key via Authorization: Bearer <token> header.
​
id
string
required
Agent UUID
​
name
string
New agent name (1-100 characters)
​
description
string
New description (max 500 characters)
​
pvc_size
string
New persistent volume size (e.g., “2Gi”, “10Gi”)
​
system_prompt
string
New system prompt
​
system_prompt_type
string
How to apply the system prompt: replace or append
​
output_token_balance
number
Set agent output token balance directly
​
session_mode
string
Session lifecycle mode: ephemeral or persistent
​
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 (max 200 chars). Set to null to clear.
​
slack_bot_token
object
Slack credentials: { bot_token, signing_secret, app_token }. Set to null to clear.
​
telegram_bot_token
string
Telegram bot token (max 200 chars). Set to null to clear.
​
configuration
object
Configuration updates (partial update supported)
​
files
object
File operations to perform on the agent workspace

​
Configuration Object

All configuration fields are optional. Only provided fields will be updated.
FieldTypeDescription
timeout_secondsnumberNew task timeout in seconds
modelstringNew model name to use
mcp_serversobjectUpdated MCP server configurations
compactionobjectUpdated compaction configuration
custom_envobjectUpdated custom environment variables (max 20 entries)
unread_reminder_interval_msnumberHow often (ms) to remind agent about unread messages (10000-3600000)
hook_messagesobjectUpdated lifecycle prompt templates

​
Compaction Updates

FieldTypeDescription
enabledbooleanEnable/disable context compaction
threshold_triggernumberInput token threshold (50000-180000)
modelstringModel for summarization
instructionsstringCustom compaction prompt (max 2000 chars)

​
Hook Messages Updates

Each hook can be updated independently:
HookDescription
channel_message_receivedPrompt when new messages arrive
unread_message_reminderPeriodic reminder for unread messages
interruptPrompt when messages interrupt active session
session_restartMessage injected when agent pod restarts
compaction_summarizeInstructions for compaction summarization
compaction_continuationPrompt after compaction to continue work
session_resume_fallbackFallback when resuming without user input

​
File Operations

The files object allows you to add, update, or delete files in the agent workspace within a single request.
FieldTypeDescription
addarrayFiles to add (each with path, content, and optional encoding)
updatearrayFiles to update (each with path, content, and optional encoding)
deletearrayFile paths to delete (array of strings)

​
File Object

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

​
Example: Update Configuration

curl -X POST https://api.app.shinzo.ai/v1/agent/update/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated agent for thorough code reviews",
    "session_mode": "persistent",
    "configuration": {
      "timeout_seconds": 3600,
      "unread_reminder_interval_ms": 300000,
      "compaction": {
        "enabled": true,
        "threshold_trigger": 150000
      }
    }
  }'

​
Example: Update Files and Configuration

curl -X POST https://api.app.shinzo.ai/v1/agent/update/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "configuration": {
      "custom_env": {
        "REVIEW_STYLE": "detailed",
        "MAX_FILE_SIZE": "200000"
      }
    },
    "files": {
      "add": [
        {
          "path": "templates/review.md",
          "content": "# Review Template\n\n## Summary\n..."
        }
      ],
      "update": [
        {
          "path": "config.json",
          "content": "{\"review_style\": \"detailed\"}"
        }
      ],
      "delete": ["old-config.json", "deprecated/old-template.md"]
    }
  }'

​
Example: Configure Bot Tokens

curl -X POST https://api.app.shinzo.ai/v1/agent/update/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "telegram_bot_token": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
    "slack_bot_token": {
      "bot_token": "xoxb-1234567890-abcdefghijk",
      "signing_secret": "abc123def456",
      "app_token": "xapp-1-A01234BCDEF-567890"
    }
  }'

​
Example Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "code-review-agent",
  "description": "Updated agent for thorough code reviews",
  "status": "active",
  "session_mode": "persistent",
  "output_token_balance": 4850000,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-09T14:30:00Z",
  "configuration": {
    "timeout_seconds": 3600,
    "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": 150000
    }
  },
  "system_prompt": "You are a senior code reviewer.",
  "system_prompt_type": "append",
  "mcp_servers": [],
  "filesystem_summary": {
    "total_files": 16,
    "total_size_mb": 2.5,
    "last_modified": "2026-03-09T14:30:00Z"
  }
}

​
Status Codes

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

​
Notes

  • Partial updates: Only provide the fields you want to change
  • Bot tokens: Setting a bot token to null clears the configuration but doesn’t unlink existing channel bindings
  • PVC size: Can only be increased, not decreased
  • Configuration merging: Configuration updates are merged with existing settings (not replaced entirely)
  • File operations: All file operations in a single request are applied atomically