Aperçu de l'API

L’API REST CodeCourier fournit un accès programmatique complet à chaque fonctionnalité disponible dans le dashboard web. Avec 171 endpoints répartis sur 26 catégories de ressources, un LLM ou un script d’automatisation peut faire tout ce qu’un humain peut faire - créer des projets, configurer des workflows, lancer des runs de codage IA, gérer des learnings, configurer des contextes et des assets, planifier des tâches récurrentes et plus encore. Tous les endpoints sont authentifiés via des clés API à scope de projet et renvoient des réponses JSON cohérentes.

URL de base

Tous les endpoints de l’API REST sont servis depuis l’URL des HTTP Actions de votre déploiement Convex, sous le préfixe /api/v1/ :

https://<your-deployment>.convex.site/api/v1/

Important : L’URL de base se termine par .convex.site - PAS .convex.cloud. Le domaine .convex.cloud est l’URL WebSocket de données Convex utilisée en interne. Le domaine .convex.site est l’endpoint HTTP Actions qui sert l’API REST. Utiliser le mauvais domaine entraînera des échecs de connexion.

Vous pouvez trouver le nom de votre déploiement dans le dashboard Convex. Il ressemble généralement à happy-animal-123, ce qui vous donne une URL de base de : https://happy-animal-123.convex.site/api/v1/

Authentification

Chaque requête nécessite une clé API de projet passée en tant que bearer token dans le header Authorization. Les clés sont générées via le dashboard ou via l’API elle-même. Voir la page Authentification pour tous les détails sur la création et la gestion des clés.

curl -H "Authorization: Bearer cc_live_..." \
  https://<your-deployment>.convex.site/api/v1/project

Important : Le header est Authorization: Bearer <key> - PAS x-api-key, PAS X-API-Key. Les clés API commencent par cc_live_ (production) ou cc_test_ (environnements de test).

Format de réponse

Toutes les réponses réussies renvoient :

{ "data": <result> }

Toutes les réponses d’erreur renvoient :

{ "error": "Human-readable error message" }

Codes de statut HTTP standard :

• 200 - Succès
• 201 - Créé (pour les endpoints d’action comme start)
• 400 - Requête invalide (champs manquants, JSON invalide)
• 403 - Interdit (clé API invalide ou révoquée)
• 404 - Ressource non trouvée
• 500 - Erreur interne du serveur

IDs de ressource : id vs _id

Chaque ressource renvoyée par l’API REST expose son identifiant canonique sous deux noms de champ : id (convention REST) et _id (alias interne Convex, conservé pour la compatibilité ascendante). Les deux contiennent la même chaîne opaque et peuvent être passés indifféremment à tout endpoint qui accepte un ID.

{
  "data": {
    "id":  "k57a8...",   // ← preferred in new code
    "_id": "k57a8...",   // ← retained for back-compat through 2026-10-24
    "name": "..."
  }
}

Les nouvelles intégrations devraient lire id. Le champ _id est conservé sur chaque projection jusqu’au sunset de l’enveloppe v1 le 2026-10-24 ; après cette date, il pourra être retiré des réponses REST sans autre préavis. Les queries internes Convex ne sont pas affectées - _id reste le nom du champ de document dans la base de données.

Quick Start : démarrer un run et obtenir sa sortie

Voici la séquence minimale dont un agent ou un script a besoin pour démarrer un run et récupérer la sortie complète de la conversation IA :

Étape 1 - Obtenir un workflow ID

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/workflows/list
# → { "data": [{ "id": "jx7...", "_id": "jx7...", "name": "My Workflow", ... }] }

Étape 2 - Démarrer un run

curl -X POST \
  -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "jx7...",
    "prompt": "Add a dark mode toggle to the settings page",
    "githubRepoUrl": "https://github.com/org/repo"
  }' \
  https://<deployment>.convex.site/api/v1/runs/start
# → { "data": { "id": "abc...", "status": "running" } }

Note : githubRepoUrl est requis en pratique. Sans lui, la sandbox n’a aucun code de projet sur lequel travailler et les opérations git échouent immédiatement avec exit status 128.

Étape 3 - Attendre, puis lister les runs pour obtenir le run ID

curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/runs?limit=5"
# → { "data": [{ "id": "r_abc...", "_id": "r_abc...", "status": "completed", ... }] }

Étape 4 - Obtenir les sandbox IDs du run

curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/sandboxes/list?runId=r_abc..."
# → { "data": [{ "id": "s_xyz...", "_id": "s_xyz...", "status": "killed", ... }] }

Étape 5 - Obtenir la sortie complète de la conversation

curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/sandboxes/messages?id=s_xyz..."
# → { "data": [{ "role": "assistant", "content": "...", "timestamp": ... }] }

