Downloads

Generated downloads operations.

GET/v1/downloads/artifacts/{grant}Fetch a download's media file, whole or by byte rangeopen

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: get_download_artifact

Parameters

Name	In	Type	Description
`grant`required	path	`string`

Responses

200Successapplication/octet-stream

Example

"string"

Schema

string (binary)

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestinvalid_download_grantdownloads_not_alloweddownload_unavailabledownload_not_readydownload_source_offlinedownloads_unavailablenot_foundinternaldatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/artifacts/{grant}"

HEAD/v1/downloads/artifacts/{grant}Read a download's size, type and digestopen

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: head_download_artifact

Parameters

Name	In	Type	Description
`grant`required	path	`string`

Responses

200Successapplication/octet-stream

Example

"string"

Schema

string (binary)

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestinvalid_download_grantdownloads_not_alloweddownload_unavailabledownload_not_readydownload_source_offlinedownloads_unavailablenot_foundinternaldatabase_busy

Example request

curl -X HEAD "http://127.0.0.1:32500/v1/downloads/artifacts/{grant}"

GET/v1/downloads/artifacts/{grant}/artwork/{role}Fetch one picture that travels with a downloadopen

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: get_download_artwork

Parameters

Name	In	Type	Description
`grant`required	path	`string`
`role`required	path	`string`

Responses

200Successapplication/octet-stream

Example

"string"

Schema

string (binary)

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestinvalid_download_grantdownloads_not_alloweddownload_unavailabledownload_not_readydownload_source_offlinedownloads_unavailablenot_foundinternaldatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/artifacts/{grant}/artwork/{role}"

GET/v1/downloads/artifacts/{grant}/chapters/{source}/{index}/imageFetch one chapter thumbnail that travels with a downloadopen

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: get_download_chapter_image

Parameters

Name	In	Type
`grant`required	path	`string`
`source`required	path	`string`
`index`required	path	`string`

Responses

200Successapplication/octet-stream

Example

"string"

Schema

string (binary)

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestinvalid_download_grantdownloads_not_alloweddownload_unavailabledownload_not_readydownload_source_offlinedownloads_unavailablenot_foundinternaldatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/artifacts/{grant}/chapters/{source}/{index}/image"

GET/v1/downloads/artifacts/{grant}/subtitles/{resource}/{revision}.vttFetch one subtitle track that travels with a download, as WebVTTopen

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: get_download_subtitle

Parameters

Name	In	Type
`grant`required	path	`string`
`resource`required	path	`string`
`revision`required	path	`string`

Responses

200Successapplication/octet-stream

Example

"string"

Schema

string (binary)

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestinvalid_download_grantdownloads_not_alloweddownload_unavailabledownload_not_readydownload_source_offlinedownloads_unavailablenot_foundinternaldatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/artifacts/{grant}/subtitles/{resource}/{revision}.vtt"

GET/v1/downloads/artifacts/{grant}/subtitles/{resource}/{revision}/{file}Fetch one file of a styled or picture subtitle track that travels with a downloadopen

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: get_download_subtitle_original

Parameters

Name	In	Type
`grant`required	path	`string`
`resource`required	path	`string`
`revision`required	path	`string`
`file`required	path	`string`

Responses

200Successapplication/octet-stream

Example

"string"

Schema

string (binary)

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestinvalid_download_grantdownloads_not_alloweddownload_unavailabledownload_not_readydownload_source_offlinedownloads_unavailablenot_foundinternaldatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/artifacts/{grant}/subtitles/{resource}/{revision}/{file}"

GET/v1/downloads/artifacts/{grant}/trickplay/{set}/thumbnails.vttFetch the scrubbing preview track that travels with a downloadopen

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: get_download_trickplay_thumbnails

Parameters

Name	In	Type	Description
`grant`required	path	`string`
`set`required	path	`string`

Responses

200Successapplication/octet-stream

Example

"string"

Schema

string (binary)

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestinvalid_download_grantdownloads_not_alloweddownload_unavailabledownload_not_readydownload_source_offlinedownloads_unavailablenot_foundinternaldatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/artifacts/{grant}/trickplay/{set}/thumbnails.vtt"

GET/v1/downloads/artifacts/{grant}/trickplay/{set}/tiles/{tile}Fetch one scrubbing preview sheet that travels with a downloadopen

Audience: Clients · Native API
Authorization: No credential needed
OpenAPI operation ID: get_download_trickplay_tile

Parameters

Name	In	Type
`grant`required	path	`string`
`set`required	path	`string`
`tile`required	path	`string`

Responses

200Successapplication/octet-stream

Example

"string"

Schema

string (binary)

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestinvalid_download_grantdownloads_not_alloweddownload_unavailabledownload_not_readydownload_source_offlinedownloads_unavailablenot_foundinternaldatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/artifacts/{grant}/trickplay/{set}/tiles/{tile}"

POST/v1/downloads/optionsRead combined per-quality sizes for the visible members of a containerplayback

Audience: Clients · Native API
Authorization: API key or personal access token with the playback scope, or a signed-in session
OpenAPI operation ID: get_container_download_options
Max body: 8 KiB

Request body application/json · required

Example

{
  "deviceId": "id_8h2k4q",
  "policy": {
    "episodes": "string",
    "keepNext": 0
  },
  "target": {
    "id": "id_8h2k4q",
    "kind": "string"
  }
}

Schema

deviceIdstringrequired
policyobjectrequired
- episodesstringrequired
- keepNextinteger
targetobjectrequired
- idstringrequired
- kindstringrequired

Responses

200Successapplication/json

Example

{
  "options": [
    {
      "available": true,
      "dataGBPerHour": 0,
      "estimated": true,
      "estimatedBytes": 0,
      "label": "string",
      "maxVideoBitrateBps": 0,
      "quality": "string",
      "sameAsOriginal": true,
      "unavailableCount": 0,
      "unknownSizeCount": 0
    }
  ],
  "target": {
    "id": "id_8h2k4q",
    "kind": "string"
  },
  "total": 0
}

Schema

optionsarray of objectrequired
- availablebooleanrequired
- dataGBPerHournumber
- estimatedbooleanrequired
- estimatedBytesintegerrequired
- labelstringrequired
- maxVideoBitrateBpsinteger
- qualitystringrequired
- sameAsOriginalbooleanrequired
- unavailableCountintegerrequired
- unknownSizeCountintegerrequired
targetobjectrequired
- idstringrequired
- kindstringrequired
totalintegerrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittednot_foundidempotency_key_reusedrate_limitedinternaldownloads_unavailabletimeoutdatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/downloads/options" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deviceId":"id_8h2k4q","policy":{"episodes":"string","keepNext":0},"target":{"id":"id_8h2k4q","kind":"string"}}'

GET/v1/downloads/preparationsList this viewer's download claims, newest firstread

Audience: Clients · Native API
Authorization: API key or personal access token with the read scope, or a signed-in session
OpenAPI operation ID: list_download_preparations

