Points de terminaison Operations API

Référence complète des points de terminaison REST API des notifications, du merging, des analytics, de la corbeille, des sprint chains, des tâches récurrentes, des branches, des pull requests et de l’inbox dans CodeCourier.

14 min lire
apinotificationsmerging

L’Operations API couvre des préoccupations transverses : notifications, merge de PR, analytics d’usage, gestion de la corbeille, sprint chains, tâches récurrentes, gestion de branches GitHub, opérations de pull request, et gestion de l’inbox. Ces 28 points de terminaison vous aident à surveiller l’activité, fusionner du travail terminé, suivre les coûts, planifier de l’automatisation récurrente, et gérer les ressources supprimées.

Notifications

GET /api/v1/notifications/list

Liste les notifications de l’utilisateur et du projet actuels.

Paramètres de query :

  • filter (optionnel) - Type de filtre (p. ex., unread, all)
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/notifications/list?filter=unread"

Types de notifications inclus : run_completed, run_failed, pr_created, pr_merged, pr_failed, member_joined, workflow_completed, sprint_completed, sprint_failed.

GET /api/v1/notifications/unread-count

Récupère le nombre de notifications non lues.

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/notifications/unread-count

Réponse :

{ "data": { "count": 5 } }

POST /api/v1/notifications/mark-read

Marque une seule notification comme lue.

{ "notificationId": "..." }

POST /api/v1/notifications/mark-all-read

Marque toutes les notifications du projet comme lues. Aucun body requis.

POST /api/v1/notifications/dismiss

Rejette une notification (la masque de la liste).

{ "notificationId": "..." }

Points de terminaison REST Inbox / Notification

