Skip to main content

Event

The full set of /api/v1/events SSE event types.

event stringrequired

The full set of /api/v1/events SSE event types.

Possible values: [job_progress, disk_state, container_state, notification, catalog]

data objectrequired
idstring<uuid>required
typeJobTyperequired

Every job type, each belonging to one of the mutually exclusive job classes.

Possible values: [sync, scrub, fix, check, rebalance, evacuation, share_relocation, mover, vm_disk_relocation, disk_format, disk_add, disk_remove, disk_replace, disk_upgrade_data, disk_upgrade_parity, pool_remount, migration_scan, migration_import, migration_verify, migration_parity, appdata_backup, appdata_restore, appdata_restore_preview, restore_drill, config_backup, container_update, container_recreate, stack_start, acme_issue, vm_start, vm_stop, vm_create, vm_delete, vm_snapshot, vm_clone, vm_migration_import]

classJobClassrequired

The mutually exclusive job class the scheduler enforces.

Possible values: [parity, array_write, topology, service, vm]

statusJobStatusrequired

interrupted is set on an in-flight job by a daemon restart and is never cleared automatically — resuming or re-running it is always an explicit user action.

Possible values: [queued, running, interrupted, succeeded, failed, cancelled]

progress(integer | null)<int32>nullable

Null when the job type or tool reports no meaningful percentage.

Possible values: >= 0 and <= 100

resumablebooleanrequired

Whether this job type persists a checkpoint to resume from.

cancellablebooleanrequired

Whether the underlying tool honestly supports cancelling this job.

createdAtstring<date-time>required
startedAt(string | null)<date-time>nullable
finishedAt(string | null)<date-time>nullable
error object
oneOf
codestringrequired

A stable, machine-readable identifier, e.g. job_not_found. Every auth-related operation can also return one of: setup_required (409 — no admin account exists yet; every operation but getSetupStatus/createFirstAdmin refuses with this while it's true), setup_complete (409, createFirstAdmin — an admin account already exists), rate_limited (429 — the account or source address is currently locked out after repeated failures; message gives a retry-after), too_busy (503 — the bounded password-hashing worker pool is saturated; safe to retry shortly), invalid_credentials (401, login — an unknown username or wrong password, deliberately indistinguishable), totp_required (401, login — the account has TOTP enrolled and no code was supplied), totp_invalid (401, login and confirmTotp — a code was supplied but is wrong, expired or already used; a missing login code is totp_required instead, never this), totp_reverify_required (403, enrollTotp — TOTP is already active and the caller didn't prove they still hold the account: no password or code was supplied, or the one supplied was wrong; 403 rather than 401 since the session itself is valid, only the reverification is missing or failed), totp_reverify_ambiguous (400, enrollTotp — TOTP is already active and both the current password and a current TOTP code were supplied; supply exactly one), totp_not_pending (409, confirmTotp — no pending secret to confirm), unauthorized (401 — no credential, or one that no longer validates), forbidden (403 — a valid credential whose role doesn't satisfy the operation), no_session (404 — the Unix socket's peer-credential-trusted local access has no signed-in user for an operation that needs one), request_too_large (413 — the request body exceeded the server's size limit), bad_request (400 — the request body could not be decoded), not_found (404 — no such API route), api_token_not_found (404, revokeApiToken — no token with that id), invalid_token_role (400, createApiToken — the requested role is neither admin nor viewer; share-only is never a valid token role), share_only_no_api_token (403, createApiToken — the target account has SMB/NFS access only and no API access at all) and token_role_exceeds_account (403, createApiToken — the requested role is wider than the target account's own role; a token can only narrow an account's access, never widen it).

messagestringrequired

A human-readable explanation, safe to show in the UI or CLI.

details object

Optional structured context, e.g. which field failed validation.

property name*any

Optional structured context, e.g. which field failed validation.

Event
{
  "event": "job_progress",
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "sync",
    "class": "parity",
    "status": "queued",
    "progress": 0,
    "resumable": true,
    "cancellable": true,
    "createdAt": "2024-07-29T15:51:28.071Z",
    "startedAt": "2024-07-29T15:51:28.071Z",
    "finishedAt": "2024-07-29T15:51:28.071Z",
    "error": {
      "code": "string",
      "message": "string",
      "details": {}
    }
  }
}