Collections

Generated collections operations.

DELETE/v1/collections/{id}Remove collectionslibrary

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

Parameters

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

Responses

204Success

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittednot_foundinternaldatabase_busywriter_capacity

Example request

curl -X DELETE "http://127.0.0.1:32500/v1/collections/{id}" \
  -H "Authorization: Bearer $PORTICO_API_KEY"

GET/v1/collections/{id}Read collectionsread

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

Parameters

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

Responses

200Successapplication/json

Example

{
  "id": "id_8h2k4q",
  "itemCount": 0,
  "libraryId": "id_8h2k4q",
  "name": "Fargo",
  "origin": "string",
  "revision": 0
}

Schema

idstringrequired
itemCountintegerrequired
libraryIdstringrequired
namestringrequired
originstringrequired
revisionintegerrequired

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittednot_foundinternaldatabase_busy

Example request

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

PATCH/v1/collections/{id}Change collectionslibrary

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

Parameters

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

Request body application/json · required

Example

{
  "name": "Fargo"
}

Schema

namestringrequired

Responses

200Successapplication/json

Example

{
  "id": "id_8h2k4q",
  "itemCount": 0,
  "libraryId": "id_8h2k4q",
  "name": "Fargo",
  "origin": "string",
  "revision": 0
}

Schema

idstringrequired
itemCountintegerrequired
libraryIdstringrequired
namestringrequired
originstringrequired
revisionintegerrequired

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittednot_foundinternaldatabase_busywriter_capacity

Example request

curl -X PATCH "http://127.0.0.1:32500/v1/collections/{id}" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Fargo"}'

GET/v1/collections/{id}/itemsRead or update the selected projectionread

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

Parameters

Name	In	Type
`id`required	path	`string`
`sort`	query	`string`
`direction`	query	`string`
`category`	query	`string`
`q`	query	`string`
`cursor`	query	`string`
`limit`	query	`integer`

Responses

200Successapplication/json

Example

{
  "items": [
    {
      "addedAt": "2026-10-18T19:30:00Z",
      "audioFacts": {
        "atmos": true,
        "bitDepth": 0,
        "channels": 0,
        "codec": "string",
        "layout": "string",
        "lossless": true,
        "sampleRate": 0
      },
      "available": true,
      "backdropUrl": "https://example.com/…",
      "bookFile": {
        "bookId": "id_8h2k4q",
        "bookTitle": "Fargo",
        "discNumber": 0,
        "localMetadata": {
          "authors": [],
          "description": "string",
          "edition": "string",
          "identifiers": [],
          "language": "en",
          "narrators": [],
          "publishedYear": 0,
          "publisher": "string",
          "series": [],
          "sources": {}
        },
        "localMetadataIssue": "string",
        "localPolicy": {
          "localMode": "string",
          "revision": 0
        },
        "partNumber": 0,
        "sourceBoundary": "string"
      },
      "durationMs": 1800000,
      "durationState": "unrepresentable",
      "episode": {
        "airDate": "string",
        "localIdentityStatus": "string",
        "number": 0,
        "numbering": "string",
        "orderingBasis": "string",
        "providerMatchStatus": "string",
        "seasonId": "id_8h2k4q",
        "seasonNumber": 0,
        "showId": "id_8h2k4q",
        "showTitle": "Fargo",
        "sourceBoundary": "string"
      },
      "fileInfoOpening": "string",
      "id": "id_8h2k4q",
      "kind": "string",
      "libraryId": "id_8h2k4q",
      "missing": true,
      "overview": "string",
      "posterUrl": "https://example.com/…",
      "progressMs": 1800000,
      "song": {
        "albumArtist": "string",
        "albumId": "id_8h2k4q",
        "albumTitle": "Fargo",
        "artist": "string",
        "discNumber": 0,
        "localMetadataIssue": "string",
        "providerArtist": "string",
        "providerMatchStatus": "string",
        "providerObservedAt": "2026-10-18T19:30:00Z",
        "providerRecordingId": "id_8h2k4q",
        "providerReleaseGroupId": "id_8h2k4q",
        "providerReleaseId": "id_8h2k4q",
        "providerReleaseStatus": "string",
        "providerSourceUrl": "https://example.com/…",
        "providerTitle": "Fargo",
        "providerTrackId": "id_8h2k4q",
        "trackNumber": 0
      },
      "sources": [
        {
          "audioCodec": "string",
          "container": "string",
          "durationMs": 1800000,
          "height": 0,
          "id": "id_8h2k4q",
          "videoCodec": "string",
          "width": 0
        }
      ],
      "stillUrl": "https://example.com/…",
      "title": "Fargo",
      "watched": true,
      "year": 0
    }
  ],
  "nextCursor": "eyJvIjoyMH0"
}

Schema

itemsarray of objectrequired
- addedAtstring | any | nullrequired
- audioFactsobject
  - atmosboolean
  - bitDepthinteger
  - channelsinteger
  - codecstringrequired
  - layoutstring
  - losslessboolean
  - sampleRateinteger
