Skip to content
Praxrr

Import a portable entity or entity bundle

POST
/pcd/import
curl --request POST \
  --url https://example.com/api/v1/pcd/import \
  --header 'Content-Type: application/json' \
  --data '{ "databaseId": 1, "layer": "user", "entityType": "delay_profile", "migration": { "format": "json", "version": 1, "source": "example" }, "data": { "name": "example", "rename": true, "standardEpisodeFormat": "example", "dailyEpisodeFormat": "example", "animeEpisodeFormat": "example", "seriesFolderFormat": "example", "seasonFolderFormat": "example", "replaceIllegalCharacters": true, "colonReplacementFormat": "example", "customColonReplacementFormat": "example", "multiEpisodeStyle": "example" } }'

Deserializes a portable entity into PCD operations, creating the entity in the target database and layer.

The request body matches the export response format (entityType + data), plus databaseId and layer to specify the target. Optional migration metadata (format, version, source) can be provided for hybrid JSON/YAML ingestion flows.

Name uniqueness is validated — importing an entity with a name that already exists will return a 400 error.

Bundle import: when the body contains a bundle key it is treated as a PcdBundleImportRequest (the legacy single-entity path is not used). All entities are written to the single requested layer as one undo unit.

  • dryRun: true applies the bundle against an ephemeral cache and returns a PcdBundleImportReport listing creates, collisions and missing references. Nothing is written to pcd_ops or pcd_op_history.
  • collisions selects skip, rename or overwrite for entities whose name already exists (case-insensitive), with an optional per-entity override keyed "<entityType>:<name>".
  • References (quality profile to custom format, custom format to regular expression) must resolve inside the bundle or the target database. On a real apply any unresolved reference returns 400 with the report before anything is written.
  • A failure part-way through applying rolls back every operation the import created and returns 500 with the report and rolledBack: true. If the rollback itself failed, the database is disabled and rolledBack is false.
  • expectedPlanDigest: pass the planDigest returned by a dry run to reject the apply with HTTP 409 when the database changed in between.
  • Limits: at most 1000 entities and a 5 MiB JSON body (400 otherwise).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
One of:
object
databaseId
required

The PCD database ID to import into

integer
layer
required

The operation layer to write to

string
Allowed values: user base
entityType
required

Portable PCD entity identifiers used by import/export endpoints.

Lidarr media-management entities are first-class portable contract members:

  • lidarr_naming
  • lidarr_media_settings
  • lidarr_quality_definitions

Runtime validation is deterministic and fail-fast for Lidarr payloads: payloads are rejected when required fields are missing, when unsupported fields are present, or when cross-family fields are mixed into the payload (for example Radarr naming fields with lidarr_naming).

Clients must emit lidarr_* entity types for Lidarr entities.

string
Allowed values: delay_profile regular_expression custom_format quality_profile radarr_naming sonarr_naming radarr_media_settings sonarr_media_settings radarr_quality_definitions sonarr_quality_definitions lidarr_metadata_profile lidarr_naming lidarr_media_settings lidarr_quality_definitions
migration

Optional migration metadata for hybrid imports. If provided, this field must include all keys from PortableMigrationMetadata.

object
format
required

Migration payload format marker (json for JSON payloads, yaml for YAML in future hybrid ingestion flows).

string
Allowed values: json yaml
version
required

Migration schema contract version for hybrid payloads.

integer
>= 1
source
required

Migration source marker (example: pcd-export, pcd-file, pcd-importer).

string
data
required
One of:
object
name
required
string
preferredProtocol
required
string
Allowed values: prefer_usenet prefer_torrent only_usenet only_torrent
usenetDelay
required
integer
torrentDelay
required
integer
bypassIfHighestQuality
required
boolean
bypassIfAboveCfScore
required
boolean
minimumCfScore
required
integer

Responses

Section titled “Responses”

200

Section titled “200”

Entity created successfully, or bundle import report

