Start a canary rollout

POST

/canary/rollouts

curl --request POST \
  --url https://example.com/api/v1/canary/rollouts \
  --header 'Content-Type: application/json' \
  --data '{ "arrType": "radarr", "canaryInstanceId": 1, "sections": [ "qualityProfiles" ], "maxBatchSize": 1, "partialPolicy": "gate" }'

• API v1

Runs the canary sync inline and persists the rollout with durable, explicit remaining-target preview evidence. The staged response contains the evidence in its rollout as either complete available previews or unavailable with a safe reason and recovery action; array length is never used to infer availability. When only one eligible target exists the staged flow is auto-skipped and a plain sync result is returned instead. The response is discriminated on skipped.

Request Body

Media typeapplication/json

object

arrType

required

The Arr app the rollout is scoped to. Required — a rollout targets exactly one arr_type.

string

Allowed values: radarr sonarr lidarr

canaryInstanceId

Explicit canary instance. Highest selection precedence.

integer

sections

Optional section filters. Omit for all configured sections.

Array<string>

Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles

maxBatchSize

Max remaining instances synced per batch. Falls back to the settings default.

integer

>= 1

partialPolicy

How a partial canary outcome is treated:

• gate: pass-with-warning; continue to the verification gate
• abort: treat as failure; remaining instances are never touched

string

Allowed values: gate abort

Responses

200

Canary started (staged) or auto-skipped (plain sync)

Media typeapplication/json

One of:

object

Returned when a single eligible same-arr_type target auto-skips the staged flow.

object

skipped

required

boolean

result

required

Verbatim executeSyncJob return, surfaced when a start auto-skips to a plain sync.

object

status

required

Per-instance outcome status following JobRunStatus semantics.

string

Allowed values: success failure skipped cancelled

output

string

error

string

rescheduleAt

One of:

string

string format: date-time

null

null

object

Returned when the canary passed and the rollout is awaiting confirmation. The rollout carries the persisted remaining-preview evidence used by detail reads and promotion authorization.

object

skipped

required

boolean

rollout

required

object

id

required

integer

arrType

required

Arr family a rollout is scoped to. A rollout never spans types.

string

Allowed values: radarr sonarr lidarr

status

required

Live state machine of a staged rollout:

• canary_running: canary sync is executing inline
• awaiting_confirmation: canary passed, waiting at the verification gate
• rolling_out: batched rollout job is syncing remaining instances
• completed: all remaining instances synced cleanly
• aborted: gate declined, or canary failed/partial-abort/skipped (remaining untouched)
• failed: rollout ran but one or more remaining instances failed

string

Allowed values: canary_running awaiting_confirmation rolling_out completed aborted failed

canaryInstanceId

required

One of:

integer

integer

null

null

canaryInstanceName

required

string

canaryStatus

required

One of:

string

Classified terminal status of the canary sync run.

string

Allowed values: success partial failed skipped

null

null

canarySyncHistoryId

required

One of:

integer

integer

null

null

sections

required

One of:

Array<string>

Array<string>

Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles

null

null

maxBatchSize

required

integer

>= 1

partialPolicy

required

How a partial canary outcome is treated:

• gate: pass-with-warning; continue to the verification gate
• abort: treat as failure; remaining instances are never touched

string

Allowed values: gate abort

canaryOutput

required

One of:

string

string

null

null

canaryError

required

One of:

string

string

null

null

remainingTargets

required

Array<object>

object

instanceId

required

Arr instance ID selected as a rollout target.

integer

instanceName

required

Denormalized instance name captured at rollout start.

string

remainingPreview

required

One of: discriminator: availability

object

object

version

required

Persisted Canary remaining-preview evidence schema version.

integer

Allowed value: 1

availability

required

string

Allowed value: available

generatedAt

required

Time the complete exact-target evidence snapshot was generated.

string format: date-time

previews

required

Complete previews for the persisted remaining target set. An empty mutation summary is a valid no-changes result and is distinct from unavailable evidence.

Array<object>

Read-only per-instance preview payload produced by the Canary coordinator. This matches the runtime GeneratePreviewResult contract; it is not a stored Sync Preview and therefore has no preview id, expiry timestamp, or top-level failure field.

