Update a component on websites

POST

https://api.modulards.com/api/public/v1/components/:component/upgrade

POST

/api/public/v1/components/:component/upgrade

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
  ]
}'

202Update a component on websites

{
  "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.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 website is not connected; connect it first.",
        "reason_code": "SITE_UNREACHABLE",
        "site_action_id": null,
        "site_id": 13,
        "site_name": "Blog"
      }
    ],
    "warnings": [
      "A direct update has no rollback: a failed update leaves each website as the update left it. Take a backup first if the website matters."
    ]
  }
}

Updates one plugin, theme or WordPress version to its newest version on the websites you list in sites. By default it is a safe update: Modular DS takes a backup, updates, compares the website visually before and after, and rolls back automatically if the comparison fails. A direct update skips those safeguards. Use “Approve or roll back a safe update” to give your verdict on a safe update that waits for you; if nobody decides within 7 days of the moment it starts waiting, Modular DS approves it automatically.

It creates one site action per website that passes the checks. The work finishes later: see Writes and asynchronous operations. Follow the site actions with “List site actions”. Websites that cannot be processed are reported in meta.skipped, each with a reason_code and a message, and do not fail the call. A direct update, and a safe update with is_manual, also add a warning to the answer. A website is skipped when it is not connected, does not have the component, hides its update notice, is already up to date, is a multisite sub-site, already has an action on this item or too many pending or running actions, or, for a safe update of a plugin, when the plugin is not active.

Body

sites (array of integers, required): ids of the websites to act on, 1 to 50.
action (safe_upgrade or upgrade, optional): safe_upgrade for a safe update, or upgrade for a direct update with no rollback. Default safe_upgrade.
is_manual (boolean, optional): only with safe_upgrade: when true, each website stops after the update and waits for your verdict instead of being validated automatically, and is approved automatically if nobody decides within 7 days. Default false.
clean_cache (boolean, optional): clear each website’s cache after updating. Default: the Updater setting of your organization.
scheduled_at (date-time, optional): when to run the update. It must be in the future and at most 14 days ahead; omit it to run now.

Errors

404: the component is not installed on any of your websites.
422: sites is invalid, scheduled_at is not in the future or more than 14 days ahead, or is_manual is sent with action upgrade.

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