Media typeapplication/json
One of:
object
success
required
boolean
Example
{
  "outcomes": [
    {
      "entityType": "delay_profile",
      "action": "create"
    }
  ],
  "missingReferences": [
    {
      "fromType": "delay_profile",
      "toType": "delay_profile"
    }
  ],
  "errors": [
    {
      "entityType": "delay_profile"
    }
  ]
}

400

Section titled “400”

Validation error (missing fields, duplicate name, invalid data, bundle caps, unresolved references)

Media typeapplication/json
Any of:
object
error
required
string
code

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

string
Example
{
  "report": {
    "outcomes": [
      {
        "entityType": "delay_profile",
        "action": "create"
      }
    ],
    "missingReferences": [
      {
        "fromType": "delay_profile",
        "toType": "delay_profile"
      }
    ],
    "errors": [
      {
        "entityType": "delay_profile"
      }
    ]
  },
  "missingReferences": [
    {
      "fromType": "delay_profile",
      "toType": "delay_profile"
    }
  ]
}

403

Section titled “403”

Cannot write to base layer

Media typeapplication/json
object
error
required
string
code

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

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

409

Section titled “409”

The plan digest no longer matches the database (run a new dry run)

Media typeapplication/json
object
error
required
string
report
object
planDigest
required

Deterministic hash over the ordered plan outcomes and the target state they were computed from. Pass back as expectedPlanDigest on the apply request to get a 409 when the plan no longer matches the database.

string
dryRun
required
boolean
applied
required

True only when a non-dry-run import wrote its operations.

boolean
rolledBack

True when a failure mid-apply was fully rolled back (HTTP 500).

boolean
outcomes
required
Array<object>
object
entityType
required

Portable PCD entity identifiers used by import/export endpoints.

Lidarr media-management entities are first-class portable contract members:

  • lidarr_naming
  • lidarr_media_settings
  • lidarr_quality_definitions

Runtime validation is deterministic and fail-fast for Lidarr payloads: payloads are rejected when required fields are missing, when unsupported fields are present, or when cross-family fields are mixed into the payload (for example Radarr naming fields with lidarr_naming).

Clients must emit lidarr_* entity types for Lidarr entities.

string
Allowed values: delay_profile regular_expression custom_format quality_profile radarr_naming sonarr_naming radarr_media_settings sonarr_media_settings radarr_quality_definitions sonarr_quality_definitions lidarr_metadata_profile lidarr_naming lidarr_media_settings lidarr_quality_definitions
name
required

Entity name as it appears in the bundle.

string
finalName
required

Name the entity has (or would have) in the target database after import.

string
action
required
string
Allowed values: create skip rename overwrite error
error

Present when action is error.

string
missingReferences
required
Array<object>

A reference (quality profile to custom format, custom format to regular expression) that resolves neither inside the bundle nor in the target database.

object
fromType
required

Portable PCD entity identifiers used by import/export endpoints.

Lidarr media-management entities are first-class portable contract members:

  • lidarr_naming
  • lidarr_media_settings
  • lidarr_quality_definitions

Runtime validation is deterministic and fail-fast for Lidarr payloads: payloads are rejected when required fields are missing, when unsupported fields are present, or when cross-family fields are mixed into the payload (for example Radarr naming fields with lidarr_naming).

Clients must emit lidarr_* entity types for Lidarr entities.

string
Allowed values: delay_profile regular_expression custom_format quality_profile radarr_naming sonarr_naming radarr_media_settings sonarr_media_settings radarr_quality_definitions sonarr_quality_definitions lidarr_metadata_profile lidarr_naming lidarr_media_settings lidarr_quality_definitions
fromName
required
string
toType
required

Portable PCD entity identifiers used by import/export endpoints.

Lidarr media-management entities are first-class portable contract members:

  • lidarr_naming
  • lidarr_media_settings
  • lidarr_quality_definitions

Runtime validation is deterministic and fail-fast for Lidarr payloads: payloads are rejected when required fields are missing, when unsupported fields are present, or when cross-family fields are mixed into the payload (for example Radarr naming fields with lidarr_naming).

Clients must emit lidarr_* entity types for Lidarr entities.

