Control Plane Agents

Read and manage workspace-scoped Spinup Agents through the public control-plane API.

Use the control-plane API when you need workspace-scoped metadata or basic management for a Spinup Agent. Authenticate with a workspace API key for SDK/direct API usage, or a personal/device key for CLI usage. Do not use an agent runtime key here.

Inspect an agent

curl -sS "https://api.getspinup.com/v1/workspaces/acme/agents/support-agent" \
  -H "Authorization: Bearer sk_workspace_0123456789abcdef..."

Example response:

{
  "agent": {
    "id": "agent_01hxyz...",
    "name": "Support Agent",
    "slug": "support-agent",
    "createdAt": "2026-04-17T10:00:00.000Z",
    "updatedAt": "2026-04-17T10:05:00.000Z",
    "modelPolicy": {
      "provider": "openai",
      "model": "gpt-5.4"
    },
    "harnessTargets": [
      { "harnessName": "openclaw", "enabled": true, "role": "default" },
      { "harnessName": "hermes", "enabled": true, "role": "available" }
    ],
    "capabilityBindings": [],
    "runtimePolicy": {
      "resourceLimits": { "memoryMiB": 4096, "diskGiB": 4 },
      "networkPolicy": { "mode": "allow_all", "allowList": [] },
      "storagePolicy": { "persistent": true, "sizeGb": 4 }
    }
  },
  "environment": {
    "status": "ready",
    "attention": "none",
    "readyAt": "2026-04-17T10:06:00.000Z",
    "createdAt": "2026-04-17T10:01:00.000Z",
    "updatedAt": "2026-04-17T10:06:00.000Z",
    "lastError": null,
    "runtimeReconciliation": {
      "status": "applied",
      "lastError": null
    }
  }
}

The response is an inspection-safe subset of the agent's current model, harnesses, capabilities, runtime sizing and network policy, and environment status. It does not return secret values or internal runtime identifiers.

You won't find snapshot lifecycle controls in these examples on purpose. Spinup manages runtime persistence for you today, and there's no public way to stop, start, or snapshot an agent through /v1. A customer-operable lifecycle is on the roadmap; for now, persistence is a property the runtime guarantees, not a primitive you call.

Create an agent

curl -sS "https://api.getspinup.com/v1/workspaces/acme/agents" \
  -H "Authorization: Bearer sk_workspace_0123456789abcdef..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Support Agent" }'

Creation queues environment provisioning the same way dashboard creation does.

Rename an agent

curl -sS -X PATCH "https://api.getspinup.com/v1/workspaces/acme/agents/support-agent" \
  -H "Authorization: Bearer sk_workspace_0123456789abcdef..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Support Agent v2" }'

The returned agent.slug may change after a rename.

Update enabled harnesses

curl -sS -X PATCH "https://api.getspinup.com/v1/workspaces/acme/agents/support-agent/harnesses" \
  -H "Authorization: Bearer sk_workspace_0123456789abcdef..." \
  -H "Content-Type: application/json" \
  -d '{
    "harnessTargets": [
      { "harnessName": "openclaw", "enabled": true, "role": "default" },
      { "harnessName": "hermes", "enabled": true, "role": "available" }
    ]
  }'

harnessTargets is the complete set of enabled harnesses for the agent. Today, the supported harness names are openclaw and hermes. At most one entry may use role: "default", and any enabled set must include exactly one default.

Harness updates follow the same reconciliation path as dashboard harness changes. A ready environment may move into a pending reconciliation state while the runtime applies the new harness selection.

Add a capability

curl -sS -X POST "https://api.getspinup.com/v1/workspaces/acme/agents/support-agent/capabilities" \
  -H "Authorization: Bearer sk_workspace_0123456789abcdef..." \
  -H "Content-Type: application/json" \
  -d '{
    "capability": {
      "kind": "skill",
      "name": "vercel-react-best-practices",
      "source": "vercel-labs/agent-skills",
      "installPlan": {
        "strategy": "skill",
        "manager": "skills_cli",
        "skillName": "vercel-react-best-practices",
        "source": "vercel-labs/agent-skills"
      }
    }
  }'

Capabilities are the public control-plane surface for skills and future installable capabilities. Use PATCH /capabilities/{capabilityId} to update writable fields such as status, and DELETE /capabilities/{capabilityId} to remove one.

Capability updates follow the same reconciliation path as dashboard capability changes. A ready environment may move into a pending reconciliation state while the runtime installs, disables, or removes capabilities.

Manage capabilities

See Capabilities for the concept. Use the control-plane API to list, add, update, or remove declared capability settings.

You can set capability status to declared or disabled. Runtime statuses such as materialized, validated, projected, available, and failed are recorded by Spinup as environment evidence, not written directly through this API.

List capabilities:

curl -sS "https://api.getspinup.com/v1/workspaces/acme/agents/support-agent/capabilities" \
  -H "Authorization: Bearer sk_workspace_0123456789abcdef..."

Add a declared CLI requirement:

curl -sS -X POST "https://api.getspinup.com/v1/workspaces/acme/agents/support-agent/capabilities" \
  -H "Authorization: Bearer sk_workspace_0123456789abcdef..." \
  -H "Content-Type: application/json" \
  -d '{
    "capability": {
      "kind": "cli",
      "name": "ffmpeg",
      "source": "system",
      "status": "declared",
      "validationPlan": {
        "strategy": "executable",
        "executable": "ffmpeg",
        "versionArgs": ["-version"]
      }
    }
  }'

Update or disable a capability:

curl -sS -X PATCH "https://api.getspinup.com/v1/workspaces/acme/agents/support-agent/capabilities/capability_01hxyz..." \
  -H "Authorization: Bearer sk_workspace_0123456789abcdef..." \
  -H "Content-Type: application/json" \
  -d '{ "capability": { "status": "disabled" } }'

Remove a capability:

curl -sS -X DELETE "https://api.getspinup.com/v1/workspaces/acme/agents/support-agent/capabilities/capability_01hxyz..." \
  -H "Authorization: Bearer sk_workspace_0123456789abcdef..."

The response includes the saved state version, the current capability list, and any missing secret requirements. Secret values are never returned.

Delete an agent

curl -sS -X DELETE "https://api.getspinup.com/v1/workspaces/acme/agents/support-agent" \
  -H "Authorization: Bearer sk_workspace_0123456789abcdef..." \
  -H "Content-Type: application/json" \
  -d '{ "confirmationSlug": "support-agent" }'

The confirmation value must match the current agent slug. If the agent has a ready environment, deletion first follows the same teardown path used by the dashboard. If an environment lifecycle operation is in progress, deletion is rejected.