OpenAPI JSON

Handle asynchronous jobs

Backup downloads, restores, migrations, staging creation, and several maintenance actions return a task instead of waiting for the work to finish.

1. Start the operation

The operation response includes a task identifier. For example, Create a staging site returns the task created for staging-site creation.

Save that task ID immediately. Do not start the operation again just because the first response is still running.

2. Poll the task

Use Show a task with the returned ID:

curl --request GET \
  --url https://api.blogvault.net/api/v6/tasks/TASK_ID \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json'

The task model includes status, request details, site-level progress, and step-level progress when available. List tasks is useful when recovering a task ID or reviewing recent work.

3. Classify the state

The documented task states are initializing, running, completed, cancelled, failed, and aborted. Treat completed, cancelled, failed, and aborted as terminal.

  • completed: continue to the resource or result described by the operation.
  • failed: surface the task error and decide whether the user should change the request.
  • cancelled or aborted: stop polling and show the final state.

Polling guidance

Start with a short delay, then back off. A practical client can poll after 1, 2, 4, 8, and 15 seconds, then use a slower interval until a bounded timeout. Respect 429 responses and the account’s rate-limit headers.

For a restore or migration, do not assume a timeout means failure. Retrieve the task once more, record the final task ID, and let an operator decide whether to retry.