En plus des points de terminaison legacy /notifications/* ci-dessus, l’API expose une interface d’inbox RESTful sous /api/v1/notifications utilisant les verbes HTTP standards :

GET /api/v1/notifications

Liste toutes les notifications du projet via l’URL de style REST.

Paramètres de query :

  • filter (optionnel) - unread ou all (par défaut : all)
  • limit (optionnel) - Résultats max (par défaut : 50)
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/notifications?filter=unread&limit=20"

PUT /api/v1/notifications/:id/read

Marque une notification spécifique comme lue.

curl -X PUT -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/notifications/notif_.../read

PUT /api/v1/notifications/read-all

Marque toutes les notifications du projet comme lues. Aucun body requis.

curl -X PUT -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/notifications/read-all

DELETE /api/v1/notifications/:id

Rejette et retire une notification spécifique.

curl -X DELETE -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/notifications/notif_...

Merging

GET /api/v1/merging/list

Liste tous les runs d’agent de merge du projet.

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

POST /api/v1/merging/start

Démarre un agent de merge qui combine plusieurs pull requests en une seule. L’agent de merge provisionne une sandbox, récupère toutes les PR, résout les conflits, et crée une PR unifiée.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "pullRequests": [
      {"prUrl": "https://github.com/org/repo/pull/1", "prNumber": 1},
      {"prUrl": "https://github.com/org/repo/pull/2", "prNumber": 2}
    ],
    "baseBranch": "main",
    "config": {}
  }' \
  https://<deployment>.convex.site/api/v1/merging/start

Requis : pullRequests (tableau non vide d’objets PR).

Optionnel : baseBranch, config.

Réponse (201 Created) :

{ "data": { "id": "...", "status": "running" } }

Analytics

GET /api/v1/analytics/usage

Récupère les enregistrements d’usage (compute, tokens, appels API) avec filtrage par plage de dates et par service.

Paramètres de query :

  • startDate (optionnel) - Chaîne de date ISO (p. ex., 2024-01-01)
  • endDate (optionnel) - Chaîne de date ISO
  • service (optionnel) - Filtrer par service (p. ex., e2b, anthropic, openai)
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/analytics/usage?startDate=2024-01-01&endDate=2024-01-31"

GET /api/v1/analytics/daily-stats

Récupère les statistiques agrégées quotidiennes du projet.

Paramètres de query :

  • startDate (optionnel) - Début de la plage de dates
  • endDate (optionnel) - Fin de la plage de dates

GET /api/v1/analytics/counters

Récupère les compteurs actuels du projet (total des runs, sandboxes actives, issues en attente, etc.).

Gestion de la corbeille

GET /api/v1/trash/list

Liste toutes les ressources supprimées en soft-delete à travers tous les types d’entités (runs, sandboxes, workflows, sessions d’issue, learnings, etc.).

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

POST /api/v1/trash/restore

Restaure une ressource supprimée en soft-delete depuis la corbeille.

{
  "entityType": "run",
  "entityId": "..."
}

Valeurs valides pour entityType : run, sandbox, workflow, learning, issueSession.

POST /api/v1/trash/permanent-delete

Supprime définitivement une ressource depuis la corbeille. Irréversible.

{
  "entityType": "run",
  "entityId": "..."
}

GET /api/v1/trash

Point de terminaison de style REST pour lister les items supprimés en soft-delete. Renvoie les mêmes données que GET /api/v1/trash/list. Supporte un paramètre de query type optionnel pour filtrer par type d’entité.

curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/trash?type=run"

POST /api/v1/trash/:type/:id/restore

Restauration de style REST. :type est le type d’entité (p. ex., run) et :id est l’ID de l’entité.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/trash/run/r_.../restore

DELETE /api/v1/trash/:type/:id

Suppression définitive de style REST. Retire irréversiblement l’entité du système.

curl -X DELETE -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/trash/run/r_...

Sprint Chains

Les sprint chains orchestrent du travail IA multi-sprint, en exécutant une série de runs séquentiels à travers des sprints numérotés. Une sprint chain peut être mise en pause, reprise depuis un index de sprint spécifique, et suit les URL de PR générées par sprint.

Objet Sprint Chain

{
  "id": "sc_...",
  "status": "running",
  "sprintRange": [1, 5],
  "currentSprintIndex": 2,
  "resumeFromSprint": null,
  "sprintPrUrls": [
    "https://github.com/org/repo/pull/10",
    "https://github.com/org/repo/pull/11"
  ],
  "workflowId": "wf_...",
  "createdAt": "2024-01-15T10:00:00Z"
}

Valeurs de statut de sprint chain : pending, running, completed, failed, cancelled.

  • sprintRange ([start, end]) - Les premiers et derniers numéros de sprint dans la chain
  • currentSprintIndex (number) - Index zéro-indexé du sprint en cours d’exécution
  • resumeFromSprint (number | null) - Si défini, la chain redémarrera depuis cet index de sprint à la prochaine tentative de run
  • sprintPrUrls (string[]) - Liste ordonnée des URL de PR générées par chaque sprint terminé
  • workflowId (string) - Le blueprint de workflow utilisé pour chaque exécution de sprint

GET /api/v1/sprint-chains

Liste toutes les sprint chains du projet.

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

GET /api/v1/sprint-chains/:id

Récupère une seule sprint chain par ID, y compris toutes les métadonnées de sprint et les URL de PR.

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/sprint-chains/sc_...

POST /api/v1/sprint-chains

Crée et démarre une nouvelle sprint chain.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "wf_...",
    "sprintRange": [1, 5],
    "prompt": "Migrate all REST API handlers to use the new validation layer",
    "githubRepoUrl": "https://github.com/org/repo",
    "branchName": "feature/validation-migration"
  }' \
  https://<deployment>.convex.site/api/v1/sprint-chains

Champs du body :

  • workflowId (string, requis) - Blueprint de workflow à exécuter pour chaque sprint
  • sprintRange ([number, number], requis) - Numéros de sprint de début et de fin (inclus)
  • prompt (string, requis) - Description de tâche maîtresse partagée entre tous les sprints
  • githubRepoUrl (string, requis) - URL du repository cible
  • branchName (string, optionnel) - Branche de base à partir de laquelle travailler
  • resumeFromSprint (number, optionnel) - Démarrer l’exécution depuis un index de sprint spécifique (pour reprendre des chains interrompues)

Réponse (201 Created) :

{ "data": { "id": "sc_...", "status": "running" } }

DELETE /api/v1/sprint-chains/:id

Annule et supprime une sprint chain. Si la chain est en cours d’exécution, le sprint actif est autorisé à terminer avant que la chain soit marquée comme annulée.

curl -X DELETE -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/sprint-chains/sc_...

Tâches récurrentes

Les tâches récurrentes vous permettent de planifier un prompt de workflow pour s’exécuter automatiquement à une cadence fixe - quotidienne, hebdomadaire, mensuelle, et plus. Chaque déclenchement crée un nouveau run avec les champs scheduledFor et recurrencePattern renseignés.

Objet Recurring Task

{
  "id": "rt_...",
  "title": "Daily dependency audit",
  "description": "Check for outdated or vulnerable npm packages",
  "prompt": "Run npm audit and npm outdated. Create issues for any critical vulnerabilities found.",
  "frequency": "daily",
  "targetWorkflowId": "wf_...",
  "isActive": true,
  "timezone": "America/Chicago",
  "scheduledHour": 8,
  "scheduledMinute": 0,
  "nextRunAt": "2024-01-16T14:00:00Z"
}

Valeurs de fréquence : daily, every_other_day, weekly, biweekly, monthly.

  • timezone (chaîne fuseau horaire IANA) - Fuseau horaire pour interpréter scheduledHour et scheduledMinute
  • scheduledHour (0-23) - Heure du jour dans le fuseau horaire spécifié à laquelle la tâche se déclenche
  • scheduledMinute (0-59) - Minute dans l’heure à laquelle la tâche se déclenche
  • nextRunAt (timestamp ISO) - Date/heure UTC de la prochaine exécution planifiée
  • isActive (boolean) - Si la tâche est actuellement activée ; les tâches inactives ne sont pas exécutées

GET /api/v1/recurring-tasks

Liste toutes les tâches récurrentes du projet.

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

GET /api/v1/recurring-tasks/:id

Récupère une seule tâche récurrente par ID.

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/recurring-tasks/rt_...

POST /api/v1/recurring-tasks

Crée une nouvelle tâche récurrente.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Weekly bundle size check",
    "description": "Ensure the production bundle stays under 200KB",
    "prompt": "Run the build and measure bundle size. If total JS exceeds 200KB, open an issue listing the top 5 contributors by size.",
    "frequency": "weekly",
    "targetWorkflowId": "wf_...",
    "timezone": "UTC",
    "scheduledHour": 6,
    "scheduledMinute": 0
  }' \
  https://<deployment>.convex.site/api/v1/recurring-tasks

Champs du body :

  • title (string, requis) - Nom de tâche lisible
  • prompt (string, requis) - Le prompt de tâche envoyé à l’agent IA à chaque exécution
  • frequency (string, requis) - Fréquence de récurrence : daily, every_other_day, weekly, biweekly, ou monthly
  • targetWorkflowId (string, requis) - Blueprint de workflow à utiliser pour chaque run
  • timezone (string, requis) - Chaîne de fuseau horaire IANA (p. ex., America/New_York, UTC)
  • scheduledHour (number, requis) - Heure de déclenchement (0-23, dans le fuseau horaire spécifié)
  • scheduledMinute (number, requis) - Minute de déclenchement (0-59)
  • description (string, optionnel) - Description étendue à des fins de documentation

Réponse (201 Created) :

{ "data": { "id": "rt_...", "isActive": true, "nextRunAt": "2024-01-16T06:00:00Z" } }

PUT /api/v1/recurring-tasks/:id

Met à jour une tâche récurrente. Tous les champs sont optionnels ; seuls les champs fournis sont modifiés. Mettre à jour des champs liés à la planification (frequency, scheduledHour, scheduledMinute, timezone) recalcule automatiquement nextRunAt.

curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "frequency": "biweekly",
    "scheduledHour": 9,
    "timezone": "Europe/London"
  }' \
  https://<deployment>.convex.site/api/v1/recurring-tasks/rt_...

DELETE /api/v1/recurring-tasks/:id

Supprime définitivement une tâche récurrente. Les runs actifs déjà en cours ne sont pas affectés.

curl -X DELETE -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/recurring-tasks/rt_...

PUT /api/v1/recurring-tasks/:id/toggle

Active ou désactive une tâche récurrente. Une tâche inactive est préservée mais ne se déclenchera pas selon sa planification. Utilisez ceci pour mettre en pause temporairement l’automatisation sans supprimer la configuration.

# Deactivate
curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "isActive": false }' \
  https://<deployment>.convex.site/api/v1/recurring-tasks/rt_.../toggle

# Reactivate
curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "isActive": true }' \
  https://<deployment>.convex.site/api/v1/recurring-tasks/rt_.../toggle

Champs du body :

  • isActive (boolean, requis) - true pour activer, false pour désactiver

Informations

Quand vous réactivez une tâche, nextRunAt est recalculé à partir de l’heure actuelle en utilisant la fréquence et la planification de la tâche. La tâche ne se déclenchera pas rétroactivement pour les exécutions manquées pendant qu’elle était inactive.

Branches

La Branches API expose les branches GitHub du repository configuré du projet, vous permettant d’inspecter et de nettoyer les branches de fonctionnalité créées par des runs IA.

GET /api/v1/branches

Liste les branches GitHub du repository du projet. Renvoie les métadonnées de branche incluant le SHA du dernier commit, l’auteur, et l’horodatage.

curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/branches"
# → {
#     "data": [
#       {
#         "name": "feature/dark-mode",
#         "sha": "abc123...",
#         "author": "codecourier[bot]",
#         "committedAt": "2024-01-15T10:30:00Z",
#         "isProtected": false
#       }
#     ]
#   }

Paramètres de query :

  • prefix (optionnel) - Filtrer les branches par préfixe de nom (p. ex., feature/)
  • limit (optionnel) - Résultats max (par défaut : 100)

Avertissement

Ce point de terminaison appelle l’API GitHub à chaque requête. Si le projet n’a pas configuré de clé de provider GitHub, il renvoie une erreur 400. Évitez le polling à haute fréquence ; mettez en cache les listes de branches côté client et rafraîchissez à la demande.

DELETE /api/v1/branches/:name

Supprime une branche GitHub par nom. Le nom de branche doit être encodé en URL s’il contient des slashes (p. ex., feature%2Fdark-mode). Les branches protégées et la branche par défaut ne peuvent pas être supprimées via ce point de terminaison.

curl -X DELETE -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/branches/feature%2Fdark-mode"

Pull Requests

La Pull Requests API vous permet de lister les PR ouvertes à travers les runs et de déclencher des opérations de merge automatisées.

GET /api/v1/pull-requests

Liste les pull requests du projet, y compris leur statut de check CI. Les résultats proviennent des enregistrements de runs de CodeCourier plutôt que du polling direct de GitHub, donc ils reflètent les PR créées par des runs IA au sein de la plateforme.

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

Paramètres de query :

  • status (optionnel) - Filtrer par statut de PR : creating, created, failed, skipped, merged, blocked_on_ci
  • runId (optionnel) - Récupérer la PR d’un run spécifique

Réponse :

{
  "data": [
    {
      "runId": "r_...",
      "runName": "Add dark mode toggle",
      "prUrl": "https://github.com/org/repo/pull/42",
      "prNumber": 42,
      "prStatus": "blocked_on_ci",
      "ciChecks": {
        "status": "failed",
        "checkedAt": "2024-01-15T10:30:00Z",
        "checks": [
          { "name": "test", "status": "failure", "conclusion": "failure" }
        ]
      }
    }
  ]
}

POST /api/v1/pull-requests/:id/merge

Déclenche l’agent de merge pour une pull request spécifique. Le paramètre :id est l’ID du run associé à la PR, pas le numéro de PR. L’agent de merge provisionne une sandbox, vérifie le statut CI, et effectue le merge.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/pull-requests/r_.../merge

Champs du body optionnels :

  • mergeStrategy (string) - Stratégie de merge : merge, squash, ou rebase (par défaut : squash)
  • skipCiCheck (boolean) - Forcer le merge même si CI n’a pas réussi (à utiliser avec précaution)

Réponse (201 Created) :

{ "data": { "mergeJobId": "...", "status": "running" } }

Avertissement

Définir skipCiCheck: true contourne l’application du gate CI. Utilisez ceci uniquement si vous êtes certain que l’échec est un test instable ou sans rapport avec les changements de la PR.