Parameters

Name	In	Type
`state`	query	`string`
`profileId`	query	`string`
`cursor`	query	`string`
`limit`	query	`integer`
`ids`	query	`string`
`operationId`	query	`string`
`deviceId`	query	`string`

Responses

200Successapplication/json

Example

{
  "closed": true,
  "items": [
    {
      "actions": [
        "string"
      ],
      "artifact": {
        "bytes": 0,
        "container": "string",
        "contentType": "string",
        "estimated": true,
        "fileName": "Fargo",
        "kind": "string",
        "ref": "string",
        "sha256": "string"
      },
      "batchId": "id_8h2k4q",
      "createdAt": "2026-10-18T19:30:00Z",
      "expiresAt": "2026-10-18T19:30:00Z",
      "id": "id_8h2k4q",
      "itemId": "id_8h2k4q",
      "libraryId": "id_8h2k4q",
      "origin": "string",
      "profileId": "id_8h2k4q",
      "progress": {
        "bytesDone": 0,
        "bytesTotal": 0,
        "bytesTotalEstimated": true,
        "etaMs": 1800000,
        "percent": 0
      },
      "quality": "string",
      "readyAt": "2026-10-18T19:30:00Z",
      "reason": "string",
      "revision": 0,
      "state": "string",
      "title": {
        "artist": "string",
        "durationMs": 1800000,
        "groupId": "id_8h2k4q",
        "groupNumber": 0,
        "groupTitle": "Fargo",
        "kind": "string",
        "number": 0,
        "onServer": true,
        "parentId": "id_8h2k4q",
        "parentTitle": "Fargo",
        "title": "Fargo",
        "year": 0
      },
      "updatedAt": "2026-10-18T19:30:00Z",
      "versionId": "id_8h2k4q"
    }
  ],
  "nextCursor": "eyJvIjoyMH0"
}

Schema

closedboolean
itemsarray of objectrequired
- actionsarray of stringrequired
- artifactobjectrequired
  - bytesintegerrequired
  - containerstring
  - contentTypestring
  - estimatedbooleanrequired
  - fileNamestring
  - kindstringrequired
  - refstring
  - sha256string
- batchIdstring
- createdAtstringrequired
- expiresAtstring
- idstringrequired
- itemIdstringrequired
- libraryIdstringrequired
- originstringrequired
- profileIdstringrequired
- progressobjectrequired
  - bytesDoneintegerrequired
  - bytesTotalintegerrequired
  - bytesTotalEstimatedbooleanrequired
  - etaMsinteger | any | nullrequired
  - percentnumberrequired
- qualitystringrequired
- readyAtstring
- reasonstring
- revisionintegerrequired
- statestringrequired
- titleobjectrequired
  - artiststring
  - durationMsinteger≥ 0
  - groupIdstring
  - groupNumberinteger
  - groupTitlestring
  - kindstringrequired
  - numberinteger
  - onServerbooleanrequired
  - parentIdstring
  - parentTitlestring
  - titlestringrequired
  - yearinteger
- updatedAtstringrequired
- versionIdstringrequired
nextCursorstringrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittedfeature_restrictednot_founddownloads_not_alloweddownloads_unavailableinternaltimeoutdatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/preparations" \
  -H "Authorization: Bearer $PORTICO_API_KEY"

POST/v1/downloads/preparationsClaim one title, several titles or the next episode for offline useplayback

Audience: Clients · Native API
Authorization: API key or personal access token with the playback scope, or a signed-in session
OpenAPI operation ID: create_download_preparations
Max body: 32 KiB

Request body application/json · required

Example

{
  "mediaId": "id_8h2k4q",
  "mediaIds": [
    "string"
  ],
  "nextAfterMediaId": "id_8h2k4q",
  "operationId": "id_8h2k4q",
  "quality": "original",
  "versionId": "id_8h2k4q"
}

Schema

mediaIdstring
mediaIdsarray of string
nextAfterMediaIdstring
operationIdstringrequired
qualitystringone of "original", "automatic", "2160p", "1080p-high", "1080p-low", "720p-high", "720p-low", "480p", "240p", "cd-quality", "320", "96"
versionIdstring

Responses

201Successapplication/json

Example

{
  "accepted": 0,
  "batchId": "id_8h2k4q",
  "duplicate": true,
  "items": [
    {
      "actions": [
        "string"
      ],
      "artifact": {
        "bytes": 0,
        "container": "string",
        "contentType": "string",
        "estimated": true,
        "fileName": "Fargo",
        "kind": "string",
        "ref": "string",
        "sha256": "string"
      },
      "batchId": "id_8h2k4q",
      "createdAt": "2026-10-18T19:30:00Z",
      "expiresAt": "2026-10-18T19:30:00Z",
      "id": "id_8h2k4q",
      "itemId": "id_8h2k4q",
      "libraryId": "id_8h2k4q",
      "origin": "string",
      "profileId": "id_8h2k4q",
      "progress": {
        "bytesDone": 0,
        "bytesTotal": 0,
        "bytesTotalEstimated": true,
        "etaMs": 1800000,
        "percent": 0
      },
      "quality": "string",
      "readyAt": "2026-10-18T19:30:00Z",
      "reason": "string",
      "revision": 0,
      "state": "string",
      "title": {
        "artist": "string",
        "durationMs": 1800000,
        "groupId": "id_8h2k4q",
        "groupNumber": 0,
        "groupTitle": "Fargo",
        "kind": "string",
        "number": 0,
        "onServer": true,
        "parentId": "id_8h2k4q",
        "parentTitle": "Fargo",
        "title": "Fargo",
        "year": 0
      },
      "updatedAt": "2026-10-18T19:30:00Z",
      "versionId": "id_8h2k4q"
    }
  ],
  "rejected": [
    {
      "code": "string",
      "itemId": "id_8h2k4q"
    }
  ]
}

Schema

acceptedintegerrequired
batchIdstringrequired
duplicatebooleanrequired
itemsarray of objectrequired
- actionsarray of stringrequired
- artifactobjectrequired
  - bytesintegerrequired
  - containerstring
  - contentTypestring
  - estimatedbooleanrequired
  - fileNamestring
  - kindstringrequired
  - refstring
  - sha256string
- batchIdstring
- createdAtstringrequired
- expiresAtstring
- idstringrequired
- itemIdstringrequired
- libraryIdstringrequired
- originstringrequired
- profileIdstringrequired
- progressobjectrequired
  - bytesDoneintegerrequired
  - bytesTotalintegerrequired
  - bytesTotalEstimatedbooleanrequired
  - etaMsinteger | any | nullrequired
  - percentnumberrequired
- qualitystringrequired
- readyAtstring
- reasonstring
- revisionintegerrequired
- statestringrequired
- titleobjectrequired
  - artiststring
  - durationMsinteger≥ 0
  - groupIdstring
  - groupNumberinteger
  - groupTitlestring
  - kindstringrequired
  - numberinteger
  - onServerbooleanrequired
  - parentIdstring
  - parentTitlestring
  - titlestringrequired
  - yearinteger
