Veille & Alertes — Lecture + actions

Le module Veille capture des documents (web, news, RSS) sur des thématiques configurées, les score (relevance + freshness), et permet de générer des synthèses IA.

Source : server/publicApi/routes/watches.ts.

⚠️ L'API publique ne permet pas de créer/modifier/supprimer une veille — uniquement lire et déclencher des runs/synthèses. La gestion des veilles passe par l'UI (création des sources, mots-clés, fréquence).

Vue d'ensemble

Méthode	Path	Scope	Description
GET	/watches	watches:read	Liste paginée des veilles
GET	/watches/:id	watches:read	Détail d'une veille
GET	/watches/:id/feed	watches:read	Documents collectés (paginés, scorés)
GET	/watches/:id/syntheses	watches:read	20 dernières synthèses générées
POST	/watches/:id/run	watches:write	Lance un run immédiat (async)
POST	/watches/:id/syntheses	watches:write	Génère une synthèse IA (async)

Pas de webhooks publics actuellement émis pour ce module.

---

GET /watches

Liste paginée des veilles de l'agence (triées par updatedAt DESC).

{
  "data": [
    { "id": 1, "agencyId": 7, "name": "Veille concurrence", "status": "active", "updatedAt": "2026-04-27T08:00:00.000Z" }
  ],
  "total": 4,
  "limit": 50,
  "offset": 0
}

---

GET /watches/:id

Détail d'une veille.

{ "data": { "id": 1, "name": "Veille concurrence", "status": "active", ... } }

⚠️ Réponse enveloppée dans { data: ... } (différent des autres endpoints). Pourrait être harmonisé en v2.

---

GET /watches/:id/feed

Documents collectés par la veille.

Query params

Param	Type	Description
limit	int	Défaut 50, max 100
offset	int	Offset
sort	score | date	Tri (défaut score — par compositeScore desc)

Réponse 200

{
  "data": [
    {
      "id": 101,
      "title": "Article concurrent X annonce…",
      "url": "https://example.com/news",
      "snippet": "…extrait…",
      "author": "Jane Doe",
      "publishedAt": "2026-04-26T18:00:00.000Z",
      "sourceType": "rss",
      "sourceDomain": "example.com",
      "language": "fr",
      "relevanceScore": 0.92,
      "freshnessScore": 0.85,
      "compositeScore": 0.89,
      "isRead": false,
      "isStarred": false
    }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0
}

Les documents archivés (isArchived = true) sont automatiquement exclus.

---

GET /watches/:id/syntheses

Liste des 20 dernières synthèses IA générées (pas de pagination — historique limité).

{
  "data": [
    {
      "id": 12,
      "watchId": 1,
      "status": "completed",
      "summary": "…texte de synthèse…",
      "periodDays": 7,
      "documentsAnalyzed": 47,
      "createdAt": "2026-04-27T08:00:00.000Z"
    }
  ],
  "total": 12
}

---

POST /watches/:id/run

Déclenche un run de collecte immédiat (async). La veille doit être status = "active" (sinon 409).

Réponse 202

{ "message": "Run lancé", "watchId": 1 }

L'exécution est asynchrone — vous pouvez poller /watches/:id/feed ensuite pour voir les nouveaux documents.

Erreurs

• 409 : la veille n'est pas active

---

POST /watches/:id/syntheses

Lance la génération d'une synthèse IA (async, async, OpenAI/Anthropic backend).

Body (optionnel)

{
  "periodDays": 7,
  "maxDocuments": 50
}

Champ	Type	Défaut	Bornes
periodDays	int	7	1 - 90
maxDocuments	int	50	5 - 100

Réponse 202

{ "message": "Génération lancée", "synthesisId": 12 }

Anti-spam

Si une synthèse est déjà status = "generating" pour cette veille, retourne 429 :

{ "error": "Une synthèse est déjà en cours de génération", "synthesisId": 11 }

Exemple — déclencher une synthèse 30 jours, max 100 docs

curl -X POST \
  -H "x-api-key: spk_..." \
  -H "Content-Type: application/json" \
  -d '{"periodDays":30,"maxDocuments":100}' \
  https://beta.stormeo.io/api/public/v1/watches/1/syntheses

Récupération du résultat ensuite via :

curl -H "x-api-key: spk_..." \
  https://beta.stormeo.io/api/public/v1/watches/1/syntheses