API REST : brancher un agent sur vos enregistrements

Une clé d'API Revoir ouvre une API HTTP sous https://api.revoir.agenceelan.ca/api/v1. Elle donne accès en lecture aux enregistrements de son propriétaire : les lister, chercher un passage, récupérer le document extrait. Elle permet aussi d'envoyer un enregistrement et de s'abonner à des webhooks.

Toutes les réponses sont en JSON, sauf les exports de document qui renvoient le format demandé. Le succès a la forme { "data": ... }, parfois accompagnée d'un bloc meta. L'erreur a toujours la forme { "error": { "code", "message" } }.

1. S'authentifier

Créez une clé depuis Réglages > Clés d'API. Elle commence par revoir_live_ et n'est affichée qu'une seule fois. Passez-la en en-tête sur chaque appel :

Authorization: Bearer revoir_live_VOTRE_CLE

Il n'y a pas d'autre forme d'authentification sur cette API : ni paramètre de requête, ni cookie de session. Une clé agit toujours pour le compte de l'utilisateur qui l'a créée, et ne voit que les enregistrements de ce compte.

2. Les routes disponibles

Cette liste est exhaustive. Tout chemin qui n'y figure pas répond 404, y compris les routes que l'application web utilise pour elle-même : celles-là demandent une session, pas une clé.

Les chemins sont relatifs à https://api.revoir.agenceelan.ca/api/v1.

3. Lister les enregistrements

curl "https://api.revoir.agenceelan.ca/api/v1/videos?limit=20&status=ready" \
  -H "Authorization: Bearer revoir_live_VOTRE_CLE"

meta.total compte les enregistrements qui passent les filtres, pas le catalogue entier : il sert directement à paginer.

{
  "data": [
    {
      "id": "3f2b1c8e-5d4a-4e91-bb27-9c0f6a1d8e33",
      "title": "Comité de direction du 12 septembre",
      "originalFilename": "comite-2026-09-12.mp4",
      "duration": 4320,
      "sizeBytes": 734003200,
      "status": "ready",
      "folderId": "8a1d2f40-11bc-4e07-9f3a-5b6c7d8e9f01",
      "color": null,
      "pinnedAt": null,
      "detailLevel": "standard",
      "createdAt": "2026-09-12T14:02:11.000Z",
      "extractedAt": "2026-09-12T14:11:48.000Z"
    }
  ],
  "meta": { "total": 137, "limit": 20, "offset": 0 }
}

duration est en secondes et vaut null tant que l'extraction n'a pas tourné. Un enregistrement n'est lisible que lorsque son status vaut ready.

4. Chercher un passage

C'est la route à utiliser quand vous cherchez une information précise dans un historique de réunions. Elle fait une recherche sémantique dans le contenu extrait et renvoie des extraits horodatés, sans vous faire télécharger les documents entiers.

curl "https://api.revoir.agenceelan.ca/api/v1/search?q=budget%20Boréal&limit=5" \
  -H "Authorization: Bearer revoir_live_VOTRE_CLE"

{
  "data": [
    {
      "recordingId": "3f2b1c8e-5d4a-4e91-bb27-9c0f6a1d8e33",
      "title": "Comité de direction du 12 septembre",
      "timestamp": "00:41:12",
      "score": 0.82,
      "excerpt": "On confirme l'enveloppe Boréal pour le trimestre, sous réserve du"
    }
  ],
  "meta": {
    "query": "budget Boréal",
    "limit": 5,
    "recordingId": null,
    "excerptChars": 300
  }
}

Chaque extrait est tronqué à 300 caractères : search sert à repérer un passage, pas à restituer le document. Une fois le recordingId et l'horodatage connus, allez chercher le document complet à la section suivante.

Une limite hors bornes est refusée avec un 400 plutôt que rognée en silence : un agent qui demande 50 résultats et en reçoit 20 sans le savoir conclurait à tort qu'il n'y en a que 20.

5. Récupérer le document extrait

Quatre formats, même contenu. Pour un agent, prenez export.md (du texte structuré, directement utilisable en contexte) ou export.json (des champs à parcourir).

curl "https://api.revoir.agenceelan.ca/api/v1/videos/3f2b1c8e-5d4a-4e91-bb27-9c0f6a1d8e33/export.md" \
  -H "Authorization: Bearer revoir_live_VOTRE_CLE"

La forme du Markdown

C'est exactement ce que l'outil MCP get_recording_document renvoie. Les sections absentes du document sont omises : un enregistrement sans décision n'a pas de section ## Décisions.

# Comité de direction du 12 septembre

**Durée**: 1h 12min | **Langue**: fr

## Résumé

Revue trimestrielle du portefeuille, arbitrage sur l'enveloppe Boréal.

**Sujets clés**: budget, Boréal, embauches

**Participants**:
- **Julie Tremblay** (direction): mène la séance

## Segments

### [00:00 - 08:12] discussion

**Transcript:**
- **Julie Tremblay** [00:00:14]: On commence par le portefeuille.

**Faits clés:**
- Enveloppe Boréal arrêtée à 240 k$

