Skip to content
Praxrr

Generate a sync preview

POST
/sync/preview
curl --request POST \
  --url https://example.com/api/v1/sync/preview \
  --header 'Content-Type: application/json' \
  --data '{ "instanceId": 1, "sections": [ "qualityProfiles" ], "sectionConfigs": { "qualityProfiles": "example", "delayProfiles": { "databaseId": 1, "profileName": "example" }, "mediaManagement": { "namingDatabaseId": 1, "namingConfigName": "example", "qualityDefinitionsDatabaseId": 1, "qualityDefinitionsConfigName": "example", "mediaSettingsDatabaseId": 1, "mediaSettingsConfigName": "example" }, "metadataProfiles": { "databaseId": 1, "profileName": "example" } } }'

Computes a read-only preview of the sync changes for an Arr instance.

This endpoint performs no writes. It only reads from PCD and Arr GET endpoints to compare desired versus current state, then stores a preview snapshot for later retrieval or application. Optional transient sectionConfigs are treated as bound reviewed execution state: their normalized effective values are retained privately with the expiring preview and reused during reviewed apply.

If no sections are provided, all configured sections for the instance are included.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
instanceId
required

Arr instance ID to preview

integer
sections

Optional section filters for preview generation

Array<string>
Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles
sectionConfigs

Optional transient configuration overrides used to materialize the selected preview sections. These values are bound as reviewed execution state: apply revalidates and executes with the same effective configuration instead of silently falling back to newly saved configuration. The server retains the normalized values only in the private, expiring preview envelope; they are never included in preview or apply responses.

object
<= 4 properties
qualityProfiles

Effective quality-profile section configuration to review and bind.

delayProfiles

Complete transient delay/metadata profile selection. Both fields must be null to select no profile, or both must contain a valid selection.

object
databaseId
required
integer
nullable >= 1
profileName
required
string
nullable >= 1 characters /.*\S.*/
Any of:
object
databaseId
integer
>= 1
profileName
string
>= 1 characters /.*\S.*/
mediaManagement

Complete transient media-management selection. Each database/name pair must either be null/null or contain a positive database ID and non-empty name.

object
namingDatabaseId
required
integer
nullable >= 1
namingConfigName
required
string
nullable >= 1 characters /.*\S.*/
qualityDefinitionsDatabaseId
required
integer
nullable >= 1
qualityDefinitionsConfigName
required
string
nullable >= 1 characters /.*\S.*/
mediaSettingsDatabaseId
required
integer
nullable >= 1
mediaSettingsConfigName
required
string
nullable >= 1 characters /.*\S.*/
Any of:
object
namingDatabaseId
integer
>= 1
namingConfigName
string
>= 1 characters /.*\S.*/
Any of:
object
qualityDefinitionsDatabaseId
integer
>= 1
qualityDefinitionsConfigName
string
>= 1 characters /.*\S.*/
Any of:
object
mediaSettingsDatabaseId
integer
>= 1
mediaSettingsConfigName
string
>= 1 characters /.*\S.*/
metadataProfiles

Complete transient delay/metadata profile selection. Both fields must be null to select no profile, or both must contain a valid selection.

object
databaseId
required
integer
nullable >= 1
profileName
required
string
nullable >= 1 characters /.*\S.*/
Any of:
object
databaseId
integer
>= 1
profileName
string
>= 1 characters /.*\S.*/

Responses

Section titled “Responses”

200

Section titled “200”

Preview generated

Media typeapplication/json
object
id
required

Preview identifier

string
instanceId
required

Target Arr instance ID

integer
instanceName
required

Target Arr instance name

string
arrType
required

Arr instance family

string
Allowed values: radarr sonarr lidarr
createdAt
required

ISO 8601 timestamp when preview was generated

string format: date-time
expiresAt
required

ISO 8601 timestamp when preview becomes expired

string format: date-time
status
required

Preview lifecycle state:

  • generating: build in progress
  • ready: preview fully materialized and runnable
  • applying: preview is being executed as sync
  • applied: execution succeeded
  • failed: generation or execution failed
  • expired: staleness TTL elapsed
string
Allowed values: generating ready applying applied failed expired
failure
required
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
sections
required

Sections included in preview

Array<string>
Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles
sectionOutcomes
required

Per-section preview generation status used to enforce safe apply behavior.

Array<object>
object
section
required

Sync section handled by preview generation

string
Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles
skipped
required

True when the section had no config to preview and was skipped.

boolean
failure
required
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
qualityProfiles
required
One of:
object
section
required
string
Allowed values: qualityProfiles
customFormats
required

Custom-format change set

Array<object>
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
qualityProfiles
required

Quality-profile change set

Array<object>
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
delayProfiles
required
One of:
object
section
required
string
Allowed values: delayProfiles
profile
required
One of:
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
mediaManagement
required
One of:
object
section
required
string
Allowed values: mediaManagement
naming
required
One of:
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
qualityDefinitions
required

Quality definition change set

Array<object>
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
mediaSettings
required
One of:
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
metadataProfiles
required
One of:
object
section
required
string
Allowed values: metadataProfiles
profile
required
One of:
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
summary
required
object
totalCreates
required

Number of create actions

integer
totalUpdates
required

Number of update actions

integer
totalDeletes
required

Number of delete actions

integer
totalUnchanged
required

Number of unchanged entities

