Writes and asynchronous operations

Create, update and delete

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

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 when there is one, 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).
• 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.

Polling

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