Skip to content
Praxrr

Apply a sync preview

POST
/sync/preview/{previewId}/apply
curl --request POST \
  --url https://example.com/api/v1/sync/preview/example/apply \
  --header 'Content-Type: application/json' \
  --data '{ "sections": [ "qualityProfiles" ] }'

Applies the selected sections from a previously generated preview to the target Arr instance.

Preview generation itself is read-only. Apply atomically claims the preview and selected section rows, then revalidates the exact reviewed instance, Arr family, section subset, effective configuration, desired PCD evidence, live Arr evidence, and material plan. Every selected section must match before any Arr write, confirmed outcome, or Sync History row is created.

A matching review executes through the existing section writers with the bound effective configuration. Private fingerprints, retained configuration, and raw comparison evidence are never returned by this endpoint.

The response reports only the aggregate job/run result. Preview entity changes remain planned evidence and are not per-entity confirmation of what succeeded.

Apply rejects previews that are too stale based on policy:

  • warnings are returned when the preview is older than 5 minutes
  • apply is blocked when staleness exceeds the hard threshold

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
previewId
required
string

Preview snapshot ID

Request Body

Section titled “Request Body”
Media typeapplication/json
object
sections

Optional section filters for preview application

Array<string>
Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles

Responses

Section titled “Responses”

200

Section titled “200”

Selected sections completed successfully or required no work

Media typeapplication/json