- updatedAtstringrequired
- versionIdstringrequired
rejectedarray of objectrequired
- codestringrequired
- itemIdstringrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesdownload_conflictstorage_fulldownload_not_readydownload_unavailablerate_limitedinvalid_requestunauthorizednot_permittedfeature_restrictednot_founddownloads_not_alloweddownloads_unavailableinternaltimeoutdatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/downloads/preparations" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mediaId":"id_8h2k4q","mediaIds":["string"],"nextAfterMediaId":"id_8h2k4q","operationId":"id_8h2k4q","quality":"original","versionId":"id_8h2k4q"}'

GET/v1/downloads/preparations/{id}Read one download claimread

Audience: Clients · Native API
Authorization: API key or personal access token with the read scope, or a signed-in session
OpenAPI operation ID: get_download_preparation

Parameters

Name	In	Type	Description
`id`required	path	`string`

Responses

200Successapplication/json

Example

{
  "actions": [
    "string"
  ],
  "artifact": {
    "bytes": 0,
    "container": "string",
    "contentType": "string",
    "estimated": true,
    "fileName": "Fargo",
    "kind": "string",
    "ref": "string",
    "sha256": "string"
  },
  "batchId": "id_8h2k4q",
  "createdAt": "2026-10-18T19:30:00Z",
  "expiresAt": "2026-10-18T19:30:00Z",
  "id": "id_8h2k4q",
  "itemId": "id_8h2k4q",
  "libraryId": "id_8h2k4q",
  "origin": "string",
  "profileId": "id_8h2k4q",
  "progress": {
    "bytesDone": 0,
    "bytesTotal": 0,
    "bytesTotalEstimated": true,
    "etaMs": 1800000,
    "percent": 0
  },
  "quality": "string",
  "readyAt": "2026-10-18T19:30:00Z",
  "reason": "string",
  "revision": 0,
  "state": "string",
  "title": {
    "artist": "string",
    "durationMs": 1800000,
    "groupId": "id_8h2k4q",
    "groupNumber": 0,
    "groupTitle": "Fargo",
    "kind": "string",
    "number": 0,
    "onServer": true,
    "parentId": "id_8h2k4q",
    "parentTitle": "Fargo",
    "title": "Fargo",
    "year": 0
  },
  "updatedAt": "2026-10-18T19:30:00Z",
  "versionId": "id_8h2k4q"
}

Schema

actionsarray of stringrequired
artifactobjectrequired
- bytesintegerrequired
- containerstring
- contentTypestring
- estimatedbooleanrequired
- fileNamestring
- kindstringrequired
- refstring
- sha256string
batchIdstring
createdAtstringrequired
expiresAtstring
idstringrequired
itemIdstringrequired
libraryIdstringrequired
originstringrequired
profileIdstringrequired
progressobjectrequired
- bytesDoneintegerrequired
- bytesTotalintegerrequired
- bytesTotalEstimatedbooleanrequired
- etaMsinteger | any | nullrequired
- percentnumberrequired
qualitystringrequired
readyAtstring
reasonstring
revisionintegerrequired
statestringrequired
titleobjectrequired
- artiststring
- durationMsinteger≥ 0
- groupIdstring
- groupNumberinteger
- groupTitlestring
- kindstringrequired
- numberinteger
- onServerbooleanrequired
- parentIdstring
- parentTitlestring
- titlestringrequired
- yearinteger
updatedAtstringrequired
versionIdstringrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittedfeature_restrictednot_founddownloads_not_alloweddownloads_unavailableinternaltimeoutdatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/preparations/{id}" \
  -H "Authorization: Bearer $PORTICO_API_KEY"

POST/v1/downloads/preparations/{id}/actionsPause, resume, cancel, retry or remove a download claimplayback

Audience: Clients · Native API
Authorization: API key or personal access token with the playback scope, or a signed-in session
OpenAPI operation ID: act_on_download_preparation
Max body: 4 KiB

Parameters

Name	In	Type	Description
`id`required	path	`string`

Request body application/json · required

Example

{
  "action": "string",
  "expectedRevision": 0,
  "operationId": "id_8h2k4q"
}

Schema

actionstringrequired
expectedRevisionintegerrequired
operationIdstringrequired

Responses

200Successapplication/json

Example

{
  "actions": [
    "string"
  ],
  "artifact": {
    "bytes": 0,
    "container": "string",
    "contentType": "string",
    "estimated": true,
    "fileName": "Fargo",
    "kind": "string",
    "ref": "string",
    "sha256": "string"
  },
  "batchId": "id_8h2k4q",
  "createdAt": "2026-10-18T19:30:00Z",
  "expiresAt": "2026-10-18T19:30:00Z",
  "id": "id_8h2k4q",
  "itemId": "id_8h2k4q",
  "libraryId": "id_8h2k4q",
  "origin": "string",
  "profileId": "id_8h2k4q",
  "progress": {
    "bytesDone": 0,
    "bytesTotal": 0,
    "bytesTotalEstimated": true,
    "etaMs": 1800000,
    "percent": 0
  },
  "quality": "string",
  "readyAt": "2026-10-18T19:30:00Z",
  "reason": "string",
  "revision": 0,
  "state": "string",
  "title": {
    "artist": "string",
    "durationMs": 1800000,
    "groupId": "id_8h2k4q",
    "groupNumber": 0,
    "groupTitle": "Fargo",
    "kind": "string",
    "number": 0,
    "onServer": true,
    "parentId": "id_8h2k4q",
    "parentTitle": "Fargo",
    "title": "Fargo",
    "year": 0
  },
  "updatedAt": "2026-10-18T19:30:00Z",
  "versionId": "id_8h2k4q"
}

Schema

actionsarray of stringrequired
artifactobjectrequired
- bytesintegerrequired
- containerstring
- contentTypestring
- estimatedbooleanrequired
- fileNamestring
- kindstringrequired
- refstring
- sha256string
batchIdstring
createdAtstringrequired
expiresAtstring
idstringrequired
itemIdstringrequired
libraryIdstringrequired
originstringrequired
profileIdstringrequired
progressobjectrequired
- bytesDoneintegerrequired
- bytesTotalintegerrequired
- bytesTotalEstimatedbooleanrequired
- etaMsinteger | any | nullrequired
- percentnumberrequired
qualitystringrequired
readyAtstring
reasonstring
revisionintegerrequired
statestringrequired
titleobjectrequired
- artiststring
- durationMsinteger≥ 0
- groupIdstring
- groupNumberinteger
- groupTitlestring
- kindstringrequired
- numberinteger
- onServerbooleanrequired
- parentIdstring
- parentTitlestring
- titlestringrequired
- yearinteger
updatedAtstringrequired
versionIdstringrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Example request

