Albums

Generated albums operations.

GET/v1/albums/{id}/metadata/musicbrainzRead album metadata musicbrainzlibrary

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

Parameters

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

Responses

200Successapplication/json

Example

{
  "actions": [
    "string"
  ],
  "attempts": 0,
  "attribution": "string",
  "candidates": [
    {
      "artist": "string",
      "confidence": 0,
      "decision": "string",
      "edition": "string",
      "id": "id_8h2k4q",
      "observedAt": "2026-10-18T19:30:00Z",
      "reasons": [
        "string"
      ],
      "title": "Fargo"
    }
  ],
  "entityId": "id_8h2k4q",
  "error": "string",
  "kind": "string",
  "libraryId": "id_8h2k4q",
  "manual": true,
  "nextAttempt": "string",
  "observation": {
    "algorithm": "string",
    "confidence": 0,
    "fingerprintStatus": "string",
    "margin": 0,
    "providerError": "string",
    "strongSignals": 0
  },
  "policy": {
    "acoustidConfigured": true,
    "acoustidEnabled": true,
    "fingerprintAllowed": true,
    "localMode": "string",
    "musicBrainzEnabled": true,
    "revision": 0
  },
  "published": {
    "artist": "string",
    "country": "string",
    "date": "string",
    "details": {
      "barcode": "string",
      "credits": [
        {
          "artist": {},
          "joinphrase": "string",
          "name": "Fargo"
        }
      ],
      "isrcs": [
        "string"
      ],
      "labels": [
        {
          "catalog-number": "string",
          "label": {}
        }
      ],
      "language": "en",
      "packaging": "string",
      "relations": [
        {
          "artist": {},
          "attributes": [],
          "direction": "string",
          "target-type": "string",
          "type": "string",
          "type-id": "id_8h2k4q",
          "work": {}
        }
      ],
      "script": "string",
      "status": "string"
    },
    "matchedTracks": 0,
    "observedAt": "2026-10-18T19:30:00Z",
    "pendingTracks": 0,
    "reconciliationPending": true,
    "recordingId": "id_8h2k4q",
    "releaseGroupId": "id_8h2k4q",
    "releaseId": "id_8h2k4q",
    "reviewTracks": 0,
    "title": "Fargo",
    "totalTracks": 0,
    "trackId": "id_8h2k4q",
    "trackStatus": "string",
    "trackTitle": "Fargo"
  },
  "revision": 0,
  "selectedId": "id_8h2k4q",
  "serverId": "id_8h2k4q",
  "status": "string",
  "viewerFence": "string"
}

Schema

actionsarray of stringrequired
attemptsintegerrequired
attributionstringrequired
candidatesarray of objectrequired
- artiststringrequired
- confidencenumberrequired
- decisionstringrequired
- editionstringrequired
- idstringrequired
- observedAtstringrequired
- reasonsarray of stringrequired
- titlestringrequired
entityIdstringrequired
errorstringrequired
kindstringrequired
libraryIdstringrequired
manualbooleanrequired
nextAttemptstringrequired
observationobject
- algorithmstringrequired
- confidencenumberrequired
- fingerprintStatusstringrequired
- marginnumberrequired
- providerErrorstringrequired
- strongSignalsintegerrequired
policyobject
- acoustidConfiguredbooleanrequired
- acoustidEnabledbooleanrequired
- fingerprintAllowedbooleanrequired
- localModestringrequired
- musicBrainzEnabledbooleanrequired
- revisionintegerrequired
publishedobject
- artiststringrequired
- countrystringrequired
- datestringrequired
- detailsobject
  - barcodestring
  - creditsarray of objectrequired
    artistobjectrequired
    disambiguationstringrequired
    idstringrequired
    namestringrequired
    sort-namestringrequired
    joinphrasestringrequired
    namestringrequired
  - isrcsarray of stringrequired
  - labelsarray of objectrequired
    catalog-numberstringrequired
    labelobject
    idstringrequired
    namestringrequired
  - languagestring
  - packagingstring
  - relationsarray of objectrequired
    artistobject
    disambiguationstringrequired
    idstringrequired
    namestringrequired
    sort-namestringrequired
    attributesarray of string
    directionstring
    target-typestringrequired
    typestringrequired
    type-idstring
    workobject
    disambiguationstring
    idstringrequired
    titlestringrequired
    typestring
  - scriptstring
  - statusstring
