Upgrade component | Modular DS

curl -X POST https://api.modulards.com/api/public/v1/components/component/upgrade \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "action": "upgrade",
  "sites": [
    12
  ]
}'

{
  "data": [
    {
      "attributes": {
        "completed_at": null,
        "created_at": "2026-09-21T09:00:00.000000Z",
        "created_by": 501,
        "origin": "agent",
        "site_id": 12,
        "started_at": null,
        "status": "pending",
        "type": "manager.safe_upgrade",
        "updated_at": "2026-09-21T09:00:00.000000Z"
      },
      "id": "5011",
      "links": {
        "self": "{{base_url}}/api/public/v1/site-actions/5011"
      },
      "type": "site-actions"
    }
  ],
  "jsonapi": {
    "version": "1.1"
  },
  "meta": {
    "skipped": [
      {
        "message": "This site is not connected; connect it before upgrading this component.",
        "reason_code": "SITE_UNREACHABLE",
        "site_action_id": null,
        "site_id": 13,
        "site_name": "Blog"
      }
    ]
  }
}

Upgrades one component (plugin, theme or WordPress core) to its newest version on the selection: one manager.upgrade/manager.safe_upgrade Site Action per accepted website.

Body parameters:

sites (integer array, required): exact ids, 1 to 200.
action (string, default safe_upgrade): safe_upgrade (backup, update, visual check, automatic rollback) or upgrade (direct, no rollback).
is_manual (boolean 1/0, default 0): action: safe_upgrade only; 1 stops each website at REQUIRES_ACTION for a human verdict instead of auto-validating.
clean_cache (boolean 1/0, default: the account’s updates setting): clear each website’s cache after updating.
scheduled_at (string, ISO 8601 datetime): must be in the future (after:now); omit to run now.

202 with the created site-actions documents under data and meta.skipped: one entry per website the preflight refused, {site_id, site_name, site_action_id, reason_code, message}. site_action_id is always null in these entries (a refused website never had an action created); site_name is null for PERMISSION_DENIED (an id the token cannot reach). A disconnected website answers reason_code: SITE_UNREACHABLE. data: [] is still a 202.

422: sites missing/empty/over 200/unknown id; scheduled_at not in the future.
404: {component} does not exist or is not reachable from the token’s organization.
403: a read-only token.

Upgrades one component (plugin, theme or WordPress core) to its newest version on the selection: one `manager.upgrade`/`manager.safe_upgrade` Site Action per accepted website. Body parameters: - `sites` (integer array, required): exact ids, 1 to 200. - `action` (string, default `safe_upgrade`): `safe_upgrade` (backup, update, visual check, automatic rollback) or `upgrade` (direct, no rollback). - `is_manual` (boolean `1`/`0`, default `0`): `action: safe_upgrade` only; `1` stops each website at `REQUIRES_ACTION` for a human verdict instead of auto-validating. - `clean_cache` (boolean `1`/`0`, default: the account's updates setting): clear each website's cache after updating. - `scheduled_at` (string, ISO 8601 datetime): must be in the future (`after:now`); omit to run now. 202 with the created `site-actions` documents under `data` and `meta.skipped`: one entry per website the preflight refused, `{site_id, site_name, site_action_id, reason_code, message}`. `site_action_id` is always null in these entries (a refused website never had an action created); `site_name` is null for `PERMISSION_DENIED` (an id the token cannot reach). A disconnected website answers `reason_code: SITE_UNREACHABLE`. `data: []` is still a 202. - **422**: `sites` missing/empty/over 200/unknown id; `scheduled_at` not in the future. - **404**: `{component}` does not exist or is not reachable from the token's organization. - **403**: a read-only token.

Authentication

AuthorizationBearer

Personal access token created in the Modular DS dashboard; read-only tokens can only call GET endpoints.

Path parameters

componentstringRequired

Request

This endpoint expects an object.

actionstringOptional

siteslist of doublesOptional

Response

202 Accepted - one upgrade launched, one website skipped

datalist of objectsOptional

jsonapiobjectOptional

metaobjectOptional

Upgrades one component (plugin, theme or WordPress core) to its newest version on the selection: one manager.upgrade/manager.safe_upgrade Site Action per accepted website.

Body parameters:

sites (integer array, required): exact ids, 1 to 200.
action (string, default safe_upgrade): safe_upgrade (backup, update, visual check, automatic rollback) or upgrade (direct, no rollback).
is_manual (boolean 1/0, default 0): action: safe_upgrade only; 1 stops each website at REQUIRES_ACTION for a human verdict instead of auto-validating.
clean_cache (boolean 1/0, default: the account’s updates setting): clear each website’s cache after updating.
scheduled_at (string, ISO 8601 datetime): must be in the future (after:now); omit to run now.

422: sites missing/empty/over 200/unknown id; scheduled_at not in the future.
404: {component} does not exist or is not reachable from the token’s organization.
403: a read-only token.