POST
/
instance
/
create
POST /instance/create
curl --request POST \
  --url https://api.example.com/instance/create \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "framework": "<string>",
  "version": "<string>"
}
'
{
  "402": {},
  "403": {},
  "instance_id": "<string>",
  "status": "<string>",
  "port": 123,
  "url": "<string>"
}

​
Overview

Create a new isolated Docker container running your AI agent framework.

​
Request

curl -X POST https://api.agentik.dev/api/instance/create \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "framework": "openclaw",
    "version": "latest"
  }'

​
Body Parameters

​
name
string
Optional instance name (defaults to auto-generated)
​
framework
string
default:"openclaw"
AI framework: openclaw (only option currently)
​
version
string
default:"latest"
Framework version tag

​
Response

{
  "instance_id": "inst_7xKXtg2CW87",
  "name": "my-agent",
  "status": "provisioning",
  "framework": "openclaw",
  "version": "latest",
  "port": 18042,
  "url": "https://inst-7xKXtg2CW87.agentik.dev",
  "created_at": "2026-02-12T10:30:00Z",
  "estimated_ready": "2026-02-12T10:30:30Z"
}
​
instance_id
string
Unique instance identifier
​
status
string
Current status: provisioning, running, stopped, failed
​
port
number
Assigned port (18000-19000 range)
​
url
string
Public URL to access instance

​
Provisioning Process

  1. Backend validates subscription + usage limits
  2. Allocates port from available range
  3. Creates Docker container with resource limits
  4. Starts container
  5. Records instance in database
  6. Returns instance details (status: provisioning)
Poll /instance/status/:id to check when status becomes running.

​
Errors

​
402
error
No active subscription
​
403
error
Instance limit exceeded for tier