- availablebooleanrequired
- backdropUrlstring
- bookFileobject
  - bookIdstringrequired
  - bookTitlestringrequired
  - discNumberinteger
  - localMetadataobject
    authorsarray of stringrequired
    descriptionstring
    editionstring
    identifiersarray of objectrequired
    schemestringrequired
    valuestringrequired
    languagestring
    narratorsarray of stringrequired
    publishedYearinteger
    publisherstring
    seriesarray of objectrequired
    namestringrequired
    positionstring
    sourcesobjectrequired
  - localMetadataIssuestring
  - localPolicyobject
    localModestringrequired
    revisionintegerrequired
  - partNumberinteger
  - sourceBoundarystringrequired
- durationMsinteger≥ 0
- durationStatestringone of "unrepresentable"
- episodeobject
  - airDatestring
  - localIdentityStatusstringrequired
  - numberintegerrequired
  - numberingstringrequired
  - orderingBasisstringrequired
  - providerMatchStatusstringrequired
  - seasonIdstring
  - seasonNumberinteger
  - showIdstringrequired
  - showTitlestringrequired
  - sourceBoundarystringrequired
- fileInfoOpeningstring
- idstringrequired
- kindstringrequired
- libraryIdstringrequired
- missingbooleanrequired
- overviewstring
- posterUrlstring
- progressMsintegerrequired≥ 0
- songobject
  - albumArtiststringrequired
  - albumIdstringrequired
  - albumTitlestringrequired
  - artiststringrequired
  - discNumberinteger
  - localMetadataIssuestring
  - providerArtiststring
  - providerMatchStatusstringrequired
  - providerObservedAtstring
  - providerRecordingIdstring
  - providerReleaseGroupIdstring
  - providerReleaseIdstring
  - providerReleaseStatusstringrequired
  - providerSourceUrlstring
  - providerTitlestring
  - providerTrackIdstring
  - trackNumberinteger
- sourcesarray of object
  - audioCodecstringrequired
  - containerstringrequired
  - durationMsintegerrequired≥ 0
  - heightintegerrequired
  - idstringrequired
  - videoCodecstringrequired
  - widthintegerrequired
- stillUrlstring
- titlestringrequired
- watchedboolean
- yearinteger
nextCursorstringrequired

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittednot_foundinternaldatabase_busy

Example request

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

POST/v1/collections/{id}/items:batchRun collections items batchlibrary

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

Parameters

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

Request body application/json · required

Example

{
  "addItemIds": [
    "string"
  ],
  "removeItemIds": [
    "string"
  ]
}

Schema

addItemIdsarray of stringrequired
removeItemIdsarray of stringrequired

Responses

200Successapplication/json

Example

{
  "collection": {
    "id": "id_8h2k4q",
    "itemCount": 0,
    "libraryId": "id_8h2k4q",
    "name": "Fargo",
    "origin": "string",
    "revision": 0
  },
  "entries": {
    "added": [
      "string"
    ],
    "failed": [
      {
        "code": "string",
        "itemId": "id_8h2k4q"
      }
    ],
    "removed": [
      "string"
    ],
    "unchanged": [
      "string"
    ]
  }
}

Schema

collectionobjectrequired
- idstringrequired
- itemCountintegerrequired
- libraryIdstringrequired
- namestringrequired
- originstringrequired
- revisionintegerrequired
entriesobjectrequired
- addedarray of stringrequired
- failedarray of objectrequired
  - codestringrequired
  - itemIdstringrequired
- removedarray of stringrequired
- unchangedarray of stringrequired

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittednot_foundinternaldatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/collections/{id}/items:batch" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"addItemIds":["string"],"removeItemIds":["string"]}'

DELETE/v1/collections/{id}/items/{itemId}Remove collections titlelibrary

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

Parameters

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

Responses

204Success

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittednot_foundinternaldatabase_busywriter_capacity

Example request

curl -X DELETE "http://127.0.0.1:32500/v1/collections/{id}/items/{itemId}" \
  -H "Authorization: Bearer $PORTICO_API_KEY"

PUT/v1/collections/{id}/items/{itemId}Save collections titlelibrary

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

Parameters

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

Responses

204Success

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittednot_foundinternaldatabase_busywriter_capacity

Example request

curl -X PUT "http://127.0.0.1:32500/v1/collections/{id}/items/{itemId}" \
  -H "Authorization: Bearer $PORTICO_API_KEY"

PUT/v1/collections/{id}/orderMove titles of a library collection (at most 200), fenced by its revisionlibrary

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

Parameters

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

Request body application/json · required

Example

{
  "afterItemId": "id_8h2k4q",
  "expectedRevision": 0,
  "itemIds": [
    "string"
  ]
}

Schema

afterItemIdstring
expectedRevisionintegerrequired
itemIdsarray of stringrequired

Responses

200Successapplication/json

Example

{
  "id": "id_8h2k4q",
  "itemCount": 0,
  "libraryId": "id_8h2k4q",
  "name": "Fargo",
  "origin": "string",
  "revision": 0
}

Schema

idstringrequired
itemCountintegerrequired
libraryIdstringrequired
namestringrequired
originstringrequired
revisionintegerrequired

defaultRequest refused or unavailableapplication/json

Example

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

Schema

errorobjectrequired
- codestringrequired
- messagestringrequired

Error codesinvalid_requestunauthorizednot_permittednot_foundrevision_mismatchinternaldatabase_busywriter_capacity

Example request

curl -X PUT "http://127.0.0.1:32500/v1/collections/{id}/order" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"afterItemId":"id_8h2k4q","expectedRevision":0,"itemIds":["string"]}'