Integration API v1

Quven Integration API

Read-only reporting for third-party software: what this installation is, which libraries it serves, what it holds, and what is playing right now.

OpenAPI document (JSON) Integration guide

Server address Integration key

The key is used by this page only, to call the address above. It is never sent to quven.tv.

Keep the key for this tab, so a reload does not lose it

Authentication

An operator issues a key under Settings, Integrations. Send it as X-Quven-Key, or as Authorization: Bearer. Every route is a GET: a key changes nothing and cannot issue another.

Where requests go

The API belongs to a Quven server, not to Quven Cloud. Requests go to the address of the server that issued the key; quven.tv serves this reference and no API of its own.

Polling

Every read carries a weak ETag; send it back as If-None-Match for a 304 with no body. Sessions differ every time, since the answer carries the instant it was taken. A key is allowed 120 requests a minute, counted per key.

Uptime

GET /health/live answers 200 with no key and is what a monitor should poll. Start time is in the reads: startedUtc, and quven_server_start_time_seconds in the metrics.

GET /api/integration/v1/server

Return this installation's identity and version

Answer IntegrationServerDto · 5 fields

Field	Type
`apiVersion`	int32
`name`	string
`serverId`	uuid
`startedUtc`	date-time
`version`	string

GET /api/integration/v1/server

{
  "serverId": "2f1c0f5e-7f5a-4a1e-9d3f-8c9a1b2c3d4e",
  "name": "Living room",
  "version": "1.1.11",
  "apiVersion": 1,
  "startedUtc": "2026-08-27T18:04:11.000Z"
}

GET /api/integration/v1/libraries

Return the libraries this installation serves

Answer IntegrationLibraryListDto · 1 field

Field	Type
`items`	IntegrationLibraryDto[]

GET /api/integration/v1/libraries

{
  "items": [
    {
      "id": "9b7d5a10-2c44-4f31-8a0b-5d6e7f801234",
      "name": "Films",
      "kind": "Movies",
      "fileCount": 2280,
      "lastScannedUtc": "2026-08-27T02:15:00.000Z"
    },
    {
      "id": "c4e8f2b1-6a37-4c58-9e10-2b3c4d5e6f70",
      "name": "Series",
      "kind": "Shows",
      "fileCount": 14032,
      "lastScannedUtc": null
    }
  ]
}

GET /api/integration/v1/statistics

Return catalogue counts and storage size

Answer IntegrationStatisticsDto · 5 fields

Field	Type
`episodeCount`	int64
`fileCount`	int64
`movieCount`	int64
`showCount`	int64
`totalStorageBytes`	int64

GET /api/integration/v1/statistics

{
  "movieCount": 2280,
  "showCount": 190,
  "episodeCount": 14032,
  "fileCount": 16312,
  "totalStorageBytes": 41284773120
}

GET /api/integration/v1/sessions

Return the playback sessions in progress

Answer IntegrationSessionListDto · 3 fields

Field	Type
`items`	IntegrationSessionDto[]
`observedUtc`	date-time
`refreshAfterSeconds`	int32

GET /api/integration/v1/sessions

{
  "items": [
    {
      "mediaId": "7d1e2f30-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
      "title": "The Lives of Others",
      "kind": "Movie",
      "seriesTitle": null,
      "seasonNumber": null,
      "episodeNumber": null,
      "positionSeconds": 1832,
      "durationSeconds": 8340,
      "isTranscoding": false,
      "posterUrl": "https://image.tmdb.org/t/p/w342/8Gxv8gSFCU0XGDykEGv7zR1n2ua.jpg"
    }
  ],
  "observedUtc": "2026-08-27T20:41:09.000Z",
  "refreshAfterSeconds": 10
}

GET /api/integration/v1/history

Return finished playbacks, most recent first

Query parameters 2 parameters

Name	Type
`limit`	int32 · nullable
`offset`	int32 · nullable

Answer IntegrationHistoryPageDto · 4 fields

Field	Type
`items`	IntegrationHistoryEntryDto[]
`limit`	int32
`offset`	int32
`totalCount`	int32

GET /api/integration/v1/history

limit offset

{
  "items": [
    {
      "mediaId": "7d1e2f30-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
      "title": "The Lives of Others",
      "kind": "Movie",
      "subtitle": null,
      "startedUtc": "2026-08-26T21:02:44.000Z",
      "endedUtc": "2026-08-26T23:21:12.000Z",
      "positionSeconds": 8308,
      "watchedToEnd": true,
      "posterUrl": "https://image.tmdb.org/t/p/w342/8Gxv8gSFCU0XGDykEGv7zR1n2ua.jpg"
    }
  ],
  "totalCount": 4132,
  "offset": 0,
  "limit": 50
}

GET /api/integration/v1/metrics text/plain

Return the same counts in Prometheus exposition format

Answers text/plain rather than a JSON object.

GET /api/integration/v1/metrics

# HELP quven_movies_total Films in the catalogue.
# TYPE quven_movies_total gauge
quven_movies_total 2280
# HELP quven_library_files Physical media files per library.
# TYPE quven_library_files gauge
quven_library_files{library="Films",kind="Movies"} 2280
quven_library_files{library="Series",kind="Shows"} 14032
# HELP quven_sessions_active Playback sessions in progress.
# TYPE quven_sessions_active gauge
quven_sessions_active 1

Schemas 8 types

IntegrationHistoryEntryDto 9 fields

Field	Type
`endedUtc`	date-time
`kind`	string
`mediaId`	uuid
`positionSeconds`	int64
`posterUrl`	string · nullable
`startedUtc`	date-time
`subtitle`	string · nullable
`title`	string
`watchedToEnd`	boolean

IntegrationHistoryPageDto 4 fields

Field	Type
`items`	IntegrationHistoryEntryDto[]
`limit`	int32
`offset`	int32
`totalCount`	int32

IntegrationLibraryDto 5 fields

Field	Type
`fileCount`	int64
`id`	uuid
`kind`	string
`lastScannedUtc`	date-time · nullable
`name`	string

IntegrationLibraryListDto 1 fields

Field	Type
`items`	IntegrationLibraryDto[]

IntegrationServerDto 5 fields

Field	Type
`apiVersion`	int32
`name`	string
`serverId`	uuid
`startedUtc`	date-time
`version`	string

IntegrationSessionDto 10 fields

Field	Type
`durationSeconds`	int64 · nullable
`episodeNumber`	int32 · nullable
`isTranscoding`	boolean
`kind`	string
`mediaId`	uuid
`positionSeconds`	int64
`posterUrl`	string · nullable
`seasonNumber`	int32 · nullable
`seriesTitle`	string · nullable
`title`	string

IntegrationSessionListDto 3 fields

Field	Type
`items`	IntegrationSessionDto[]
`observedUtc`	date-time
`refreshAfterSeconds`	int32

IntegrationStatisticsDto 5 fields

Field	Type
`episodeCount`	int64
`fileCount`	int64
`movieCount`	int64
`showCount`	int64
`totalStorageBytes`	int64