Pourquoi ne pas utiliser /api/v1/runs/detail ? Cet endpoint renvoie les métadonnées du run et les étapes d’exécution, mais PAS le texte de la conversation IA. La sortie réelle de l’agent réside dans les messages de la sandbox.

Sections de l’API

L’API est organisée en les sections suivantes. Chacune est documentée en détail sur sa propre page :

Gestion des projets - 16 endpoints

Lisez, mettez à jour et supprimez votre projet. Gérez les paramètres du projet (system prompts, env vars, config git), les membres d’équipe (inviter, retirer, mettre à jour les rôles), les clés API des providers (E2B, Anthropic, GitHub, etc.), les clés API de projet (générer, révoquer) et consultez les compteurs du projet.

Workflows - 10 endpoints

Lister, obtenir, créer, mettre à jour, supprimer, restaurer, supprimer définitivement, dupliquer, renommer et supprimer en masse des blueprints de workflow.

Personas - 9 endpoints

Lister, obtenir, voir les analytics, créer, mettre à jour, supprimer, dupliquer, activer/désactiver et supprimer en masse des personas d’agent IA.

Runs - 11 endpoints

Lister, obtenir, obtenir par numéro (recherche par runNumber orienté humain pour le diagnostic), filtrer par workflow ou chain, renommer, supprimer, restaurer, supprimer définitivement, supprimer en masse et démarrer de nouveaux runs de workflow. Inclut des champs pour la planification de runs récurrents (scheduledFor, timezone, recurrencePattern), le statut des checks CI, les détails d’erreur, les scores de qualité, la consommation de tokens et les détails de qualité et de résultats de tests des run steps.

Issues, Sessions, Answering Sessions & Work Chains - 30 endpoints

Opérations CRUD pour les issues (list, get, create, update, delete, link-run, bulk-delete). Gérez les sessions de scan d’issues (list, get, rename, delete, restore, permanent-delete, bulk-delete, start). Answering sessions (list, get, create, update status, delete) et session questions (list, review, update assumption). Plus les work chains (list, get, get issues, create, delete, start).

Sandboxes - 7 endpoints

Lister, obtenir, voir les messages, renommer, supprimer, restaurer et supprimer définitivement des sandboxes.

Learnings & Versions - 19 endpoints

Gestion complète du cycle de vie pour les learnings (list, stats, preview, by-sandbox, create, update-status, update-content, delete, restore, permanent-delete, bulk-update-status, bulk-delete) et les learning versions (list, get, active, compile, activate, deactivate).

Contexts & Assets - 31 endpoints

Gérez les contextes (documents de savoir projet réutilisables avec historique de versions), les skills (comportements d’agent réutilisables multi-fichiers), les commands (commandes IA à fichier unique) et les scripts (scripts d’automatisation exécutables). Chaque type d’asset prend en charge un CRUD complet plus des workflows de publication versionnés.

Opérations - 28 endpoints

Notifications (list, unread-count, mark-read, mark-all-read, dismiss), merging (list, start), analytics (usage, daily-stats, counters), trash (list, restore, permanent-delete), sprint chains (list, get, create, delete), tâches récurrentes (list, get, create, update, delete, toggle), branches GitHub (list, delete), pull requests (list, trigger merge) et endpoints inbox/notification de style REST.

Webhooks & Callbacks

Gestion des webhooks Clerk, endpoint de callback interne Trigger.dev (avec une référence complète des opérations organisée par domaine), vérification de signature et événements de notification.

Endpoints legacy en lecture seule

Les 7 endpoints originaux en lecture seule à /api/v1/projects, /api/v1/workflows, /api/v1/runs, /api/v1/runs/detail et /api/v1/learningsrestent disponibles pour la compatibilité ascendante. Les nouveaux endpoints spécifiques par section (p. ex., /api/v1/runs/list) fournissent les mêmes données plus des opérations d’écriture et davantage d’options de filtrage.

Découverte OpenAPI

La spécification OpenAPI 3.1 complète est servie en direct à GET /api/v1/openapi.json. Cet endpoint ne nécessite aucune authentification et constitue la manière recommandée pour les agents LLM et l’outillage de découvrir chaque endpoint, paramètre et forme de réponse sans avoir à accéder au site de docs.

curl https://<your-deployment>.convex.site/api/v1/openapi.json

CORS

Tous les endpoints /api/v1/* prennent en charge le CORS via un handler global de preflight OPTIONS. Les réponses incluent des headers Access-Control-Allow-Origin: *.

Rate limits

L’API hérite des rate limits de la plateforme Convex. Pour les intégrations à haut débit, implémentez un backoff exponentiel sur les réponses 429. Il n’y a aucun rate limit par clé supplémentaire au-delà de ce que Convex applique.