Utiliser l'API REST de Clevera

L'API REST de Clevera permet à vos propres scripts et services d'effectuer les actions qu'un agent peut réaliser via MCP : lire votre bibliothèque, demander des vidéos et des articles, exporter des vidéos, travailler sur des sites de documentation et suivre les tâches. Cet article couvre l'URL de base, l'authentification, le flux de requête pour le travail payant, les erreurs et les limites de débit.

Bases#

Vérifiez un jeton avec GET /docs/me :

curl -H "Authorization: Bearer $CLEVERA_TOKEN" \
     -H "Accept: application/json" \
     https://app.clevera.ai/api/v1/docs/me

La réponse indique qui utilise le jeton : le nom et l'expiration du jeton, la personne et son rôle actuel, l'espace de travail, les sites concernés et les autorisations actives (les autorisations du jeton réduites au rôle actuel de la personne). Appelez-le en premier lorsqu'un appel est refusé.

Points de terminaison#

Chaque point de terminaison nécessite l'autorisation indiquée. Appeler l'un d'eux sans autorisation renvoie 403 forbidden_ability. Voir Autorisations de l'agent.

Bibliothèque et matériaux#

Vidéos et articles#

Tâches et crédits#

Sites de documentation#

Plus d'informations sur les agents et les sites de documentation : Connecter des agents IA à vos sites de documentation.

Demander un travail payant#

Le travail qui coûte des crédits nécessite toujours un devis d'abord, puis un démarrage :

1. Faire un devis. POST /videos/quotes (ou /clips/quotes) avec ce que vous voulez. La réponse contient un quote_id et la fourchette de crédits. Un devis est valide pendant 15 minutes et peut être utilisé une fois.
2. Optionnellement, faire un test (dry-run). Envoyez le démarrage avec "dry_run": true pour savoir s'il démarrerait, nécessiterait une approbation ou serait bloqué. Rien n'est écrit.
3. Démarrer. POST /videos avec quote_id et un en-tête Idempotency-Key. La réponse est 202 avec une tâche.
4. Suivre. GET /jobs/{job}/wait jusqu'à ce que le status de la tâche change, ou écoutez les webhooks.

curl -X POST https://app.clevera.ai/api/v1/videos/quotes \
  -H "Authorization: Bearer $CLEVERA_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "how_to", "recording_id": "<recording id>", "language": "en-US"}'

curl -X POST https://app.clevera.ai/api/v1/videos \
  -H "Authorization: Bearer $CLEVERA_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6c1a2e-8d4b-4f7a-9c1e-2b5d7e9f0a13" \
  -d '{"quote_id": "<quote id>"}'

Statuts des tâches :

Le fait qu'un démarrage s'exécute immédiatement ou attende une personne dépend des plafonds de dépenses du jeton et de son paramètre Approuver automatiquement ci-dessous. Voir Contrôler les dépenses et les approbations des agents.

Tentatives et idempotence#

Envoyez un en-tête Idempotency-Key (un UUID unique par action) à chaque création et démarrage. Si le réseau tombe et que vous réessayez avec la même clé et le même corps, vous recevrez la première réponse au lieu d'une deuxième vidéo. Les clés sont conservées pendant 24 heures.

Erreurs#

Chaque erreur a la même forme, avec un message indiquant quoi faire ensuite :

{
  "error": {
    "code": "forbidden_ability",
    "message": "This token lacks the videos:create ability. Ask the workspace member who owns it for a token that has it.",
    "details": { "ability": "videos:create" }
  },
  "request_id": "req_example"
}

Incluez le request_id lorsque vous contactez le support.

Chaque message, avec sa solution : Corriger les erreurs d'agent et d'API.

Limites de débit#

Une réponse 429 contient un en-tête Retry-After et retry_after (secondes) dans le corps. Attendez ce délai avant de réessayer. Les lectures, devis et vérifications de statut ne coûtent aucun crédit.

Connexe#