RecommendationsResponse

Response from GET /api/v1/user/recommendations

Recommendations from all enabled recommendation-provider instances are merged into a single list (deduped by external ID, highest score wins, reasons combined), each item tagged with its source/sourcePlugin. sources carries per-instance status so the UI can show provenance and per-source refresh/staleness state.

recommendations object[]required

Merged, deduped recommendations across all enabled provider instances

Array [

basedOnstring[]

Titles that influenced this recommendation

codexSeriesIdstring | nullnullable

Codex series ID if matched to an existing series

countryOfOriginstring | nullnullable

Country of origin ISO code (e.g., "JP", "KR", "CN")

coverUrlstring | nullnullable

Cover image URL

externalIdstringrequired

External ID on the source service

externalUrlstring | nullnullable

URL to the entry on the external service

formatstring | nullnullable

Media format (e.g., "MANGA", "NOVEL", "ONE_SHOT")

genresstring[]

Genres

inCodexboolean

Whether this series exists in the Codex library (matched via external IDs)

inLibraryboolean

Whether this series is already in the user's library (as reported by the plugin)

popularityinteger,null<int32>nullable

Popularity ranking/count on the source service

ratinginteger,null<int32>nullable

Average user rating on the source service (0-100 scale)

reasonstringrequired

Human-readable reason for this recommendation

scorenumber<double>required

Confidence/relevance score (0.0 to 1.0)

sourcestring

External ID source of the producing plugin (e.g. "anilist"). Used by the UI to filter/group by source.

sourcePluginstring

Display name of the plugin instance that produced this recommendation. When the same item is recommended by several instances, this is the highest-scoring contributor.

startYearinteger,null<int32>nullable

Year the series started

statusstring | nullnullable

Publication status (ongoing, ended, hiatus, abandoned, unknown)

summarystring | nullnullable

Summary/description

tags object[]

Tags with relevance rank

Array [

categorystringrequired

Tag category (e.g., "Genre", "Theme")

namestringrequired

Tag name (e.g., "Isekai", "Gore")

rankinteger<int32>required

Relevance rank (0-100)

]

titlestringrequired

Title of the recommended series/book

totalChapterCountnumber,null<float>nullable

Total expected number of chapters in the series. May be fractional.

totalVolumeCountinteger,null<int32>nullable

Total expected number of volumes in the series.

]

sources object[]

The provider instances that contributed (status, provenance)

Array [

cachedboolean

Whether this instance's results came from cache

generatedAtstring | nullnullable

When this instance's recommendations were generated

pluginIdstring<uuid>required

Plugin ID

pluginNamestringrequired

Plugin display name

sourcestring

External ID source of this plugin (e.g. "anilist").

taskIdstring,null<uuid>nullable

ID of the running/pending refresh task for this instance, if any

taskStatusstring | nullnullable

Status of a running/pending refresh task for this instance, if any

]

RecommendationsResponse

{
  "recommendations": [
    {
      "basedOn": [
        "string"
      ],
      "codexSeriesId": "string",
      "countryOfOrigin": "string",
      "coverUrl": "string",
      "externalId": "string",
      "externalUrl": "string",
      "format": "string",
      "genres": [
        "string"
      ],
      "inCodex": true,
      "inLibrary": true,
      "popularity": 0,
      "rating": 0,
      "reason": "string",
      "score": 0,
      "source": "string",
      "sourcePlugin": "string",
      "startYear": 0,
      "status": "string",
      "summary": "string",
      "tags": "Unknown Type: array,null",
      "title": "string",
      "totalChapterCount": 0,
      "totalVolumeCount": 0
    }
  ],
  "sources": [
    {
      "cached": true,
      "generatedAt": "string",
      "pluginId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "pluginName": "string",
      "source": "string",
      "taskId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "taskStatus": "string"
    }
  ]
}