Skip to main content
POST
/
v1
/
instances
curl -X POST https://api.chowder.dev/v1/instances \
  -H "Authorization: Bearer chd_org_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-assistant",
    "model_provider": "anthropic"
  }'

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "my-assistant",
  "status": "provisioning",
  "model_provider": "anthropic",
  "sandbox_provider": "sandbox",
  "sandbox_id": null,
  "gateway_url": null,
  "openclaw_version": "v1",
  "openclaw_config": null,
  "region": null,
  "error_message": null,
  "created_at": "2026-02-14T16:00:00.000000+00:00",
  "updated_at": "2026-02-14T16:00:00.000000+00:00"
}
Create a new instance. This kicks off a provisioning process that spins up a cloud sandbox, installs OpenClaw, configures your model provider, and starts the gateway. The endpoint returns immediately with status: "provisioning" — the sandbox takes roughly ~90 seconds to become fully ready. Poll Get Instance Status to know when provisioning completes.
Requires an organization key (chd_org_*). Your org must have an API key configured for the chosen model_provider — set one via Update Organization first.

​
Request Body

​
name
string
required
A name for the instance. 1–128 characters.
​
model_provider
string
default:"anthropic"
Which LLM provider to use. Your org must have an API key set for this provider.Options: "anthropic", "openai", "gemini"
​
sandbox_provider
string
default:"sandbox"
The cloud sandbox provider. Currently only "sandbox" is supported.
​
openclaw_version
string
default:"v1"
Which OpenClaw version to deploy. Defaults to "v1".
​
openclaw_config
object
Optional config overrides passed to the OpenClaw instance. These are dot-path key/value pairs that get applied via openclaw config set. Useful for tweaking behavior, setting system prompts, etc.
​
region
string
Preferred region for the sandbox. If not specified, the default region is used.

​
Response

Returns 201 Created with the instance object.
​
id
string
Unique instance ID (UUID).
​
organization_id
string
The owning organization’s ID.
​
name
string
Instance name.
​
status
string
Current status. Will be "provisioning" immediately after creation. See the overview for all possible states.
​
model_provider
string
The configured model provider.
​
sandbox_provider
string
The sandbox provider (e.g. "sandbox").
​
sandbox_id
string | null
The underlying sandbox ID. null until provisioning completes.
​
gateway_url
string | null
Public URL for the OpenClaw gateway. null until provisioning completes.
​
openclaw_version
string
The deployed OpenClaw version.
​
openclaw_config
object | null
Any config overrides applied to this instance.
​
region
string | null
The sandbox region, if specified.
​
error_message
string | null
If status is "error", this explains what went wrong.
​
created_at
string
ISO 8601 timestamp.
​
updated_at
string
ISO 8601 timestamp.
curl -X POST https://api.chowder.dev/v1/instances \
  -H "Authorization: Bearer chd_org_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-assistant",
    "model_provider": "anthropic"
  }'

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "my-assistant",
  "status": "provisioning",
  "model_provider": "anthropic",
  "sandbox_provider": "sandbox",
  "sandbox_id": null,
  "gateway_url": null,
  "openclaw_version": "v1",
  "openclaw_config": null,
  "region": null,
  "error_message": null,
  "created_at": "2026-02-14T16:00:00.000000+00:00",
  "updated_at": "2026-02-14T16:00:00.000000+00:00"
}