object

instanceId

required

Exact remaining-target Arr instance ID.

integer

instanceName

required

Arr instance name at preview-generation time.

string

arrType

required

Arr family a rollout is scoped to. A rollout never spans types.

string

Allowed values: radarr sonarr lidarr

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

createdAtMs

required

Preview generation time as Unix epoch milliseconds.

integer format: int64

sections

required

Array<string>

Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles

sectionOutcomes

required

Per-section evidence; any failure makes aggregate Canary evidence unavailable.

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:

object

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

null

null

qualityProfiles

required

One of:

object

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

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

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

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

null

null

delayProfiles

required

One of:

object

object

section

required

string

Allowed values: delayProfiles

profile

required

One of:

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

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

unknown

null

null

mediaManagement

required

One of:

object

object

section

required

string

Allowed values: mediaManagement

naming

required

One of:

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

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

unknown

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

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

mediaSettings

required

One of:

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

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

unknown

null

null

metadataProfiles

required

One of:

object

object

section

required

string

Allowed values: metadataProfiles

profile

required

One of:

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

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

unknown

null

null

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

object

object

version

required

Persisted Canary remaining-preview evidence schema version.

integer

Allowed value: 1

availability

required

string

Allowed value: unavailable

generatedAt

required

Time this unavailable evidence result was recorded.

string format: date-time

failure

required

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

partialPreviews

required

Successfully generated diagnostic pieces, if any. Partial previews never authorize promotion and do not represent complete target coverage.

Array<object>

Read-only per-instance preview payload produced by the Canary coordinator. This matches the runtime GeneratePreviewResult contract; it is not a stored Sync Preview and therefore has no preview id, expiry timestamp, or top-level failure field.

object

instanceId

required

Exact remaining-target Arr instance ID.

integer

instanceName

required

Arr instance name at preview-generation time.

string

arrType

required

Arr family a rollout is scoped to. A rollout never spans types.

string

Allowed values: radarr sonarr lidarr

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

createdAtMs

required

Preview generation time as Unix epoch milliseconds.

integer format: int64

sections

required

Array<string>

Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles

sectionOutcomes

required

Per-section evidence; any failure makes aggregate Canary evidence unavailable.

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:

object

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

null

null

qualityProfiles

required

One of:

object

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

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

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

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

null

null

delayProfiles

required

One of:

object

object

section

required

string

Allowed values: delayProfiles

profile

required

One of:

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

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

unknown

null

null

mediaManagement

required

One of:

object

object

section

required

string

Allowed values: mediaManagement

naming

required

One of:

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

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

unknown

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

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

mediaSettings

required

One of:

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

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

unknown

null

null

metadataProfiles

required

One of:

object

object

section

required

string

Allowed values: metadataProfiles

profile

required

One of:

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

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

unknown

null

null

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

batchCursor

required

Index into remainingTargets the rollout job has reached (resumable).

integer

rolloutResults

required

Array<object>

object

instanceId

required

integer

instanceName

required

string

status

required

Per-instance outcome status following JobRunStatus semantics.

string

Allowed values: success failure skipped cancelled

output

Human-readable sync summary from executeSyncJob.

string

error

Per-instance diagnostics on failure.

string

trigger

required

How the rollout was initiated.

string

Allowed values: manual system schedule

startedAt

required

string format: date-time

finishedAt

required

One of:

string

string format: date-time

null

null

stateToken

required

Value-guard token for /proceed and /abort; re-issued on every transition.

string

createdAt

required

string

updatedAt

required

string

Example

{
  "skipped": true,
  "result": {
    "status": "success"
  }
}

400

Invalid request body

Media typeapplication/json

object

error

required

Error message

string

Example^generated

{
  "error": "example"
}

404

Explicit canary instance not found

Media typeapplication/json

object

error

required

Error message

string

Example^generated

{
  "error": "example"
}

422

No canary resolvable, or the canary is not a radarr/sonarr/lidarr instance

Media typeapplication/json

object

error

required

Error message

string

Example^generated

{
  "error": "example"
}

500

Failed to start canary rollout

Media typeapplication/json

object

error

required

Error message

string

Example^generated

{
  "error": "example"
}