curl -X POST "http://127.0.0.1:32500/v1/downloads/preparations/{id}/actions" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"string","expectedRevision":0,"operationId":"id_8h2k4q"}'

GET/v1/downloads/preparations/{id}/bundleRead everything that travels with a ready download: titles, artwork, chapters, markers, subtitles and audio tracksread

Audience: Clients · Native API
Authorization: API key or personal access token with the read scope, or a signed-in session
OpenAPI operation ID: get_download_bundle

Parameters

Name	In	Type	Description
`id`required	path	`string`

Responses

200Successapplication/json

Example

{
  "artwork": [
    {
      "contentType": "string",
      "path": "string",
      "role": "string"
    }
  ],
  "audio": [
    {
      "channels": 0,
      "codec": "string",
      "default": true,
      "index": 0,
      "language": "en",
      "title": "Fargo"
    }
  ],
  "chapters": [
    {
      "endMs": 1800000,
      "image": {
        "contentType": "string",
        "path": "string"
      },
      "index": 0,
      "startMs": 1800000,
      "title": "Fargo"
    }
  ],
  "itemId": "id_8h2k4q",
  "markers": [
    {
      "automatic": true,
      "endMs": 1800000,
      "kind": "string",
      "startMs": 1800000
    }
  ],
  "media": {
    "audioCodec": "string",
    "container": "string",
    "height": 0,
    "videoCodec": "string",
    "width": 0
  },
  "overview": "string",
  "preparationId": "id_8h2k4q",
  "publication": "string",
  "quality": "string",
  "qualityLabel": "string",
  "subtitles": [
    {
      "default": true,
      "files": {
        "key": {
          "contentType": "string",
          "path": "string"
        }
      },
      "forced": true,
      "id": "id_8h2k4q",
      "language": "en",
      "lines": {
        "forced": 0,
        "total": 0
      },
      "revision": 0,
      "title": "Fargo"
    }
  ],
  "title": {
    "artist": "string",
    "durationMs": 1800000,
    "groupId": "id_8h2k4q",
    "groupNumber": 0,
    "groupTitle": "Fargo",
    "kind": "string",
    "number": 0,
    "onServer": true,
    "parentId": "id_8h2k4q",
    "parentTitle": "Fargo",
    "title": "Fargo",
    "year": 0
  },
  "trickplay": {
    "columns": 0,
    "durationMs": 1800000,
    "frameCount": 0,
    "id": "id_8h2k4q",
    "intervalMs": 1800000,
    "rows": 0,
    "sourceOffsetMs": 1800000,
    "thumbnails": {
      "contentType": "string",
      "path": "string"
    },
    "tileHeight": 0,
    "tileWidth": 0,
    "tiles": [
      {
        "contentType": "string",
        "path": "string"
      }
    ]
  }
}

Schema

artworkarray of objectrequired
- contentTypestringrequired
- pathstringrequired
- rolestringrequired
audioarray of objectrequired
- channelsintegerrequired
- codecstringrequired
- defaultbooleanrequired
- indexintegerrequired
- languagestringrequired
- titlestringrequired
chaptersarray of objectrequired
- endMsintegerrequired≥ 0
- imageobject
  - contentTypestringrequired
  - pathstringrequired
- indexintegerrequired
- startMsintegerrequired≥ 0
- titlestringrequired
itemIdstringrequired
markersarray of objectrequired
- automaticbooleanrequired
- endMsintegerrequired≥ 0
- kindstringrequired
- startMsintegerrequired≥ 0
mediaobjectrequired
- audioCodecstring
- containerstringrequired
- heightinteger
- videoCodecstring
- widthinteger
overviewstringrequired
preparationIdstringrequired
publicationstringlength 0–2097152
qualitystringrequired
qualityLabelstringrequired
subtitlesarray of objectrequired
- defaultbooleanrequired
- filesobjectrequired
  - contentTypestringrequired
  - pathstringrequired
- forcedbooleanrequired
- idstringrequired
- languagestringrequired
- linesobject
  - forcedintegerrequired
  - totalintegerrequired
- revisionintegerrequired
- titlestringrequired
titleobjectrequired
- artiststring
- durationMsinteger≥ 0
- groupIdstring
- groupNumberinteger
- groupTitlestring
- kindstringrequired
- numberinteger
- onServerbooleanrequired
- parentIdstring
- parentTitlestring
- titlestringrequired
- yearinteger
trickplayobject
- columnsintegerrequired
- durationMsintegerrequired≥ 0
- frameCountintegerrequired
- idstringrequired
- intervalMsintegerrequired≥ 0
- rowsintegerrequired
- sourceOffsetMsintegerrequired≥ 0
- thumbnailsobjectrequired
  - contentTypestringrequired
  - pathstringrequired
- tileHeightintegerrequired
- tileWidthintegerrequired
- tilesarray of objectrequired
  - contentTypestringrequired
  - pathstringrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittedfeature_restrictednot_founddownloads_not_alloweddownloads_unavailableinternaltimeoutdatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/preparations/{id}/bundle" \
  -H "Authorization: Bearer $PORTICO_API_KEY"

POST/v1/downloads/preparations/{id}/grantTake, or keep alive, the address a ready download is fetched fromplayback

Audience: Clients · Native API
Authorization: API key or personal access token with the playback scope, or a signed-in session
OpenAPI operation ID: create_download_grant
Max body: 4 KiB

Parameters

Name	In	Type	Description
`id`required	path	`string`

Request body application/json · required

Example

{
  "operationId": "id_8h2k4q",
  "renew": "string"
}

Schema

operationIdstringrequired
renewstring

Responses

201Successapplication/json

Example

{
  "artifact": {
    "bytes": 0,
    "container": "string",
    "contentType": "string",
    "estimated": true,
    "fileName": "Fargo",
    "kind": "string",
    "ref": "string",
    "sha256": "string"
  },
  "expiresAt": "2026-10-18T19:30:00Z",
  "issuedAt": "2026-10-18T19:30:00Z",
  "itemId": "id_8h2k4q",
  "preparationId": "id_8h2k4q",
  "renewAfterMs": 1800000,
  "renewed": true,
  "token": "string",
  "url": "https://example.com/…"
}

Schema

artifactobjectrequired
- bytesintegerrequired
- containerstring
- contentTypestring
- estimatedbooleanrequired
- fileNamestring
- kindstringrequired
- refstring
- sha256string
expiresAtstringrequired
issuedAtstringrequired
itemIdstringrequired
preparationIdstringrequired
renewAfterMsintegerrequired
renewedbooleanrequired
tokenstringrequired
urlstringrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Example request

curl -X POST "http://127.0.0.1:32500/v1/downloads/preparations/{id}/grant" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operationId":"id_8h2k4q","renew":"string"}'

POST/v1/downloads/progressReport plays of downloaded copies made with no server in reachplayback