string
Allowed values: delay_profile regular_expression custom_format quality_profile radarr_naming sonarr_naming radarr_media_settings sonarr_media_settings radarr_quality_definitions sonarr_quality_definitions lidarr_metadata_profile lidarr_naming lidarr_media_settings lidarr_quality_definitions
toName
required
string
errors
required
Array<object>
object
entityType
required

Portable PCD entity identifiers used by import/export endpoints.

Lidarr media-management entities are first-class portable contract members:

  • lidarr_naming
  • lidarr_media_settings
  • lidarr_quality_definitions

Runtime validation is deterministic and fail-fast for Lidarr payloads: payloads are rejected when required fields are missing, when unsupported fields are present, or when cross-family fields are mixed into the payload (for example Radarr naming fields with lidarr_naming).

Clients must emit lidarr_* entity types for Lidarr entities.

string
Allowed values: delay_profile regular_expression custom_format quality_profile radarr_naming sonarr_naming radarr_media_settings sonarr_media_settings radarr_quality_definitions sonarr_quality_definitions lidarr_metadata_profile lidarr_naming lidarr_media_settings lidarr_quality_definitions
name
required
string
error
required
string
rolledBack

True when a mid-apply failure was fully rolled back (HTTP 500).

boolean
missingReferences

Present on HTTP 400 when references resolve neither in the bundle nor the target database.

Array<object>

A reference (quality profile to custom format, custom format to regular expression) that resolves neither inside the bundle nor in the target database.

object
fromType
required

Portable PCD entity identifiers used by import/export endpoints.

Lidarr media-management entities are first-class portable contract members:

  • lidarr_naming
  • lidarr_media_settings
  • lidarr_quality_definitions

Runtime validation is deterministic and fail-fast for Lidarr payloads: payloads are rejected when required fields are missing, when unsupported fields are present, or when cross-family fields are mixed into the payload (for example Radarr naming fields with lidarr_naming).

Clients must emit lidarr_* entity types for Lidarr entities.

string
Allowed values: delay_profile regular_expression custom_format quality_profile radarr_naming sonarr_naming radarr_media_settings sonarr_media_settings radarr_quality_definitions sonarr_quality_definitions lidarr_metadata_profile lidarr_naming lidarr_media_settings lidarr_quality_definitions
fromName
required
string
toType
required

Portable PCD entity identifiers used by import/export endpoints.

Lidarr media-management entities are first-class portable contract members:

  • lidarr_naming
  • lidarr_media_settings
  • lidarr_quality_definitions

Runtime validation is deterministic and fail-fast for Lidarr payloads: payloads are rejected when required fields are missing, when unsupported fields are present, or when cross-family fields are mixed into the payload (for example Radarr naming fields with lidarr_naming).

Clients must emit lidarr_* entity types for Lidarr entities.

string
Allowed values: delay_profile regular_expression custom_format quality_profile radarr_naming sonarr_naming radarr_media_settings sonarr_media_settings radarr_quality_definitions sonarr_quality_definitions lidarr_metadata_profile lidarr_naming lidarr_media_settings lidarr_quality_definitions
toName
required
string
Example
{
  "report": {
    "outcomes": [
      {
        "entityType": "delay_profile",
        "action": "create"
      }
    ],
    "missingReferences": [
      {
        "fromType": "delay_profile",
        "toType": "delay_profile"
      }
    ],
    "errors": [
      {
        "entityType": "delay_profile"
      }
    ]
  },
  "missingReferences": [
    {
      "fromType": "delay_profile",
      "toType": "delay_profile"
    }
  ]
}

500

Section titled “500”

Database cache not available, or bundle apply failed and was rolled back

Media typeapplication/json
Any of:
object
error
required
string
code

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

string
Example
{
  "report": {
    "outcomes": [
      {
        "entityType": "delay_profile",
        "action": "create"
      }
    ],
    "missingReferences": [
      {
        "fromType": "delay_profile",
        "toType": "delay_profile"
      }
    ],
    "errors": [
      {
        "entityType": "delay_profile"
      }
    ]
  },
  "missingReferences": [
    {
      "fromType": "delay_profile",
      "toType": "delay_profile"
    }
  ]
}