Preview incoming upstream PCD changes

GET

/pcd/{databaseId}/incoming/preview

curl --request GET \
  --url https://example.com/api/v1/pcd/1/incoming/preview

• API v1

Read-only preview of what pulling the upstream branch would change per entity, and which published local user ops would conflict (or be auto-aligned) under the database’s conflict strategy. Fetches only the remote-tracking ref origin/<branch>; never changes pcd_ops, pcd_op_history, the clone’s HEAD, or its working tree. Does not contact any Arr instance. Local-path sources return available=false. Fails closed: no partial preview.

Parameters

Path Parameters

databaseId

required

integer

>= 1

PCD database ID

Responses

200

Incoming preview

Media typeapplication/json

Read-only preview of what pulling the upstream changes would do to the PCD, per entity, with the predicted fate of local user ops. Never modifies pcd_ops, pcd_op_history, the clone’s HEAD, or its working tree. sections diff the current base state against the incoming base state (user ops excluded); predictedConflicts come from a dry replay of published user ops over the incoming state.

object

databaseId

required

integer

available

required

False when the database source cannot be previewed (for example a local-path source)

boolean

unavailableReason

required

Local_source when available is false, otherwise null

string

nullable

Allowed values: local_source

branch

required

string

nullable

hasUpdates

required

boolean

commitsBehind

required

integer

commitsAhead

required

Local commits not on the remote branch; when above zero the pull may not fast-forward

integer

commits

required

Array<object>

One upstream commit that a pull would bring in

object

hash

required

string

shortHash

required

string

message

required

string

author

required

string

authorEmail

required

string

date

required

string

files

required

Array<string>

conflictStrategy

required

Per-database strategy applied to conflicting local user ops when upstream changes are pulled

string

Allowed values: override align ask

sections

required

Array<object>

A group of entity changes for one resolved-config family. Reuses the sync-preview EntityChange/FieldChange shapes. Diff direction is PCD-to-PCD: each FieldChange.current is the CURRENT PCD desired-state and FieldChange.desired is the SNAPSHOT restore-target state (NOT live Arr state).

object

title

required

Human-readable family label (e.g. “Custom Formats”, “Naming (radarr)”)

string

entityType

required

Namespaced entity type; per-arr families are “${entityType}:${arrType}”

string

arrType

required

string

nullable

Allowed values: radarr sonarr lidarr

changes

required

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

managed

True only for deletes of entities Praxrr created (ownership ledger); only these execute on reviewed apply.

boolean

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

string

number

number

integer

integer

boolean

boolean

array

array

object

object

key

additional properties

any

unknown

desired

required

Any of:

string

string

number

number

integer

integer

boolean

boolean

array

array

object

object

key

additional properties

any

unknown

summary

required

object

totalCreates

required

integer

totalUpdates

required

integer

totalDeletes

required

integer

totalUnchanged

required

integer

predictedConflicts

required

Array<object>

Predicted fate of one published local user op when replayed over the incoming base. Predictions match the conflicts the pull’s cache build records in the op history (not the later automatic override resolution).

object

opId

required

integer

entityType

required

Entity type from the op metadata, when recorded

string

nullable

entityName

required

Entity name from the op metadata, when recorded

string

nullable

operation

required

string

nullable

Allowed values: create update delete

kind

required

Conflict = the op will be recorded as conflicted; aligned = the op is redundant upstream and will be dropped

string

Allowed values: conflict aligned

predictedStatus

required

string

Allowed values: conflicted conflicted_pending dropped

conflictReason

required

Guard_mismatch, duplicate_key, missing_target, or aligned

string

decision

required

Value-guard decision, for example rowcount_zero_conflict

string

nullable

autoAlignRule

required

string

nullable

strategy

required

Per-database strategy applied to conflicting local user ops when upstream changes are pulled

string

Allowed values: override align ask

autoResolvable

required

True only when the pull’s automatic override will resolve this conflict itself: strategy override, predictedStatus conflicted, an enabled database, and an override handler for the op (delete ops, or an entity type with an override handler). False for aligned entries and for conflicts that need a user decision.

boolean

predictedErrors

required

Array<object>

A published local user op that would fail with a non-conflict error against the incoming base

object

opId

required

integer

error

required

string

currentStateHash

required

Published-op fingerprint at preview time

string

nullable

currentHead

required

string

nullable

incomingHead

required

string

nullable

Example

{
  "unavailableReason": "local_source",
  "conflictStrategy": "override",
  "sections": [
    {
      "arrType": "radarr",
      "changes": [
        {
          "action": "create",
          "fields": [
            {
              "type": "added"
            }
          ]
        }
      ]
    }
  ],
  "predictedConflicts": [
    {
      "operation": "create",
      "kind": "conflict",
      "predictedStatus": "conflicted",
      "strategy": "override"
    }
  ]
}

400

Invalid parameters

Media typeapplication/json

object

error

required

string

code

Optional machine-readable error code, for example sync_in_progress or preview_stale

string

Example^generated

{
  "error": "example",
  "code": "example"
}

404

Database not found

Media typeapplication/json

object

error

required

string

code

Optional machine-readable error code, for example sync_in_progress or preview_stale

string

Example^generated

{
  "error": "example",
  "code": "example"
}

409

A sync is running (code sync_in_progress) or local state changed while building the preview (code preview_stale)

Media typeapplication/json

object

error

required

string

code

Optional machine-readable error code, for example sync_in_progress or preview_stale

string

Example^generated

{
  "error": "example",
  "code": "example"
}

500

Failed to generate the incoming preview

Media typeapplication/json

object

error

required

string

code

Optional machine-readable error code, for example sync_in_progress or preview_stale

string

Example^generated

{
  "error": "example",
  "code": "example"
}

502

Upstream fetch or extraction failed (code fetch_failed or incoming_unavailable)

Media typeapplication/json

object

error

required

string

code

Optional machine-readable error code, for example sync_in_progress or preview_stale

string

Example^generated

{
  "error": "example",
  "code": "example"
}