---

## Décisions

- [00:41:12] Financer le pilote Boréal (par Julie Tremblay)

## Actions à faire

- [ ] Préparer le cadrage du pilote

Les actions à faire sortent en cases à cocher, avec l'assigné en gras et l'horodatage entre crochets. Les segments sont séparés par un filet ---.

GET /videos/{id} renvoie, dans son bloc downloads, les quatre chemins d'export pour cet enregistrement, et un bloc extraction qui dit si le document est disponible.

curl "https://api.revoir.agenceelan.ca/api/v1/videos/3f2b1c8e-5d4a-4e91-bb27-9c0f6a1d8e33" \
  -H "Authorization: Bearer revoir_live_VOTRE_CLE"

6. Envoyer un enregistrement

En trois temps. L'extraction ne démarre qu'au troisième appel : tant que vous n'avez pas confirmé, rien n'est traité et rien n'est facturé.

# 1. Demander une URL d'envoi
curl -X POST https://api.revoir.agenceelan.ca/api/v1/videos/upload-url \
  -H "Authorization: Bearer revoir_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"filename":"reunion.mp4","contentType":"video/mp4","sizeBytes":734003200,"participantNoticeAck":true}'
# participantNoticeAck: obligatoire si ton organisation exige l'avis aux participants,
# et seulement après les avoir réellement avisés. Sans lui, réponse 422.

# 2. Envoyer le fichier sur l'URL reçue (uploadUrl), en PUT
curl -X PUT "<uploadUrl>" \
  -H "Content-Type: video/mp4" \
  --upload-file reunion.mp4

# 3. Confirmer: c'est cet appel qui déclenche l'extraction
curl -X POST https://api.revoir.agenceelan.ca/api/v1/videos/<uploadId>/confirm \
  -H "Authorization: Bearer revoir_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"title":"Comité du 12 septembre","detailLevel":"standard"}'

L'URL d'envoi est signée et valable 15 minutes. Les formats acceptés sont video/mp4, video/quicktime, video/x-matroska, video/webm, et les principaux formats audio (audio/mpeg, audio/wav, audio/mp4, audio/aac, audio/ogg, audio/flac).

detailLevel accepte overview, standard (défaut), detailed et exhaustive. Sur le plan Free, un fichier de plus de 5 Go est refusé ; pour alléger un fichier avant envoi, voyez la page sur les gros fichiers.

7. Être prévenu quand un document est prêt

Plutôt que de sonder, abonnez une URL. Les deux événements sont extraction.completed et extraction.failed.

curl -X POST https://api.revoir.agenceelan.ca/api/v1/webhooks \
  -H "Authorization: Bearer revoir_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://votre-agent.exemple/revoir","events":["extraction.completed"]}'

La réponse contient un secret qui commence par whsec_, renvoyé une seule fois : il sert à vérifier la signature des livraisons. La charge utile exacte, la recette de signature et la politique de réessai sont sur la page Webhooks.

8. Les erreurs

Toujours la même enveloppe, quel que soit le chemin qui a échoué. Traitez le code, pas le message : le premier est stable, le second peut être reformulé.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "limit must be between 1 and 20",
    "details": { "field": "limit", "max": 20 }
  }
}

Un 401 porte un en-tête WWW-Authenticate. Un 404 sur un enregistrement qui appartient à quelqu'un d'autre est volontairement indiscernable d'un identifiant inexistant : l'API ne confirme jamais l'existence d'un enregistrement que la clé ne peut pas lire.

9. Limites de débit

Comptées par utilisateur et par heure glissante, selon le plan. Toutes les clés d'un même compte partagent le même compteur, et le serveur MCP le partage aussi.

Chaque réponse authentifiée porte l'état du compteur :

RateLimit-Limit: 100
RateLimit-Remaining: 97
RateLimit-Reset: 1789012800
RateLimit-Policy: 100;w=3600

RateLimit-Reset est un horodatage Unix en secondes. Au-delà du plafond, les appels répondent 429 avec details.retryAt jusqu'à la fin de la fenêtre.

10. La spec OpenAPI

La spec complète est publique et ne demande aucune clé. Beaucoup d'agents et d'outils sans code savent la consommer directement pour se configurer seuls.

curl https://api.revoir.agenceelan.ca/api/openapi.json

C'est une spec OpenAPI 3.1. Elle est aussi servie en YAML sur /api/openapi.yaml, et sous sa forme versionnée sur /api/v1/openapi.json. Une interface de navigation est disponible sur api.revoir.agenceelan.ca/api/docs.

11. Ce que cette API ne fait pas

• Aucune suppression ni modification d'enregistrement. Une clé ne peut pas détruire de contenu.
• Aucun accès aux enregistrements d'un autre utilisateur, même au sein d'une même organisation.
• Pas de conversation. Le chat de l'application n'est pas exposé : GET /search rend le contexte, votre agent rédige la réponse.
• Pas de flux temps réel. L'avancement se suit par webhook.
• Pas de gestion des dossiers, des recettes ni des membres : ces écrans restent dans l'application web.