integer
Example
{
  "arrType": "radarr",
  "status": "generating",
  "failure": {
    "code": "unreachable"
  },
  "sections": [
    "qualityProfiles"
  ],
  "sectionOutcomes": [
    {
      "section": "qualityProfiles",
      "failure": {
        "code": "unreachable"
      }
    }
  ],
  "qualityProfiles": {
    "section": "qualityProfiles",
    "customFormats": [
      {
        "action": "create",
        "fields": [
          {
            "type": "added"
          }
        ]
      }
    ],
    "qualityProfiles": [
      {
        "action": "create",
        "fields": [
          {
            "type": "added"
          }
        ]
      }
    ]
  },
  "delayProfiles": {
    "section": "delayProfiles",
    "profile": {
      "action": "create",
      "fields": [
        {
          "type": "added"
        }
      ]
    }
  },
  "mediaManagement": {
    "section": "mediaManagement",
    "naming": {
      "action": "create",
      "fields": [
        {
          "type": "added"
        }
      ]
    },
    "qualityDefinitions": [
      {
        "action": "create",
        "fields": [
          {
            "type": "added"
          }
        ]
      }
    ],
    "mediaSettings": {
      "action": "create",
      "fields": [
        {
          "type": "added"
        }
      ]
    }
  },
  "metadataProfiles": {
    "section": "metadataProfiles",
    "profile": {
      "action": "create",
      "fields": [
        {
          "type": "added"
        }
      ]
    }
  }
}

400

Section titled “400”

Invalid instanceId, unsupported section, or request body

Media typeapplication/json
object
error
required

Error message

string
Examplegenerated
{
  "error": "example"
}

404

Section titled “404”

Instance not found

Media typeapplication/json
object
error
required

Error message

string
Examplegenerated
{
  "error": "example"
}

409

Section titled “409”

Preview for this instance is already generating

Media typeapplication/json
object
error
required

Error message

string
Examplegenerated
{
  "error": "example"
}

429

Section titled “429”

Preview creation is rate-limited or preview-store capacity is exhausted

Media typeapplication/json
object
error
required

Error message

string
Examplegenerated
{
  "error": "example"
}

500

Section titled “500”

Preview generation failed. The failed preview snapshot is returned with status: failed and a typed, safe failure reason — no raw exception text.

Media typeapplication/json
object
id
required

Preview identifier

string
instanceId
required

Target Arr instance ID

integer
instanceName
required

Target Arr instance name

string
arrType
required

Arr instance family

string
Allowed values: radarr sonarr lidarr
createdAt
required

ISO 8601 timestamp when preview was generated

string format: date-time
expiresAt
required

ISO 8601 timestamp when preview becomes expired

string format: date-time
status
required

Preview lifecycle state:

  • generating: build in progress
  • ready: preview fully materialized and runnable
  • applying: preview is being executed as sync
  • applied: execution succeeded
  • failed: generation or execution failed
  • expired: staleness TTL elapsed
string
Allowed values: generating ready applying applied failed expired
failure
required
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
sections
required

Sections included in preview

Array<string>
Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles
sectionOutcomes
required

Per-section preview generation status used to enforce safe apply behavior.

Array<object>
object
section
required

Sync section handled by preview generation

string
Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles
skipped
required

True when the section had no config to preview and was skipped.

boolean
failure
required
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
qualityProfiles
required
One of:
object
section
required
string
Allowed values: qualityProfiles
customFormats
required

Custom-format change set

Array<object>
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
qualityProfiles
required

Quality-profile change set

Array<object>
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
delayProfiles
required
One of:
object
section
required
string
Allowed values: delayProfiles
profile
required
One of:
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
mediaManagement
required
One of:
object
section
required
string
Allowed values: mediaManagement
naming
required
One of:
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
qualityDefinitions
required

Quality definition change set

Array<object>
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
mediaSettings
required
One of:
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
metadataProfiles
required
One of:
object
section
required
string
Allowed values: metadataProfiles
profile
required
One of:
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
summary
required
object
totalCreates
required

Number of create actions

integer
totalUpdates
required

Number of update actions

integer
totalDeletes
required

Number of delete actions

integer
totalUnchanged
required

Number of unchanged entities

integer
Example
{
  "arrType": "radarr",
  "status": "generating",
  "failure": {
    "code": "unreachable"
  },
  "sections": [
    "qualityProfiles"
  ],
  "sectionOutcomes": [
    {
      "section": "qualityProfiles",
      "failure": {
        "code": "unreachable"
      }
    }
  ],
  "qualityProfiles": {
    "section": "qualityProfiles",
    "customFormats": [
      {
        "action": "create",
        "fields": [
          {
            "type": "added"
          }
        ]
      }
    ],
    "qualityProfiles": [
      {
        "action": "create",
        "fields": [
          {
            "type": "added"
          }
        ]
      }
    ]
  },
  "delayProfiles": {
    "section": "delayProfiles",
    "profile": {
      "action": "create",
      "fields": [
        {
          "type": "added"
        }
      ]
    }
  },
  "mediaManagement": {
    "section": "mediaManagement",
    "naming": {
      "action": "create",
      "fields": [
        {
          "type": "added"
        }
      ]
    },
    "qualityDefinitions": [
      {
        "action": "create",
        "fields": [
          {
            "type": "added"
          }
        ]
      }
    ],
    "mediaSettings": {
      "action": "create",
      "fields": [
        {
          "type": "added"
        }
      ]
    }
  },
  "metadataProfiles": {
    "section": "metadataProfiles",
    "profile": {
      "action": "create",
      "fields": [
        {
          "type": "added"
        }
      ]
    }
  }
}