Writes and asynchronous operations

Create, update and delete

Write requests send a JSON body and need a read and write token (see Authentication).

Updates are documented as PATCH. PUT is accepted on the same URLs and does exactly the same: both change only the fields you send.

Creating a resource that is later read at its own URL (a website, a tag, a team, a client, a contact, a global configuration) carries the Location header. Some creations answer 201 without it because what they create has no URL of its own: file uploads, contact methods, the integrations of a notification configuration (POST /alerts/{alert}/integrations, which creates the Slack or Discord integration or replaces its URL) and the tasks created by POST /site-tasks (which answers 200 with an empty data when every website was skipped). Requests that perform an action rather than create a resource document their own answer: creating a connection plugin download, generating a website login link, clearing a website cache and verifying a website connection answer 200.

Asynchronous operations

Some operations reach the WordPress installation of each website, or copy data, and take seconds to minutes. They answer 202 Accepted as soon as the work is queued:

The 202 document lists the resources created, one per website that accepted the work, and the websites that were skipped:

{
  "data": [
    { "type": "site-actions", "id": "9181", "attributes": { "status": "pending" } }
  ],
  "meta": {
    "skipped": [
      {
        "site_id": 42,
        "site_name": "Shop",
        "site_action_id": null,
        "reason_code": "SITE_UNREACHABLE",
        "message": "This website is not connected; connect it first."
      }
    ]
  },
  "jsonapi": { "version": "1.1" }
}

• data can be empty: when every website was skipped, the answer is still 202.
• Each entry of meta.skipped names the website (site_id, site_name), carries the id of the related target (site_action_id above, backup_id, site_scan_id and so on), which is null when there is none, a machine-readable reason_code and a readable message. reason_code is one of SITE_UNREACHABLE, UNSUPPORTED, NOT_FOUND, PERMISSION_DENIED, CONFLICT, ALREADY_APPLIED and QUOTA_EXCEEDED; new codes can be added (see Versioning).
• site_id, site_name and the target id can be null: an entry with reason_code PERMISSION_DENIED names a website or a target outside your access without disclosing its name (and, for a target, without its website).
• meta.warnings appears when the work was queued with something you should know about.

202 means queued, not done. Follow each created resource by its id until it settles.

Following a site action

Read the action with its show endpoint and watch status:

Following a backup

A backup copy takes minutes. Read it, or list backups filtered by phase, and watch phase:

Restorations can be read through the API, but they are started from the dashboard.

Synchronous bulk answers

Writes over a selection that change data in place are done before the answer is built, so they answer 200 OK instead of 202. This covers assigning websites to a global configuration (the sites/sync endpoints of Uptime Monitor, Backups, Malware Scanner and Broken Links Checker), syncing or detaching the websites and the contacts of a notification configuration (POST /alerts/{alert}/sites/sync, /sites/detach, /contacts/sync and /contacts/detach), ignoring or restoring Broken Links Checker findings and pages in bulk, and hiding or showing a component on a selection of websites (PATCH /components/{component}/visibility). The document has no data: everything sits under meta.

{
  "meta": {
    "status": "applied",
    "updated": [
      { "site_id": 41, "site_name": "Fresh", "site_preset_uptime_id": 7 }
    ],
    "skipped": [
      {
        "site_id": 42,
        "site_name": "Attached",
        "site_preset_uptime_id": 8,
        "reason_code": "ALREADY_APPLIED",
        "message": "This website already uses this Uptime Monitor global configuration."
      }
    ]
  },
  "jsonapi": { "version": "1.1" }
}

• meta.status is applied when at least one entry changed and skipped when nothing did.
• meta.updated lists what changed, and meta.skipped what was refused, with the same reason_code and message as in the 202 document. Both can be empty. The key of the changed entries and the name of the id inside each entry depend on the endpoint (for example site_preset_uptime_id above, or issue_id for findings).
• There is nothing to poll: the change is already made when the answer arrives.

Polling

Poll gently: a few seconds between reads of the same resource is enough, and every read counts towards your rate limit.