Authorization: Bearer <api_key>, a partner API key created from the admin’s Utilisateurs tab. Each key carries its own named scopes — none are implicit — and its own access modes (api today, mcp reserved for a future MCP layer built on this same key system; a key without the right mode for a channel can never authenticate on it, regardless of its scopes). Base URL: https://es-epgdoctor.cedric-monnier.workers.dev/v1/api. Full machine-readable spec: /v1/api/openapi.json.
GET /channels
Liste des chaînes mémorisées
Required scope: channels:read
Renvoie chaque chaîne mémorisée disposant d’un channel_id réel (une source jamais vérifiée n’en a pas encore). Ne renvoie jamais l’URL du flux XML source. channel_id (valeur brute du provider) et channel_uuid (identifiant canonique de l’app, persistance garantie même si le provider renomme un jour la chaîne) sont tous deux exposés. player_url expose l’URL de lecture configurée (ou null), distincte de l’URL du feed EPG qui reste privée — chaque route channels/* accepte l’un ou l’autre.
Aucun paramètre de requête.
Exemple de réponse
{
"data": {
"channels": [
{
"channel_id": "raw_provider_id_123",
"channel_uuid": "3f1a2b4c-5d6e-7f89-a0b1-c2d3e4f56789",
"name": "Example Channel",
"provider": "OKAST",
"logo_url": "https://…",
"player_url": "https://example.test/live/master.m3u8",
"format": "xmltv",
"last_checked_at": "2026-08-24T10:00:00.000Z",
"has_errors": false
}
]
},
"meta": {
"count": 1
}
}
GET /channels/programs
Grille EPG d’une chaîne sur une plage donnée
Required scope: channels:read
Programmes connus pour une chaîne entre since et until (ISO 8601). Plage maximale : 31 jours. Un scope content:read supplémentaire (jamais requis, jamais un gate sur l’accès aux programmes eux-mêmes) enrichit chaque programme d’un champ iab_tags — les tags IAB Content Taxonomy 2.2 associés au TITRE de ce programme (pas à cette diffusion précise), destinés à enrichir le contexte passé au décision process de l’Ad Server pour le ciblage contextuel. Absent du tout sans ce scope ; un tableau vide (pas absent) si le scope est présent mais que le titre n’a encore aucun tag connu.
| Paramètre | Type | Requis | Note |
|---|---|---|---|
channel_id | string | non | channel_id ou channel_uuid requis (l’un des deux) |
channel_uuid | string | non | identifiant canonique de la chaîne, persistance garantie contrairement à channel_id — préférable pour un stockage long terme côté partenaire |
since | string | oui | |
until | string | oui |
Exemple de réponse
{
"data": {
"channel_id": "raw_provider_id_123",
"programs": [
{
"title": "Example Show",
"subtitle": null,
"description": null,
"start": "2026-08-24T10:00:00.000Z",
"end": "2026-08-24T10:30:00.000Z",
"category": [
"Documentaire"
],
"image_url": "https://example.test/programme.jpg",
"iab_tags": [
{
"taxonomy_version": "3.1",
"code": "640",
"label": "Television"
}
]
}
]
},
"meta": {
"count": 1,
"since": "2026-08-24T00:00:00.000Z",
"until": "2026-08-25T00:00:00.000Z"
}
}
POST /channels/refresh
Relance un contrôle sur une chaîne déjà mémorisée
Required scope: channels:write
Refait un fetch + parse réel de la source associée à ce channel_id et persiste le résultat — une vraie action avec effet de bord, pas une lecture passive. Nécessite le scope channels:write, jamais accordé par channels:read seul. channel_id ou channel_uuid requis dans le corps (l’un des deux).
Aucun paramètre de requête.
Corps de la requête
{
"channel_id": "raw_provider_id_123"
}
Exemple de réponse
{
"data": {
"channel_id": "raw_provider_id_123",
"checked_at": "2026-08-24T10:00:00.000Z",
"program_count": 42,
"issues_count": 0,
"valid": true,
"latest_epg_date": "2026-09-06T18:00:00.000Z"
}
}
GET /channels/quality
Analyse ADN d’une chaîne (structure de grille, diversité de titres, catégories)
Required scope: quality:read
range=week nécessite week_start (une date ISO, alignée automatiquement sur le lundi de cette semaine-là) ; range=90d (nom conservé par compatibilité) couvre toujours la fenêtre de rétention complète, soit 180 jours, aucun paramètre supplémentaire.
| Paramètre | Type | Requis | Note |
|---|---|---|---|
channel_id | string | non | channel_id ou channel_uuid requis (l’un des deux) |
channel_uuid | string | non | identifiant canonique de la chaîne, persistance garantie contrairement à channel_id — préférable pour un stockage long terme côté partenaire |
range | string (week | 90d) | oui | |
week_start | string | non | requis si range=week |
Exemple de réponse
{
"data": {
"channel_id": "raw_provider_id_123",
"dna": {
"catalogue_size": 128,
"top_category": {
"name": "Documentaire",
"pct": 62
}
},
"range": {
"since": "2026-08-24T00:00:00.000Z",
"until": "2026-08-31T00:00:00.000Z"
}
},
"meta": {
"truncated": false
}
}
GET /channels/heatmap
Grille hebdomadaire densité/fraîcheur/qualité, jour par jour et heure par heure
Required scope: quality:read
Même moteur que la «Vue hebdomadaire» de l’onglet Analyse.
| Paramètre | Type | Requis | Note |
|---|---|---|---|
channel_id | string | non | channel_id ou channel_uuid requis (l’un des deux) |
channel_uuid | string | non | identifiant canonique de la chaîne, persistance garantie contrairement à channel_id — préférable pour un stockage long terme côté partenaire |
week_start | string | oui |
Exemple de réponse
{
"data": {
"channel_id": "raw_provider_id_123",
"heatmap": {
"days": [
"Lun 24 août",
"…"
],
"cells": []
},
"range": {
"since": "2026-08-24T00:00:00.000Z",
"until": "2026-08-31T00:00:00.000Z"
}
},
"meta": {
"truncated": false
}
}
GET /channels/ad-load
Statistiques de charge publicitaire (quotidien/horaire)
Required scope: ad-load:read
Historique complet mergé (import quotidien et/ou coupures détaillées), pas une plage bornée — mêmes données que la carte «Ad Load Profile». Pour une chaîne avec un accès Broadpeak SSAI configuré (voir get_channel_ssai_heatmap), data.ssai_totals ajoute les vraies insertions/impressions publicitaires réellement comptées par Broadpeak sur EXACTEMENT la même période que data.stats.period, pour rapprocher inventaire planifié et activité réelle — sommées sur toutes les plateformes de distribution Broadpeak configurées pour cette chaîne (Rakuten TV, Xiaomi TV+, TCL, Plex...) ; data.ssai_by_platform détaille ce même total plateforme par plateforme (platform, service_id, warning, totals). meta.ssai_configured distingue les trois états réels : chaîne sans accès Broadpeak (false, data.ssai_totals null, jamais une erreur), chaîne configurée mais sans période à comparer faute de données ad-load importées (true, data.ssai_totals null, meta.ssai_warning null), et chaîne configurée avec un vrai résultat ou une vraie erreur Broadpeak (true, meta.ssai_warning expliquant le cas échéant pourquoi data.ssai_totals est resté null).
| Paramètre | Type | Requis | Note |
|---|---|---|---|
channel_id | string | non | channel_id ou channel_uuid requis (l’un des deux) |
channel_uuid | string | non | identifiant canonique de la chaîne, persistance garantie contrairement à channel_id — préférable pour un stockage long terme côté partenaire |
Exemple de réponse
{
"data": {
"channel_id": "raw_provider_id_123",
"stats": {
"period": {
"start": "2026-08-01",
"end": "2026-08-24",
"days": 24
},
"avails_per_day_avg": 96
},
"hourly_trend": {
"series": [],
"avg_avails_per_hour": 4
},
"ssai_totals": {
"insertions": 2184,
"impressions": 2091
},
"ssai_by_platform": [
{
"platform": "Rakuten TV",
"service_id": 75008,
"warning": null,
"totals": {
"insertions": 1200,
"impressions": 1150
}
},
{
"platform": "Xiaomi TV+",
"service_id": 75012,
"warning": null,
"totals": {
"insertions": 984,
"impressions": 941
}
}
]
},
"meta": {
"ssai_configured": true,
"ssai_warning": null
}
}
GET /channels/ad-fill-rate
Taux de remplissage Ad Server (coupures programmées vs décisions réelles)
Required scope: ad-load:read
Best-effort : si l’Ad Server est injoignable, une heatmap réelle revient quand même (tout en NO_REQUEST), avec ad_serving_warning expliquant pourquoi plutôt qu’une erreur.
| Paramètre | Type | Requis | Note |
|---|---|---|---|
channel_id | string | non | channel_id ou channel_uuid requis (l’un des deux) |
channel_uuid | string | non | identifiant canonique de la chaîne, persistance garantie contrairement à channel_id — préférable pour un stockage long terme côté partenaire |
week_start | string | oui |
Exemple de réponse
{
"data": {
"channel_id": "raw_provider_id_123",
"heatmap": {
"days": [],
"cells": []
},
"range": {
"since": "2026-08-24T00:00:00.000Z",
"until": "2026-08-31T00:00:00.000Z"
}
},
"meta": {
"ad_serving_warning": null
}
}
GET /channels/monetization
Revenus de monétisation importés (Rakuten et plateformes à venir)
Required scope: monetization:read
Statistiques de revenus (données RÉELLES d’argent généré, à distinguer de ad-load:read qui décrit un inventaire publicitaire structurel/planifié, jamais du revenu) calculées à partir des rapports partenaires importés dans l’onglet Monétisation. platform (optionnel, défaut "all") filtre sur une seule plateforme parmi celles réellement importées pour cette chaîne (voir data.platforms) ; omis ou "all", les plateformes sont sommées ensemble. data.stats vaut null si aucune donnée n’a encore été importée pour cette chaîne/plateforme — jamais une erreur. currency est le code tel qu’importé (ex. "EUR"), pas un symbole d’affichage ; currency_mixed signale que plusieurs devises coexistent dans les lignes sommées. Pour une chaîne avec un accès Broadpeak SSAI configuré (voir get_channel_ssai_heatmap), data.ssai_totals ajoute les vraies insertions/impressions publicitaires réellement comptées par Broadpeak sur EXACTEMENT la même période que data.stats.period — permet un vrai rapprochement revenu ÷ activité réelle, sommé sur toutes les plateformes de distribution Broadpeak configurées (Rakuten TV, Xiaomi TV+, TCL, Plex... — à ne pas confondre avec le paramètre platform ci-dessus, qui filtre les RAPPORTS DE REVENU importés, un axe totalement différent) ; data.ssai_by_platform détaille ce même total plateforme par plateforme (platform, service_id, warning, totals). meta.ssai_configured distingue les trois états réels : chaîne sans accès Broadpeak (false, data.ssai_totals null, jamais une erreur), chaîne configurée mais sans période à comparer faute de revenu importé (true, data.ssai_totals null, meta.ssai_warning null), et chaîne configurée avec un vrai résultat ou une vraie erreur Broadpeak (true, meta.ssai_warning expliquant le cas échéant pourquoi data.ssai_totals est resté null).
| Paramètre | Type | Requis | Note |
|---|---|---|---|
channel_id | string | non | channel_id ou channel_uuid requis (l’un des deux) |
channel_uuid | string | non | identifiant canonique de la chaîne, persistance garantie contrairement à channel_id — préférable pour un stockage long terme côté partenaire |
platform | string | non | une valeur parmi data.platforms (défaut : "all", toutes plateformes sommées ensemble) |
Exemple de réponse
{
"data": {
"channel_id": "raw_provider_id_123",
"stats": {
"period": {
"start": "2026-08-01",
"end": "2026-08-31",
"days": 31
},
"totals": {
"plays": 12000,
"impressions": 48000,
"gross_revenue": 210.5,
"operating_cost": 15,
"net_revenue": 195.5
},
"rpm_net": 4.07,
"currency": "EUR",
"currency_mixed": false,
"daily_series": [
{
"date": "2026-08-01",
"plays": 400,
"impressions": 1600,
"gross_revenue": 7,
"net_revenue": 6.5
}
],
"by_device": [
{
"device_type": "CTV",
"plays": 9000,
"impressions": 36000,
"net_revenue": 150,
"share_pct": 76.7
}
]
},
"platforms": [
"rakuten"
],
"platform_labels": {
"rakuten": "Rakuten",
"pluto_tv": "Pluto TV",
"samsung_tv_plus": "Samsung TV Plus",
"xiaomi": "Xiaomi",
"tcl": "TCL",
"other": "Autre"
},
"ssai_totals": {
"insertions": 2954,
"impressions": 2830
},
"ssai_by_platform": [
{
"platform": "Rakuten TV",
"service_id": 75008,
"warning": null,
"totals": {
"insertions": 1600,
"impressions": 1530
}
},
{
"platform": "Xiaomi TV+",
"service_id": 75012,
"warning": null,
"totals": {
"insertions": 1354,
"impressions": 1300
}
}
]
},
"meta": {
"platform": "all",
"ssai_configured": true,
"ssai_warning": null
}
}
GET /channels/ssai-heatmap
Grille hebdomadaire d’insertions/impressions publicitaires réelles, jour par jour et heure par heure (Broadpeak SSAI)
Required scope: monetization:read
Données RÉELLES d’événements publicitaires (insertions et impressions comptées côté SSAI Broadpeak), à distinguer à la fois de get_channel_monetization (revenu quotidien déclaré par un partenaire tel que Rakuten) et de get_channel_ad_load (inventaire structurel/planifié, jamais un événement publicitaire réellement survenu). Seules certaines chaînes ont un accès Broadpeak SSAI configuré — sans cela, data.heatmap vaut null et meta.ssai_configured vaut false, ce qui n’est jamais une erreur : la plupart des chaînes n’ont simplement pas cet accès. Quand une chaîne EST configurée mais que Broadpeak est injoignable, data.heatmap reste null mais meta.ssai_configured vaut true, avec meta.ssai_warning expliquant pourquoi. Chaque cellule de la grille peut valoir null (aucune donnée Broadpeak pour cette heure précise, le plus souvent une semaine pas encore entièrement passée) — à distinguer d’un vrai 0 (Broadpeak a bien compté zéro événement publicitaire cette heure-là). Une chaîne peut être distribuée sur plusieurs plateformes (Rakuten TV, Xiaomi TV+, TCL, Plex...), chacune avec son propre serviceId Broadpeak — data.platforms liste toujours les plateformes réellement configurées pour cette chaîne ; platform (paramètre, optionnel, défaut "all") combine leur activité réelle en une seule grille, ou en cible une seule (valeur exacte tirée de data.platforms) pour l’inspecter isolément — data.platform indique laquelle cette réponse représente.
| Paramètre | Type | Requis | Note |
|---|---|---|---|
channel_id | string | non | channel_id ou channel_uuid requis (l’un des deux) |
channel_uuid | string | non | identifiant canonique de la chaîne, persistance garantie contrairement à channel_id — préférable pour un stockage long terme côté partenaire |
week_start | string | oui | |
platform | string | non | une valeur parmi data.platforms (défaut : "all", toutes les plateformes Broadpeak configurées combinées) |
Exemple de réponse
{
"data": {
"channel_id": "raw_provider_id_123",
"heatmap": {
"days": [
"Lun 24 août",
"…"
],
"insertions": [],
"impressions": []
},
"range": {
"since": "2026-08-24T00:00:00.000Z",
"until": "2026-08-31T00:00:00.000Z"
},
"platforms": [
"Rakuten TV",
"Xiaomi TV+"
],
"platform": "all"
},
"meta": {
"ssai_configured": true,
"ssai_warning": null
}
}
GET /channels/context
Snapshot complet programmes + coupures + tags IAB, pour préchargement par un décision process externe
Required scope: channels:read
Conçu pour le préchargement — jamais appelé pendant une requête VAST en direct. Retourne un instantané COMPLET, non paginé et autoritatif de [since, until[ : tout programme ou coupure connu qui chevauche la fenêtre est inclus (un programme commencé avant since mais qui se termine après since est inclus). Plage maximale : 7 jours. Une correction ou dépublication de grille est observable dès le prochain appel — un programme qui n\u2019a pas été reconfirmé par la vérification la plus récente de la chaîne n\u2019est plus jamais retourné, quelle que soit la fenêtre demandée. program_id et break_id sont des identifiants publics stables (voir program_id : assignation interne UUID + correspondance titre/horaire tant qu\u2019aucun fournisseur EPG n\u2019expose son propre identifiant persistant ; break_id : identifiant interne stable, ou l\u2019identifiant persistant OKAST lui-même dès qu\u2019il sera disponible dans les exports réels). Les tags IAB (taxonomie IAB Content 3.1) sont une classification publicitaire structurée, distincte des catégories éditoriales. keywords (Ad Server, 2026-09-08) : termes éditoriaux extraits du titre/sous-titre/description de CE programme — jamais mappés vers IAB ici, ce mapping reste entièrement du côté Ad Server, à partir de son propre dictionnaire keyword → IAB Content 3.1 ; les tags IAB natifs (champ iab), quand ils existent, restent prioritaires. series_id (optionnel) : identifiant stable de série/émission récurrente quand la source en fournit un ; null pour la grande majorité des flux aujourd\u2019hui — jamais dérivé du titre. Supporte ETag/If-None-Match (304 si la fenêtre n\u2019a pas changé) — keywords et series_id sont inclus dans ce calcul, un changement de l\u2019un ou l\u2019autre invalide le cache.
| Paramètre | Type | Requis | Note |
|---|---|---|---|
channel_id | string | non | channel_id ou channel_uuid requis (l’un des deux) |
channel_uuid | string | non | identifiant canonique de la chaîne, persistance garantie contrairement à channel_id — préférable pour un stockage long terme côté partenaire |
since | string | oui | |
until | string | oui |
Exemple de réponse
{
"data": {
"channel_id": "raw_provider_id_123",
"programs": [
{
"program_id": "3f1a2b4c-5d6e-7f89-a0b1-c2d3e4f56789",
"series_id": null,
"start": "2026-08-25T18:00:00.000Z",
"end": "2026-08-25T19:00:00.000Z",
"title": "Example Show",
"subtitle": null,
"description": "An optional editorial synopsis.",
"categories": [
"Documentaire"
],
"image_url": "https://example.test/programme.jpg",
"iab": {
"taxonomy": "IAB_CONTENT",
"version": "3.1",
"cattax": 9,
"tags": [
{
"term_id": "653",
"label": "Travel",
"source": "epg_doctor_manual",
"confidence": null
}
]
},
"keywords": [
"synopsis",
"editorial",
"documentaire"
],
"updated_at": "2026-08-25T10:12:30.000Z"
}
],
"ad_breaks": [
{
"break_id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"program_id": "3f1a2b4c-5d6e-7f89-a0b1-c2d3e4f56789",
"start": "2026-08-25T18:22:00.000Z",
"end": "2026-08-25T18:24:00.000Z",
"duration_seconds": 120,
"position": "unknown",
"updated_at": "2026-08-25T10:12:30.000Z"
}
]
},
"meta": {
"since": "2026-08-25T00:00:00.000Z",
"until": "2026-09-01T00:00:00.000Z",
"generated_at": "2026-08-25T10:15:00.000Z",
"source_updated_at": "2026-08-25T10:12:30.000Z",
"coverage_until": "2026-09-06T18:00:00.000Z",
"program_count": 1,
"ad_break_count": 1
}
}