Manage Deployments and Runs

All paths use https://api.sandbase.ai and an API key.

Deployment operations

Method	Path	Description
GET	/v1/deployments	List Deployments.
GET	/v1/deployments/{id}	Get a Deployment.
PATCH	/v1/deployments/{id}	Update future-run settings or Agent binding/configuration.
POST	/v1/deployments/{id}/pause	Stop scheduled triggers. Manual runs remain allowed.
POST	/v1/deployments/{id}/unpause	Resume at the next future schedule occurrence.
POST	/v1/deployments/{id}/archive	Permanently archive the Deployment.
DELETE	/v1/deployments/{id}	Archive the Deployment.

Basic updates can change name, initial_events, schedule, or timeout_policy while active or paused:

curl -fsS -X PATCH https://api.sandbase.ai/v1/deployments/depl_01abc \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeout_policy": {
      "hard_timeout_sec": null,
      "inactivity_timeout_sec": 600
    },
    "schedule": {
      "type": "cron",
      "expression": "30 8 * * 1-5",
      "timezone": "Asia/Shanghai"
    }
  }' | jq .

timeout_policy uses merge semantics. Omitting it preserves the current policy; setting the whole value to null restores the default of no hard limit and 300 seconds of inactivity. Inside the object, omitted fields stay unchanged, while hard_timeout_sec: null removes an existing hard limit. inactivity_timeout_sec cannot be null or disabled.

Policy updates affect only future Runs. Each manual or scheduled Run stores the policy that was active when the Run was created. Manual Run requests do not accept a timeout override.

Agent changes require a paused Deployment, no queued/running run, and expected_version from the latest detail response.

For an existing-Agent Deployment, replace the binding atomically:

{
  "expected_version": 3,
  "agent_binding": {
    "agent_id": "agent_new",
    "agent_version": 2,
    "environment_id": "env_new"
  }
}

For a runtime-created Deployment, merge changes into its managed Agent configuration:

{
  "expected_version": 3,
  "agent_config": {
    "system": "Report only verified, material AI news.",
    "skills": [],
    "tools": [{"type": "agent_toolset_20260401"}],
    "mcp_servers": []
  }
}

Trigger a manual run

POST/v1/deployments/{id}/runs

curl -fsS -X POST https://api.sandbase.ai/v1/deployments/depl_01abc/runs \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: daily-ai-news-2026-07-21" \
  -d '{
    "initial_events": [{
      "type": "user.message",
      "content": "Run the AI news summary now."
    }],
    "conversation_key": "daily-ai-news"
  }' | jq .

Both active and paused Deployments accept manual runs. The request-level initial_events overrides the Deployment default for this run only. Reusing an idempotency key with the same body returns the same request_id; reusing it with a different body returns 409 idempotency_conflict.

The asynchronous 202 Accepted response contains the stable run identifier:

{
  "request_id": "req_01abc"
}

List and retrieve runs

Method	Path	Description
GET	/v1/deployments/{id}/runs	List run history for one Deployment.
GET	/v1/deployments/{id}/runs/{request_id}	Get one run for a Deployment.
GET	/v1/deployment_runs/{request_id}	Get one Deployment run directly.

Run-list filters include status, trigger, RFC 3339 from/to, cursor, and limit (maximum 100).

curl -fsS \
  "https://api.sandbase.ai/v1/deployments/depl_01abc/runs?trigger=scheduled&limit=20" \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  | jq .

curl -fsS \
  "https://api.sandbase.ai/v1/deployment_runs/req_01abc" \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  | jq .

{
  "request_id": "req_01abc",
  "deployment_id": "depl_01abc",
  "agent_id": "agent_01abc",
  "trigger": "scheduled",
  "status": "completed",
  "session_id": "sess_01abc",
  "is_cold_start": true,
  "timeout_policy": {
    "hard_timeout_sec": null,
    "inactivity_timeout_sec": 300
  },
  "last_activity_at": "2026-07-21T01:00:03Z",
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 80
  },
  "latency_ms": 4200,
  "correlation_status": "complete",
  "created_at": "2026-07-21T01:00:00Z",
  "completed_at": "2026-07-21T01:00:04Z"
}

session_id is nullable. timeout_policy is nullable only for historical Runs created before policy snapshots were introduced. A timed-out Run has status timeout and uses error_type: "hard_timeout" or error_type: "inactivity_timeout".

Mutation errors

Status	Type	Description
409	deployment_must_be_paused	Agent settings were changed while active.
409	deployment_run_in_progress	A queued/running run blocks Agent changes or archive.
409	deployment_version_conflict	expected_version is stale.
409	deployment_archived	An archived Deployment received a write operation.
409	idempotency_conflict	An idempotency key was reused with a different body.
404	deployment_not_found	Deployment was not found.
400	invalid_timeout_policy	The Deployment policy is invalid, or a manual Run attempted to override it.