Result of executing the preview’s selected sections through the normal sync job path. results describes the aggregate job/run outcome; outcomes carries the confirmed, per-entity terminal results captured from the ACTUAL Arr writes (issue #232) — these, not the planned preview changes, are execution proof.

object
success
required

True when the sync job succeeded or reported that no work was needed.

boolean
results
required
object
status
required

Terminal status returned by the sync job execution.

string
Allowed values: success failure skipped cancelled
output
required

Aggregate human-readable output from the sync job.

string
failure
One of:

Typed, closed, safe failure evidence for Sync Preview generate/apply. Replaces the former free-form error strings. message and recoveryAction are pre-authored safe copy drawn from a closed vocabulary — they NEVER contain raw exception text, Arr response bodies, credentials, hostnames, or stack traces. Full diagnostics live only in the sanitized server logs.

object
code
required

Closed vocabulary of Sync Preview generate/apply failure reasons. Each value is assigned by matching a thrown error’s TYPE/status (never by parsing message text), so no raw exception or secret-shaped string is ever transported:

  • unreachable: the Arr instance could not be reached (network/DNS/connection).
  • timeout: the Arr instance did not respond in time.
  • unauthorized: the Arr instance rejected the API key (HTTP 401/403).
  • notFound: a required Arr resource was not found (HTTP 404).
  • rejected: the Arr instance rejected the request (other HTTP 4xx).
  • serverError: the Arr instance returned a server error (HTTP 5xx).
  • sectionErrors: one or more sections failed to generate (top-level aggregate).
  • executionFailed: the apply sync run did not complete successfully.
  • stale: the preview is too old to apply safely.
  • internalError: an unexpected error occurred (catch-all for untyped failures).
string
Allowed values: unreachable timeout unauthorized notFound rejected serverError sectionErrors executionFailed stale internalError
message
required

Safe, user-facing summary of the failure. Never raw exception or secret text.

string
recoveryAction
required

Actionable next step the operator can take to recover.

string
staleWarning
required
One of:
string
outcomes
required

Confirmed per-entity outcomes captured from the actual Arr writes. Present on both success and partial/failure responses so failed and skipped outcomes are never dropped.

Array<object>

A confirmed, per-entity terminal outcome captured from an actual Arr write (issue #232). Exactly one is produced per attempted entity. Unlike the preview EntityChange (planned intent), status proves what the Arr instance actually did.

object
section
required

Sync section handled by preview generation

string
Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles
arrType
required

Arr type of the target instance — set explicitly by the syncer, never inferred.

string
Allowed values: radarr sonarr lidarr
entityType
required

The kind of entity a confirmed outcome describes.

string
Allowed values: customFormat qualityProfile delayProfile metadataProfile naming mediaSettings qualityDefinitions
name
required

Stable identity — the unsuffixed PCD name (or subsection label for singletons).

string
action
required

The write attempted for an entity (intent). delete is reserved; no syncer emits it yet.

string
Allowed values: create update delete
status
required

Terminal status of a per-entity Arr write, sourced ONLY from the write result: success (resolved), failed (threw), skipped (intentionally not written).

string
Allowed values: success skipped failed
remoteId
required
One of:
string
reason
required
One of:
string
syncHistoryId
required
One of:
integer
Example
{
  "results": {
    "status": "success",
    "failure": {
      "code": "unreachable"
    }
  },
  "outcomes": [
    {
      "section": "qualityProfiles",
      "arrType": "radarr",
      "entityType": "customFormat",
      "action": "create",
      "status": "success"
    }
  ]
}

400

Section titled “400”

Invalid request body

Media typeapplication/json
object
error
required

Error message

string
Examplegenerated
{
  "error": "example"
}

404

Section titled “404”

Preview is missing, evicted, or no longer retained

Media typeapplication/json
object
error
required

Error message

string
Examplegenerated
{
  "error": "example"
}

409

Section titled “409”

Preview lifecycle conflict or a selected section has an active claim

Media typeapplication/json
object
error
required

Error message

string
Examplegenerated
{
  "error": "example"
}

422

Section titled “422”

Preview age policy blocked apply or reviewed evidence was invalidated before writes

Media typeapplication/json
One of:

Safe pre-write rejection when the selected reviewed plan is no longer verifiable. No Arr write was attempted, so this response never contains confirmed outcomes, Sync History identifiers, private fingerprints, retained configuration, or raw PCD/Arr evidence.

object
error
required

Sanitized recovery text stating that nothing was applied and directing the operator to generate and review a new preview.

string
code
required

Closed reason for rejecting reviewed execution before any write:

  • pcd_drift: desired PCD, source, mapping, or reviewed configuration changed
  • arr_drift: material live Arr state changed
  • pcd_and_arr_drift: both PCD-side and live Arr evidence changed
  • scope_drift: the instance, Arr family, capability, or reviewed scope changed
  • unverifiable_review: authoritative evidence could not be read or compared safely
string
Allowed values: pcd_drift arr_drift pcd_and_arr_drift scope_drift unverifiable_review
changedEvidence
required

Bounded changed source classes. Empty for scope or unverifiable failures when PCD-side or Arr-side drift cannot be attributed safely.

Array<string>
0 <= 2 items unique items
Allowed values: pcd arr
changedSections
required

Exact selected sections whose reviewed execution was invalidated.

Array<string>
>= 1 items <= 4 items unique items
Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles
regenerateRequired
required

Always true because an invalidated review cannot be retried.

boolean
staleWarning
required
One of:
string
Example
{
  "code": "pcd_drift",
  "changedEvidence": [
    "pcd"
  ],
  "changedSections": [
    "qualityProfiles"
  ],
  "regenerateRequired": true
}

500

Section titled “500”

The reviewed evidence matched but the write-time sync job failed, or an unexpected internal failure occurred. A matched write-time failure uses SyncPreviewApplyResponse and preserves confirmed outcomes and Sync History correlation when present. An unexpected failure uses the typed, sanitized SyncPreviewApplyErrorResponse.

Media typeapplication/json
One of:

Result of executing the preview’s selected sections through the normal sync job path. results describes the aggregate job/run outcome; outcomes carries the confirmed, per-entity terminal results captured from the ACTUAL Arr writes (issue #232) — these, not the planned preview changes, are execution proof.

object
success
required

True when the sync job succeeded or reported that no work was needed.

boolean
results
required
object
status
required

Terminal status returned by the sync job execution.

string
Allowed values: success failure skipped cancelled
output
required

Aggregate human-readable output from the sync job.

string
failure
One of:

Typed, closed, safe failure evidence for Sync Preview generate/apply. Replaces the former free-form error strings. message and recoveryAction are pre-authored safe copy drawn from a closed vocabulary — they NEVER contain raw exception text, Arr response bodies, credentials, hostnames, or stack traces. Full diagnostics live only in the sanitized server logs.

object
code
required

Closed vocabulary of Sync Preview generate/apply failure reasons. Each value is assigned by matching a thrown error’s TYPE/status (never by parsing message text), so no raw exception or secret-shaped string is ever transported:

  • unreachable: the Arr instance could not be reached (network/DNS/connection).
  • timeout: the Arr instance did not respond in time.
  • unauthorized: the Arr instance rejected the API key (HTTP 401/403).
  • notFound: a required Arr resource was not found (HTTP 404).
  • rejected: the Arr instance rejected the request (other HTTP 4xx).
  • serverError: the Arr instance returned a server error (HTTP 5xx).
  • sectionErrors: one or more sections failed to generate (top-level aggregate).
  • executionFailed: the apply sync run did not complete successfully.
  • stale: the preview is too old to apply safely.
  • internalError: an unexpected error occurred (catch-all for untyped failures).
string
Allowed values: unreachable timeout unauthorized notFound rejected serverError sectionErrors executionFailed stale internalError
message
required

Safe, user-facing summary of the failure. Never raw exception or secret text.

string
recoveryAction
required

Actionable next step the operator can take to recover.

string
staleWarning
required
One of:
string
outcomes
required

Confirmed per-entity outcomes captured from the actual Arr writes. Present on both success and partial/failure responses so failed and skipped outcomes are never dropped.

Array<object>

A confirmed, per-entity terminal outcome captured from an actual Arr write (issue #232). Exactly one is produced per attempted entity. Unlike the preview EntityChange (planned intent), status proves what the Arr instance actually did.

object
section
required

Sync section handled by preview generation

string
Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles
arrType
required

Arr type of the target instance — set explicitly by the syncer, never inferred.

string
Allowed values: radarr sonarr lidarr
entityType
required

The kind of entity a confirmed outcome describes.

string
Allowed values: customFormat qualityProfile delayProfile metadataProfile naming mediaSettings qualityDefinitions
name
required

Stable identity — the unsuffixed PCD name (or subsection label for singletons).

string
action
required

The write attempted for an entity (intent). delete is reserved; no syncer emits it yet.

string
Allowed values: create update delete
status
required

Terminal status of a per-entity Arr write, sourced ONLY from the write result: success (resolved), failed (threw), skipped (intentionally not written).

string
Allowed values: success skipped failed
remoteId
required
One of:
string
reason
required
One of:
string
syncHistoryId
required
One of:
integer
Example
{
  "results": {
    "status": "success",
    "failure": {
      "code": "unreachable"
    }
  },
  "outcomes": [
    {
      "section": "qualityProfiles",
      "arrType": "radarr",
      "entityType": "customFormat",
      "action": "create",
      "status": "success"
    }
  ]
}