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": {}
}
'

POST

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": {}
}
'

Authentication

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

string

required

Agent UUID

string

New agent name (1-100 characters)

string

New description (max 500 characters)

string

New persistent volume size (e.g., “2Gi”, “10Gi”)

string

New system prompt

string

How to apply the system prompt: replace or append

number

Set agent output token balance directly

string

Session lifecycle mode: ephemeral or persistent

number

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

string

Discord bot token (max 200 chars). Set to null to clear.

object

Slack credentials: { bot_token, signing_secret, app_token }. Set to null to clear.

string

Telegram bot token (max 200 chars). Set to null to clear.

object

Configuration updates (partial update supported)

object

File operations to perform on the agent workspace

Configuration Object

All configuration fields are optional. Only provided fields will be updated.

Field	Type	Description
`timeout_seconds`	number	New task timeout in seconds
`model`	string	New model name to use
`mcp_servers`	object	Updated MCP server configurations
`compaction`	object	Updated compaction configuration
`custom_env`	object	Updated custom environment variables (max 20 entries)
`unread_reminder_interval_ms`	number	How often (ms) to remind agent about unread messages (10000-3600000)
`hook_messages`	object	Updated lifecycle prompt templates

Compaction Updates

Field	Type	Description
`enabled`	boolean	Enable/disable context compaction
`threshold_trigger`	number	Input token threshold (50000-180000)
`model`	string	Model for summarization
`instructions`	string	Custom compaction prompt (max 2000 chars)

Hook Messages Updates

Each hook can be updated independently:

Hook	Description
`channel_message_received`	Prompt when new messages arrive
`unread_message_reminder`	Periodic reminder for unread messages
`interrupt`	Prompt when messages interrupt active session
`session_restart`	Message injected when agent pod restarts
`compaction_summarize`	Instructions for compaction summarization
`compaction_continuation`	Prompt after compaction to continue work
`session_resume_fallback`	Fallback 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.

Field	Type	Description
`add`	array	Files to add (each with `path`, `content`, and optional `encoding`)
`update`	array	Files to update (each with `path`, `content`, and optional `encoding`)
`delete`	array	File paths to delete (array of strings)

File Object

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`

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

Code	Description
`200`	Agent updated successfully
`400`	Invalid request (validation error)
`401`	Unauthorized - invalid or missing authentication
`403`	AI Agents feature not enabled for your account
`404`	Agent 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

Overview

Authentication

AI Agents

Agent Messaging

Agent Schedules & Triggers

Agent Channels

Agent Filesystem

MCP Servers

Spotlight

Tokens

Provider Keys

Telemetry

Update Agent

Authentication

Configuration Object

Compaction Updates

Hook Messages Updates

File Operations

File Object

Example: Update Configuration

Example: Update Files and Configuration

Example: Configure Bot Tokens

Example Response

Status Codes

Notes

​Authentication

​Configuration Object

​Compaction Updates

​Hook Messages Updates

​File Operations

​File Object

​Example: Update Configuration

​Example: Update Files and Configuration

​Example: Configure Bot Tokens

​Example Response

​Status Codes

​Notes

Authentication

Configuration Object

Compaction Updates

Hook Messages Updates

File Operations

File Object

Example: Update Configuration

Example: Update Files and Configuration

Example: Configure Bot Tokens

Example Response

Status Codes

Notes