Skip to main content
POST
/
agent
/
create
Create Agent
curl --request POST \
  --url https://api.example.com/agent/create

​
Create Agent

Deploy a new AI agent with custom configuration. The agent will be provisioned in a Kubernetes environment with its own persistent storage.

​
Endpoint

POST /agent/create

​
Authentication

Requires JWT token or Platform API key.

​
Request Body

FieldTypeRequiredDescription
namestringYesAgent name (1-100 characters)
descriptionstringNoAgent description (max 500 characters)
pvc_sizestringNoPersistent volume size (e.g., 2Gi)
anthropic_api_keystringYesAnthropic API key for the agent
configurationobjectNoAgent configuration options
initial_filesarrayNoFiles to create in agent workspace

​
Configuration Options

FieldTypeDefaultDescription
timeout_secondsnumber3600Task timeout in seconds
mcp_serversobject-MCP server configurations
memory_configobject-Memory configuration
webhooksobject-Webhook URLs for notifications

​
Memory Configuration

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

​
Webhooks

FieldTypeDescription
task_completestringURL called when a task completes
task_failedstringURL called when a task fails
task_awaiting_inputstringURL called when a task needs input
agent_errorstringURL called on agent error

​
Initial Files

FieldTypeRequiredDescription
pathstringYesFile path in workspace
contentstringYesFile content
encodingstringNoContent encoding (utf-8 or base64, default: utf-8)

​
Example Request

curl -X POST https://api.app.shinzo.ai/agent/create \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-review-agent",
    "description": "Agent for automated code reviews",
    "anthropic_api_key": "sk-ant-api03-...",
    "pvc_size": "5Gi",
    "configuration": {
      "timeout_seconds": 1800,
      "webhooks": {
        "task_complete": "https://myapp.com/webhooks/task-complete"
      }
    },
    "initial_files": [
      {
        "path": "config.json",
        "content": "{\"review_style\": \"thorough\"}"
      }
    ]
  }'

​
Response

{
  "uuid": "agt_abc123def456",
  "name": "code-review-agent",
  "description": "Agent for automated code reviews",
  "status": "active",
  "created_at": "2025-01-15T10:00:00Z",
  "endpoint_url": "https://agent-abc123.shinzo.ai",
  "container_id": "k8s-pod-xyz789",
  "platform_api_key": "sk_shinzo_auto_generated...",
  "configuration": {
    "timeout_seconds": 1800,
    "memory_config": {
      "type": "hierarchical",
      "max_size_mb": 1024,
      "persistence": "persistent"
    }
  }
}

​
Response Fields

FieldTypeDescription
uuidstringUnique agent identifier
namestringAgent name
statusstringAgent status (active)
endpoint_urlstringAgent’s API endpoint
container_idstringKubernetes pod identifier
platform_api_keystringAuto-generated API key for Spotlight analytics
created_atstringCreation timestamp

​
Status Codes

CodeDescription
201Agent created successfully
400Invalid request (validation error)
401Invalid authentication
403AI Agents feature not enabled

​
Resource Limits

Agents are provisioned with the following resource limits:
ResourceRequestLimit
CPU250m1000m
Memory512Mi2Gi