Audience: Clients · Native API
Authorization: API key or personal access token with the playback scope, or a signed-in session
OpenAPI operation ID: sync_download_progress
Max body: 64 KiB

Request body application/json · required

Example

{
  "entries": [
    {
      "ended": true,
      "itemId": "id_8h2k4q",
      "observedAt": "2026-10-18T19:30:00Z",
      "playId": "id_8h2k4q",
      "positionMs": 1800000
    }
  ],
  "operationId": "id_8h2k4q"
}

Schema

entriesarray of objectrequired
- endedboolean
- itemIdstringrequired
- observedAtstringrequired
- playIdstringrequired
- positionMsintegerrequired≥ 0
operationIdstringrequired

Responses

200Successapplication/json

Example

{
  "applied": 0,
  "conflicts": 0,
  "entries": [
    {
      "itemId": "id_8h2k4q",
      "observedAt": "2026-10-18T19:30:00Z",
      "outcome": "string",
      "playId": "id_8h2k4q",
      "positionMs": 1800000,
      "watched": true
    }
  ]
}

Schema

appliedintegerrequired
conflictsintegerrequired
entriesarray of objectrequired
- itemIdstringrequired
- observedAtstring
- outcomestringrequired
- playIdstringrequired
- positionMsintegerrequired≥ 0
- watchedbooleanrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Example request

curl -X POST "http://127.0.0.1:32500/v1/downloads/progress" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entries":[{"ended":true,"itemId":"id_8h2k4q","observedAt":"2026-10-18T19:30:00Z","playId":"id_8h2k4q","positionMs":1800000}],"operationId":"id_8h2k4q"}'

GET/v1/downloads/receipt-keysRead the keys this server signs receipts withread

Audience: Clients · Native API
Authorization: API key or personal access token with the read scope, or a signed-in session
OpenAPI operation ID: list_download_receipt_keys

Responses

200Successapplication/json

Example

{
  "keys": [
    {
      "algorithm": "string",
      "createdAt": "2026-10-18T19:30:00Z",
      "id": "id_8h2k4q",
      "publicKey": "string",
      "retiredAt": "2026-10-18T19:30:00Z"
    }
  ]
}

Schema

keysarray of objectrequired
- algorithmstringrequired
- createdAtstringrequired
- idstringrequired
- publicKeystringrequired
- retiredAtstring

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittedfeature_restrictednot_founddownloads_not_alloweddownloads_unavailableinternaltimeoutdatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/receipt-keys" \
  -H "Authorization: Bearer $PORTICO_API_KEY"

POST/v1/downloads/receiptsTake signed offline permission for ready downloadsplayback

Audience: Clients · Native API
Authorization: API key or personal access token with the playback scope, or a signed-in session
OpenAPI operation ID: issue_download_receipts
Max body: 32 KiB

Request body application/json · required

Example

{
  "operationId": "id_8h2k4q",
  "preparationIds": [
    "string"
  ]
}

Schema

operationIdstringrequired
preparationIdsarray of stringrequired

Responses

201Successapplication/json

Example

{
  "results": [
    {
      "code": "string",
      "outcome": "string",
      "preparationId": "id_8h2k4q",
      "receipt": {
        "algorithm": "string",
        "claims": {
          "artifact": {},
          "expiresAt": "2026-10-18T19:30:00Z",
          "issuedAt": "2026-10-18T19:30:00Z",
          "itemId": "id_8h2k4q",
          "keyId": "id_8h2k4q",
          "kind": "string",
          "preparationId": "id_8h2k4q",
          "publication": {},
          "quality": "string",
          "qualityLabel": "string",
          "receiptId": "id_8h2k4q",
          "version": "string",
          "viewer": {}
        },
        "keyId": "id_8h2k4q",
        "payload": "string",
        "receiptId": "id_8h2k4q",
        "revision": 0,
        "signature": "string"
      },
      "receiptId": "id_8h2k4q",
      "titleOnServer": true,
      "viewing": {
        "positionMs": 1800000,
        "watched": true
      }
    }
  ]
}

Schema

resultsarray of objectrequired
- codestring
- outcomestringrequired
- preparationIdstring
- receiptobject
  - algorithmstringrequired
  - claimsobjectrequired
    artifactobjectrequired
    bytesintegerrequired
    sha256stringrequired
    expiresAtstringrequired
    issuedAtstringrequired
    itemIdstringrequired
    keyIdstringrequired
    kindstringrequired
    preparationIdstringrequired
    publicationobject
    documentSha256stringrequiredpattern ^[0-9a-f]{64}$
    formatstringrequiredone of "epub", "pdf", "cbz", "cb7", "cbr"
    revisionstringrequiredpattern ^[0-9a-f]{64}$
    sourceIdstringrequiredlength 1–128pattern ^[A-Za-z0-9_-]+$
    qualitystringrequired
    qualityLabelstringrequired
    receiptIdstringrequired
    versionstringrequired
    viewerobjectrequired
    accountIdstringrequired
    authoritystringrequired
    profileIdstringrequired
    serverIdstringrequired
  - keyIdstringrequired
  - payloadstringrequired
  - receiptIdstringrequired
  - revisionintegerrequired
  - signaturestringrequired
- receiptIdstring
- titleOnServerboolean
- viewingobject
  - positionMsintegerrequired≥ 0
  - watchedbooleanrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Example request

curl -X POST "http://127.0.0.1:32500/v1/downloads/receipts" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operationId":"id_8h2k4q","preparationIds":["string"]}'

POST/v1/downloads/receipts/revalidateRenew offline permission for copies already on a deviceplayback

Audience: Clients · Native API
Authorization: API key or personal access token with the playback scope, or a signed-in session
OpenAPI operation ID: revalidate_download_receipts
Max body: 32 KiB

Request body application/json · required

Example

{
  "operationId": "id_8h2k4q",
  "receiptIds": [
    "string"
  ]
}

Schema

operationIdstringrequired
receiptIdsarray of stringrequired

Responses

200Successapplication/json

Example

{
  "results": [
    {
      "code": "string",
      "outcome": "string",
      "preparationId": "id_8h2k4q",
      "receipt": {
        "algorithm": "string",
        "claims": {
          "artifact": {},
          "expiresAt": "2026-10-18T19:30:00Z",
          "issuedAt": "2026-10-18T19:30:00Z",
          "itemId": "id_8h2k4q",
          "keyId": "id_8h2k4q",
          "kind": "string",
          "preparationId": "id_8h2k4q",
          "publication": {},
          "quality": "string",
          "qualityLabel": "string",
          "receiptId": "id_8h2k4q",
          "version": "string",
          "viewer": {}
        },
        "keyId": "id_8h2k4q",
        "payload": "string",
        "receiptId": "id_8h2k4q",
        "revision": 0,
        "signature": "string"
      },
      "receiptId": "id_8h2k4q",
      "titleOnServer": true,
      "viewing": {
        "positionMs": 1800000,
        "watched": true
      }
    }
  ]
}