- matchedTracksintegerrequired
- observedAtstringrequired
- pendingTracksintegerrequired
- reconciliationPendingbooleanrequired
- recordingIdstringrequired
- releaseGroupIdstringrequired
- releaseIdstringrequired
- reviewTracksintegerrequired
- titlestringrequired
- totalTracksintegerrequired
- trackIdstringrequired
- trackStatusstringrequired
- trackTitlestringrequired
revisionintegerrequired
selectedIdstringrequired
serverIdstringrequired
statusstringrequired
viewerFencestringrequired

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/albums/{id}/metadata/musicbrainz" \
  -H "Authorization: Bearer $PORTICO_API_KEY"

PUT/v1/albums/{id}/metadata/musicbrainzSave album metadata musicbrainzlibrary

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

Parameters

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

Request body application/json · required

Example

{
  "expectedRevision": 0,
  "providerId": "id_8h2k4q"
}

Schema

expectedRevisionintegerrequired
providerIdstringrequired

Responses

202Successapplication/json

Example

{
  "entityId": "id_8h2k4q",
  "status": "string"
}

Schema

entityIdstringrequired
statusstringrequired

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/albums/{id}/metadata/musicbrainz" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0,"providerId":"id_8h2k4q"}'

POST/v1/albums/{id}/metadata/musicbrainz/policyRun album metadata musicbrainz policylibrary

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

Parameters

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

Request body application/json · required

Example

{
  "acoustidEnabled": true,
  "expectedPolicyRevision": 0,
  "expectedRevision": 0,
  "localMode": "string",
  "musicBrainzEnabled": true
}

Schema

acoustidEnabledbooleanrequired
expectedPolicyRevisionintegerrequired
expectedRevisionintegerrequired
localModestringrequired
musicBrainzEnabledbooleanrequired

Responses

202Successapplication/json

Example

{
  "entityId": "id_8h2k4q",
  "status": "string"
}

Schema

entityIdstringrequired
statusstringrequired

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/albums/{id}/metadata/musicbrainz/policy" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"acoustidEnabled":true,"expectedPolicyRevision":0,"expectedRevision":0,"localMode":"string","musicBrainzEnabled":true}'

POST/v1/albums/{id}/metadata/musicbrainz/retryRun album metadata musicbrainz retrylibrary

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

Parameters

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

Request body application/json · required

Example

{
  "expectedRevision": 0
}

Schema

expectedRevisionintegerrequired

Responses

202Successapplication/json

Example

{
  "entityId": "id_8h2k4q",
  "status": "string"
}

Schema

entityIdstringrequired
statusstringrequired

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/albums/{id}/metadata/musicbrainz/retry" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0}'

POST/v1/albums/{id}/metadata/musicbrainz/searchRun album metadata musicbrainz searchlibrary

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

Parameters

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

Request body application/json · required

Example

{
  "expectedRevision": 0
}

Schema

expectedRevisionintegerrequired

Responses

202Successapplication/json

Example

{
  "entityId": "id_8h2k4q",
  "status": "string"
}

Schema

entityIdstringrequired
statusstringrequired

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/albums/{id}/metadata/musicbrainz/search" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0}'

GET/v1/albums/{id}/songsRead album songsread

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

Parameters

Name	In	Type
`id`required	path	`string`
`cursor`	query	`string`
`limit`	query	`integer`

Responses

200Successapplication/json

Example

{
  "nextCursor": "eyJvIjoyMH0",
  "songs": [
    {
      "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
    }
  ]
}

Schema

nextCursorstringrequired
songsarray 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

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/albums/{id}/songs" \
  -H "Authorization: Bearer $PORTICO_API_KEY"