Create Deployment

POST/v1/deployments

Create a Deployment that runs an Agent manually, on a cron schedule, or both.

Beta

Agent Deployments is a Beta API.

Create from an existing Agent

Use this mode when you already manage an Agent and Environment.

curl -fsS -X POST https://api.sandbase.ai/v1/deployments \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-ai-news",
    "agent_id": "agent_01abc",
    "agent_version": 1,
    "environment_id": "env_01abc",
    "initial_events": [{
      "type": "user.message",
      "content": "Find today’s important AI news and write a concise Chinese summary with source links."
    }],
    "timeout_policy": {
      "hard_timeout_sec": null,
      "inactivity_timeout_sec": 300
    },
    "schedule": {
      "type": "cron",
      "expression": "0 9 * * *",
      "timezone": "Asia/Shanghai"
    }
  }' | jq .

Create from a runtime definition

SandBase creates the Agent and Environment used by the Deployment from the runtime definition. Do not mix runtime with agent_id or environment_id.

curl -fsS -X POST https://api.sandbase.ai/v1/deployments \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-ai-news",
    "runtime": "hermes",
    "system": "Research carefully, verify sources, and be concise.",
    "skills": [],
    "tools": [{"type": "agent_toolset_20260401"}],
    "mcp_servers": [],
    "initial_events": [{
      "type": "user.message",
      "content": "Find today’s important AI news and write a concise Chinese summary with source links."
    }],
    "schedule": {
      "type": "cron",
      "expression": "0 9 * * *",
      "timezone": "Asia/Shanghai"
    }
  }' | jq .

JSON, application/yaml, and application/x-yaml definitions are accepted.

Request parameters

Parameter	Type	Required	Description
name	string	Yes	Human-readable Deployment name.
agent_id	string	Existing Agent mode	Non-archived Agent visible to the organization.
agent_version	integer	No	Version to pin. Defaults to the Agent's current version.
environment_id	string	Existing Agent mode	Non-archived, supported Environment in the organization.
runtime	string	Runtime mode	Enabled runtime profile. Cannot be mixed with Agent/Environment IDs.
description	string	No	Managed Agent description in runtime mode; not a Deployment description in existing-Agent mode.
model	string or object	No	Model override in runtime mode.
system	string	No	System prompt in runtime mode.
skills	string[] or null	No	Skill references in runtime mode.
tools	array or null	No	Tool configuration in runtime mode.
mcp_servers	array or null	No	Outbound MCP configuration in runtime mode.
initial_events	array	Yes	Must include at least one user.message event.
schedule	object or null	No	Five-field cron schedule. null creates a manual-only Deployment.
timeout_policy	object or null	No	SandBase execution limits. Omit or use null for no hard limit and a 300-second inactivity limit.

Execution limits

{
  "hard_timeout_sec": null,
  "inactivity_timeout_sec": 300
}

hard_timeout_sec is an optional absolute limit measured from Run creation. null means SandBase does not impose a total-duration limit. When set, it must be between 60 and 604800 seconds.

inactivity_timeout_sec is optional inside the object and defaults to 300. When set, it must be between 180 and 3600 seconds and cannot be disabled. Authenticated runtime heartbeats and persisted Run progress refresh activity. API reads, Dashboard polling, and connection keepalives do not.

Schedule

{
  "type": "cron",
  "expression": "0 9 * * 1-5",
  "timezone": "Asia/Shanghai"
}

expression is a five-field cron expression without seconds. timezone must be a valid IANA timezone.

Response

{
  "id": "depl_01abc",
  "type": "deployment",
  "name": "daily-ai-news",
  "agent_id": "agent_01abc",
  "agent_version": 1,
  "environment_id": "env_01abc",
  "status": "active",
  "version": 1,
  "creation_mode": "advanced",
  "timeout_policy": {
    "hard_timeout_sec": null,
    "inactivity_timeout_sec": 300
  },
  "schedule": {
    "type": "cron",
    "expression": "0 9 * * *",
    "timezone": "Asia/Shanghai"
  },
  "next_run_at": "2026-07-22T01:00:00Z",
  "created_at": "2026-07-21T10:00:00Z",
  "updated_at": "2026-07-21T10:00:00Z"
}

Declarative responses use creation_mode: "declarative" and include the resolved runtime.

Errors

Status	Type	Description
400	invalid_creation_mode	Runtime and Agent fields are mixed or incomplete.
400	invalid_initial_events	Events are empty or contain an unsupported event type/content.
400	invalid_schedule	Cron expression or timezone is invalid.
400	invalid_timeout_policy	Execution-limit values or null/zero semantics are invalid.
404	skill_not_found	A declared Skill is unavailable.
422	unsupported_runtime	The runtime profile is unknown or disabled.
422	unsupported_sandbox_provider	The selected Agent or Environment cannot run on the supported provider.

Continue with Manage Deployments and Runs.