Schema

resultsarray of objectrequired
- codestring
- outcomestringrequired
- preparationIdstring
- receiptobject
  - algorithmstringrequired
  - claimsobjectrequired
    artifactobjectrequired
    bytesintegerrequired
    sha256stringrequired
    expiresAtstringrequired
    issuedAtstringrequired
    itemIdstringrequired
    keyIdstringrequired
    kindstringrequired
    preparationIdstringrequired
    publicationobject
    documentSha256stringrequiredpattern ^[0-9a-f]{64}$
    formatstringrequiredone of "epub", "pdf", "cbz", "cb7", "cbr"
    revisionstringrequiredpattern ^[0-9a-f]{64}$
    sourceIdstringrequiredlength 1–128pattern ^[A-Za-z0-9_-]+$
    qualitystringrequired
    qualityLabelstringrequired
    receiptIdstringrequired
    versionstringrequired
    viewerobjectrequired
    accountIdstringrequired
    authoritystringrequired
    profileIdstringrequired
    serverIdstringrequired
  - keyIdstringrequired
  - payloadstringrequired
  - receiptIdstringrequired
  - revisionintegerrequired
  - signaturestringrequired
- receiptIdstring
- titleOnServerboolean
- viewingobject
  - positionMsintegerrequired≥ 0
  - watchedbooleanrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Example request

curl -X POST "http://127.0.0.1:32500/v1/downloads/receipts/revalidate" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operationId":"id_8h2k4q","receiptIds":["string"]}'

GET/v1/downloads/receipts/revocationsPage the receipts that have been withdrawnread

Audience: Clients · Native API
Authorization: API key or personal access token with the read scope, or a signed-in session
OpenAPI operation ID: list_download_revocations

Parameters

Name	In	Type
`cursor`	query	`string`
`limit`	query	`integer`
`scope`	query	`string`

Responses

200Successapplication/json

Example

{
  "asOf": "string",
  "items": [
    {
      "itemId": "id_8h2k4q",
      "profileId": "id_8h2k4q",
      "reason": "string",
      "receiptId": "id_8h2k4q",
      "revokedAt": "2026-10-18T19:30:00Z",
      "sequence": 0
    }
  ],
  "nextCursor": "eyJvIjoyMH0"
}

Schema

asOfstringrequired
itemsarray of objectrequired
- itemIdstringrequired
- profileIdstringrequired
- reasonstringrequired
- receiptIdstringrequired
- revokedAtstringrequired
- sequenceintegerrequired
nextCursorstringrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittedfeature_restrictednot_founddownloads_not_alloweddownloads_unavailableinternaltimeoutdatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/receipts/revocations" \
  -H "Authorization: Bearer $PORTICO_API_KEY"

POST/v1/downloads/receipts/revokeWithdraw offline permission from copies on devicesplayback

Audience: Clients · Native API
Authorization: API key or personal access token with the playback scope, or a signed-in session
OpenAPI operation ID: revoke_download_receipts
Max body: 32 KiB

Request body application/json · required

Example

{
  "allProfiles": true,
  "operationId": "id_8h2k4q",
  "reason": "string",
  "receiptIds": [
    "string"
  ]
}

Schema

allProfilesboolean
operationIdstringrequired
reasonstring
receiptIdsarray of stringrequired

Responses

200Successapplication/json

Example

{
  "results": [
    {
      "code": "string",
      "outcome": "string",
      "preparationId": "id_8h2k4q",
      "receipt": {
        "algorithm": "string",
        "claims": {
          "artifact": {},
          "expiresAt": "2026-10-18T19:30:00Z",
          "issuedAt": "2026-10-18T19:30:00Z",
          "itemId": "id_8h2k4q",
          "keyId": "id_8h2k4q",
          "kind": "string",
          "preparationId": "id_8h2k4q",
          "publication": {},
          "quality": "string",
          "qualityLabel": "string",
          "receiptId": "id_8h2k4q",
          "version": "string",
          "viewer": {}
        },
        "keyId": "id_8h2k4q",
        "payload": "string",
        "receiptId": "id_8h2k4q",
        "revision": 0,
        "signature": "string"
      },
      "receiptId": "id_8h2k4q",
      "titleOnServer": true,
      "viewing": {
        "positionMs": 1800000,
        "watched": true
      }
    }
  ]
}

Schema

resultsarray of objectrequired
- codestring
- outcomestringrequired
- preparationIdstring
- receiptobject
  - algorithmstringrequired
  - claimsobjectrequired
    artifactobjectrequired
    bytesintegerrequired
    sha256stringrequired
    expiresAtstringrequired
    issuedAtstringrequired
    itemIdstringrequired
    keyIdstringrequired
    kindstringrequired
    preparationIdstringrequired
    publicationobject
    documentSha256stringrequiredpattern ^[0-9a-f]{64}$
    formatstringrequiredone of "epub", "pdf", "cbz", "cb7", "cbr"
    revisionstringrequiredpattern ^[0-9a-f]{64}$
    sourceIdstringrequiredlength 1–128pattern ^[A-Za-z0-9_-]+$
    qualitystringrequired
    qualityLabelstringrequired
    receiptIdstringrequired
    versionstringrequired
    viewerobjectrequired
    accountIdstringrequired
    authoritystringrequired
    profileIdstringrequired
    serverIdstringrequired
  - keyIdstringrequired
  - payloadstringrequired
  - receiptIdstringrequired
  - revisionintegerrequired
  - signaturestringrequired
- receiptIdstring
- titleOnServerboolean
- viewingobject
  - positionMsintegerrequired≥ 0
  - watchedbooleanrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Example request

curl -X POST "http://127.0.0.1:32500/v1/downloads/receipts/revoke" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allProfiles":true,"operationId":"id_8h2k4q","reason":"string","receiptIds":["string"]}'

GET/v1/downloads/requestsList the whole-show, season, album, book and playlist downloads a device startedread

Audience: Clients · Native API
Authorization: API key or personal access token with the read scope, or a signed-in session
OpenAPI operation ID: list_download_requests

Parameters

Name	In	Type
`deviceId`	query	`string`
`cursor`	query	`string`
`limit`	query	`integer \| ""`1–50

Responses

200Successapplication/json

Example

{
  "nextCursor": "eyJvIjoyMH0",
  "requests": [
    {
      "createdAt": "2026-10-18T19:30:00Z",
      "quality": "string",
      "requestId": "id_8h2k4q",
      "state": "string",
      "target": {
        "id": "id_8h2k4q",
        "kind": "string"
      },
      "title": "Fargo"
    }
  ]
}

Schema

nextCursorstring
requestsarray of objectrequired
- createdAtstringrequired
- qualitystringrequired
- requestIdstringrequired
- statestringrequired
- targetobjectrequired
  - idstringrequired
  - kindstringrequired
- titlestringrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittedfeature_restrictednot_founddownloads_not_alloweddownloads_unavailableinternaltimeoutdatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/requests" \
  -H "Authorization: Bearer $PORTICO_API_KEY"

POST/v1/downloads/requestsQueue all visible members of a container for offline preparationplayback

Audience: Clients · Native API
Authorization: API key or personal access token with the playback scope, or a signed-in session
OpenAPI operation ID: create_download_request
Max body: 8 KiB

Request body application/json · required

Example

{
  "deviceId": "id_8h2k4q",
  "operationId": "id_8h2k4q",
  "policy": {
    "episodes": "all",
    "keepNext": 1
  },
  "quality": "original",
  "target": {
    "id": "id_8h2k4q",
    "kind": "show"
  }
}

Schema

deviceIdstringrequiredpattern ^[A-Za-z0-9_-]{1,160}$
operationIdstringrequiredpattern ^[A-Za-z0-9_-]{1,160}$
policyobjectrequired
- episodesstringrequiredone of "all", "unwatched", "next"
- keepNextinteger1–10000
qualitystringone of "original", "automatic", "2160p", "1080p-high", "1080p-low", "720p-high", "720p-low", "480p", "240p", "cd-quality", "320", "96"
targetobjectrequired
- idstringrequiredpattern ^[A-Za-z0-9_-]{1,160}$
- kindstringrequiredone of "show", "season", "album", "book", "playlist"

Responses

202Successapplication/json

Example

{
  "errorCode": "string",
  "failed": 0,
  "items": [
    {
      "itemId": "id_8h2k4q",
      "preparation": {
        "actions": [
          "string"
        ],
        "artifact": {
          "bytes": 0,
          "container": "string",
          "contentType": "string",
          "estimated": true,
          "fileName": "Fargo",
          "kind": "string",
          "ref": "string",
          "sha256": "string"
        },
        "batchId": "id_8h2k4q",
        "createdAt": "2026-10-18T19:30:00Z",
        "expiresAt": "2026-10-18T19:30:00Z",
        "id": "id_8h2k4q",
        "itemId": "id_8h2k4q",
        "libraryId": "id_8h2k4q",
        "origin": "string",
        "profileId": "id_8h2k4q",
        "progress": {
          "bytesDone": 0,
          "bytesTotal": 0,
          "bytesTotalEstimated": true,
          "etaMs": 1800000,
          "percent": 0
        },
        "quality": "string",
        "readyAt": "2026-10-18T19:30:00Z",
        "reason": "string",
        "revision": 0,
        "state": "string",
        "title": {
          "artist": "string",
          "durationMs": 1800000,
          "groupId": "id_8h2k4q",
          "groupNumber": 0,
          "groupTitle": "Fargo",
          "kind": "string",
          "number": 0,
          "onServer": true,
          "parentId": "id_8h2k4q",
          "parentTitle": "Fargo",
          "title": "Fargo",
          "year": 0
        },
        "updatedAt": "2026-10-18T19:30:00Z",
        "versionId": "id_8h2k4q"
      },
      "reason": "string"
    }
  ],
  "nextCursor": "eyJvIjoyMH0",
  "paused": 0,
  "preparing": 0,
  "queued": 0,
  "ready": 0,
  "requestId": "id_8h2k4q",
  "state": "string",
  "total": 0,
  "totalKnown": true
}

Schema

errorCodestring
failedintegerrequired
itemsarray of objectrequired
- itemIdstringrequired
- preparationobject
  - actionsarray of stringrequired
  - artifactobjectrequired
    bytesintegerrequired
    containerstring
    contentTypestring
    estimatedbooleanrequired
    fileNamestring
    kindstringrequired
    refstring
    sha256string
  - batchIdstring
  - createdAtstringrequired
  - expiresAtstring
  - idstringrequired
  - itemIdstringrequired
  - libraryIdstringrequired
  - originstringrequired
  - profileIdstringrequired
  - progressobjectrequired
    bytesDoneintegerrequired
    bytesTotalintegerrequired
    bytesTotalEstimatedbooleanrequired
    etaMsinteger | any | nullrequired
    percentnumberrequired
  - qualitystringrequired
  - readyAtstring
  - reasonstring
  - revisionintegerrequired
  - statestringrequired
  - titleobjectrequired
    artiststring
    durationMsinteger≥ 0
    groupIdstring
    groupNumberinteger
    groupTitlestring
    kindstringrequired
    numberinteger
    onServerbooleanrequired
    parentIdstring
    parentTitlestring
    titlestringrequired
    yearinteger
  - updatedAtstringrequired
  - versionIdstringrequired
- reasonstring
nextCursorstring
pausedintegerrequired
preparingintegerrequired
queuedintegerrequired
readyintegerrequired
requestIdstringrequired
statestringrequired
totalintegerrequired
totalKnownbooleanrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittednot_foundidempotency_key_reusedrate_limitedinternaltimeoutdatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/downloads/requests" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deviceId":"id_8h2k4q","operationId":"id_8h2k4q","policy":{"episodes":"all","keepNext":1},"quality":"original","target":{"id":"id_8h2k4q","kind":"show"}}'

GET/v1/downloads/requests/{id}Read visible request counts and a window of preparationsread

Audience: Clients · Native API
Authorization: API key or personal access token with the read scope, or a signed-in session
OpenAPI operation ID: get_download_request

Parameters

Name	In	Type
`id`required	path	`string`
`cursor`	query	`string`
`limit`	query	`integer \| ""`0–100

Responses

200Successapplication/json

Example

{
  "errorCode": "string",
  "failed": 0,
  "items": [
    {
      "itemId": "id_8h2k4q",
      "preparation": {
        "actions": [
          "string"
        ],
        "artifact": {
          "bytes": 0,
          "container": "string",
          "contentType": "string",
          "estimated": true,
          "fileName": "Fargo",
          "kind": "string",
          "ref": "string",
          "sha256": "string"
        },
        "batchId": "id_8h2k4q",
        "createdAt": "2026-10-18T19:30:00Z",
        "expiresAt": "2026-10-18T19:30:00Z",
        "id": "id_8h2k4q",
        "itemId": "id_8h2k4q",
        "libraryId": "id_8h2k4q",
        "origin": "string",
        "profileId": "id_8h2k4q",
        "progress": {
          "bytesDone": 0,
          "bytesTotal": 0,
          "bytesTotalEstimated": true,
          "etaMs": 1800000,
          "percent": 0
        },
        "quality": "string",
        "readyAt": "2026-10-18T19:30:00Z",
        "reason": "string",
        "revision": 0,
        "state": "string",
        "title": {
          "artist": "string",
          "durationMs": 1800000,
          "groupId": "id_8h2k4q",
          "groupNumber": 0,
          "groupTitle": "Fargo",
          "kind": "string",
          "number": 0,
          "onServer": true,
          "parentId": "id_8h2k4q",
          "parentTitle": "Fargo",
          "title": "Fargo",
          "year": 0
        },
        "updatedAt": "2026-10-18T19:30:00Z",
        "versionId": "id_8h2k4q"
      },
      "reason": "string"
    }
  ],
  "nextCursor": "eyJvIjoyMH0",
  "paused": 0,
  "preparing": 0,
  "queued": 0,
  "ready": 0,
  "requestId": "id_8h2k4q",
  "state": "string",
  "total": 0,
  "totalKnown": true
}

