Workspace preferences

Endpoint: /api/workspaces/preferences/

Read and update the workspace-wide preferences shown under Workspace settings → General, including the agent update policy. There is one preferences object per workspace.

GET /api/workspaces/preferences/-/

{
  "front_url": "https://your-workspace.us1.alpacon.io",
  "country": "US",
  "language": "en",
  "timezone": "America/New_York",
  "invite_ttl": 172800,
  "enabled_extensions": ["metrics"],
  "websh_session_timeout": 86400,
  "agent_rollout_policy": {
    "mode": "latest",
    "window": {
      "days": [0, 1, 2, 3, 4],
      "start_hour": 2,
      "length_hours": 4,
      "timezone": "America/New_York"
    }
  },
  "auto_agent_upgrade": true,
  "package_proxy": null,
  "billing_email": "billing@example.com"
}

PATCH /api/workspaces/preferences/-/

{
  "agent_rollout_policy": {
    "window": {
      "days": [5, 6],
      "start_hour": 22,
      "length_hours": 6,
      "timezone": "Asia/Seoul"
    }
  }
}

Agent rollout policy#

agent_rollout_policy decides whether Alpacon upgrades agents in this workspace automatically, and in which hours:

{
  "mode": "latest",
  "window": {
    "days": [0, 1, 2, 3, 4, 5, 6],
    "start_hour": 0,
    "length_hours": 24,
    "timezone": "UTC"
  }
}

The example above is the default: latest, with a window open every day for 24 hours, so upgrades can start at any time.

A write may name only part of the object—just mode, or just one window field—and whatever it leaves out keeps its current value. A read always returns the whole object.

Alpacon plans each week’s automatic upgrades on Monday, inside the window. A change to the window takes effect from the next Monday’s plan; upgrades already planned for hours that now fall outside it wait for the next open hour.

Every server’s agent_upgrade_policy field in the Servers API carries the current mode.

auto_agent_upgrade (deprecated)#

auto_agent_upgrade is the boolean that agent_rollout_policy replaced. It stays readable and writable for one more release, then it’s removed. Use agent_rollout_policy instead.

• Read: true unless mode is manual.
• Write true: sets mode to latest, unless the mode is already automatic (latest or n_minus_1), in which case nothing changes.
• Write false: sets mode to manual.
• Neither write changes the window.
• When a request names both fields, agent_rollout_policy wins and auto_agent_upgrade is ignored.
• It accepts a JSON boolean only; any other value is refused with invalid_input.

These rules describe the REST API. For the MCP update_workspace_preferences tool, pass agent_rollout_policy directly; see the MCP agent rollout policy reference.

Error responses#