Schema

errorCodestring
failedintegerrequired
itemsarray of objectrequired
- itemIdstringrequired
- preparationobject
  - actionsarray of stringrequired
  - artifactobjectrequired
    bytesintegerrequired
    containerstring
    contentTypestring
    estimatedbooleanrequired
    fileNamestring
    kindstringrequired
    refstring
    sha256string
  - batchIdstring
  - createdAtstringrequired
  - expiresAtstring
  - idstringrequired
  - itemIdstringrequired
  - libraryIdstringrequired
  - originstringrequired
  - profileIdstringrequired
  - progressobjectrequired
    bytesDoneintegerrequired
    bytesTotalintegerrequired
    bytesTotalEstimatedbooleanrequired
    etaMsinteger | any | nullrequired
    percentnumberrequired
  - qualitystringrequired
  - readyAtstring
  - reasonstring
  - revisionintegerrequired
  - statestringrequired
  - titleobjectrequired
    artiststring
    durationMsinteger≥ 0
    groupIdstring
    groupNumberinteger
    groupTitlestring
    kindstringrequired
    numberinteger
    onServerbooleanrequired
    parentIdstring
    parentTitlestring
    titlestringrequired
    yearinteger
  - updatedAtstringrequired
  - versionIdstringrequired
- reasonstring
nextCursorstring
pausedintegerrequired
preparingintegerrequired
queuedintegerrequired
readyintegerrequired
requestIdstringrequired
statestringrequired
totalintegerrequired
totalKnownbooleanrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittednot_foundidempotency_key_reusedrate_limitedinternaltimeoutdatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/requests/{id}" \
  -H "Authorization: Bearer $PORTICO_API_KEY"

GET/v1/downloads/settingsRead the owner's download settingsread

Audience: Clients · Native API
Authorization: API key or personal access token with the read scope, or a signed-in session
OpenAPI operation ID: get_download_settings

Responses

200Successapplication/json

Example

{
  "maxPreparedBytes": 0,
  "qualities": [
    {
      "dataGBPerHour": 0,
      "kind": "string",
      "label": "string",
      "maxAudioBitrateBps": 0,
      "maxVideoBitrateBps": 0,
      "quality": "string",
      "targetDisplayHeight": 0
    }
  ],
  "retentionDays": 0,
  "revision": 0
}

Schema

maxPreparedBytesintegerrequired
qualitiesarray of objectrequired
- dataGBPerHournumber
- kindstringrequired
- labelstringrequired
- maxAudioBitrateBpsinteger
- maxVideoBitrateBpsinteger
- qualitystringrequired
- targetDisplayHeightinteger
retentionDaysintegerrequired
revisionintegerrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittedfeature_restrictednot_founddownloads_not_alloweddownloads_unavailableinternaltimeoutdatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/settings" \
  -H "Authorization: Bearer $PORTICO_API_KEY"

PUT/v1/downloads/settingsChange the owner's download settingsadmin

Audience: Clients · Native API
Authorization: API key or personal access token with the admin scope, or a signed-in session
OpenAPI operation ID: put_download_settings
Max body: 4 KiB

Parameters

Name	In	Type	Description
`Idempotency-Key`	header	`string`
`Portico-Mutation-Root`	header	`string`

Request body application/json · required

Example

{
  "expectedRevision": 0,
  "maxPreparedBytes": 0,
  "operationId": "id_8h2k4q",
  "retentionDays": 0
}

Schema

expectedRevisionintegerrequired
maxPreparedBytesintegerrequired
operationIdstringrequired
retentionDaysintegerrequired

Responses

200Successapplication/json

Example

{
  "maxPreparedBytes": 0,
  "qualities": [
    {
      "dataGBPerHour": 0,
      "kind": "string",
      "label": "string",
      "maxAudioBitrateBps": 0,
      "maxVideoBitrateBps": 0,
      "quality": "string",
      "targetDisplayHeight": 0
    }
  ],
  "retentionDays": 0,
  "revision": 0
}

Schema

maxPreparedBytesintegerrequired
qualitiesarray of objectrequired
- dataGBPerHournumber
- kindstringrequired
- labelstringrequired
- maxAudioBitrateBpsinteger
- maxVideoBitrateBpsinteger
- qualitystringrequired
- targetDisplayHeightinteger
retentionDaysintegerrequired
revisionintegerrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Example request

curl -X PUT "http://127.0.0.1:32500/v1/downloads/settings" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0,"maxPreparedBytes":0,"operationId":"id_8h2k4q","retentionDays":0}'

GET/v1/downloads/usageRead how much this viewer, or the whole server, has claimedread

Audience: Clients · Native API
Authorization: API key or personal access token with the read scope, or a signed-in session
OpenAPI operation ID: get_download_usage

Parameters

Name	In	Type
`scope`	query	`string`
`cursor`	query	`string`
`limit`	query	`integer \| ""`1–256

Responses

200Successapplication/json

Example

{
  "distinctArtifactBytes": 0,
  "maxPreparedBytes": 0,
  "profileBytes": 0,
  "profileCount": 0,
  "profileId": "id_8h2k4q",
  "profiles": [
    {
      "accountId": "id_8h2k4q",
      "accountName": "Fargo",
      "authority": "string",
      "bytes": 0,
      "count": 0,
      "profileId": "id_8h2k4q",
      "profileKey": "string",
      "profileName": "Fargo",
      "storedBytes": 0
    }
  ],
  "profilesNextCursor": "eyJvIjoyMH0",
  "remainingBytes": 0,
  "retentionDays": 0,
  "serverBytes": 0,
  "serverCount": 0
}

Schema

distinctArtifactBytesintegerrequired
maxPreparedBytesintegerrequired
profileBytesintegerrequired
profileCountintegerrequired
profileIdstringrequired
profilesarray of objectrequired
- accountIdstringrequired
- accountNamestringrequired
- authoritystringrequired
- bytesintegerrequired
- countintegerrequired
- profileIdstringrequired
- profileKeystringrequired
- profileNamestringrequired
- storedBytesintegerrequired
profilesNextCursorstringrequired
remainingBytesinteger | any | nullrequired
retentionDaysintegerrequired
serverBytesintegerrequired
serverCountintegerrequired

defaultRequest refused or unavailableapplication/json

Example

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittedfeature_restrictednot_founddownloads_not_alloweddownloads_unavailableinternaltimeoutdatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/downloads/usage" \
  -H "Authorization: Bearer $PORTICO_API_KEY"