Points de terminaison Issue, Answering Session & Work Chain API

Référence complète des points de terminaison REST API des issues, sessions de découverte, sessions de clarification, questions de session et work chains - découvrir, clarifier, suivre et résoudre les issues de codebase via l’IA.

15 min lire
apiissuesissue-sessions

Les issues représentent des bugs, améliorations ou tâches découverts dans votre codebase. Les sessions de découverte d’issues sont des runs de scan pilotés par l’IA qui trouvent des issues automatiquement. Les answering sessions permettent à un agent IA de générer et faire réviser des questions de clarification avant d’entreprendre un travail complexe. Les work chains regroupent des issues en séquences d’exécution. Ensemble, ces 30 points de terminaison permettent un workflow complet de découverte-clarification-suivi-résolution.

Points de terminaison Issue

GET /api/v1/issues/list

Liste les issues avec filtrage optionnel.

Paramètres de query :

  • status (optionnel) - Filtrer par statut d’issue
  • sessionId (optionnel) - Filtrer par session d’issue
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/issues/list?status=open"

GET /api/v1/issues/get

Récupère une seule issue par ID.

  • id (requis) - L’ID du document issue

POST /api/v1/issues/create

Crée une nouvelle issue manuellement.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Memory leak in WebSocket handler",
    "description": "Connection handlers not cleaned up on disconnect",
    "priority": "high",
    "suggestedPrompt": "Fix the memory leak in src/ws/handler.ts by cleaning up event listeners on disconnect",
    "sessionId": "..."
  }' \
  https://<deployment>.convex.site/api/v1/issues/create

Champs du body :

  • title (string, requis) - Titre de l’issue
  • description (string, optionnel) - Description détaillée
  • priority (string, optionnel) - Niveau de priorité (p. ex., high, medium, low)
  • suggestedPrompt (string, optionnel) - Prompt IA pour corriger l’issue
  • sessionId (string, optionnel) - Lien vers la session de découverte

POST /api/v1/issues/update

Met à jour une issue existante.

{
  "issueId": "...",
  "title": "Updated title",
  "priority": "critical",
  "suggestedPrompt": "Updated fix instructions"
}

Champs : issueId (requis), plus les champs optionnels title, description, priority, suggestedPrompt.

POST /api/v1/issues/delete

Supprime une issue.

{ "issueId": "..." }

POST /api/v1/issues/link-run

Lie un run de workflow à une issue (marque l’issue comme en cours de traitement).

{ "issueId": "...", "runId": "..." }

POST /api/v1/issues/bulk-delete

Supprime plusieurs issues.

{ "issueIds": ["id1", "id2", "id3"] }

Points de terminaison Issue Session

GET /api/v1/issue-sessions/list

Liste toutes les sessions de scan d’issues du projet.

GET /api/v1/issue-sessions/get

Récupère une seule session d’issue.

  • id (requis) - L’ID du document session

POST /api/v1/issue-sessions/rename

Renomme une session d’issue.

{ "sessionId": "...", "name": "Security Audit Scan" }

POST /api/v1/issue-sessions/delete

Supprime une session d’issue (soft-delete).

{ "sessionId": "..." }

POST /api/v1/issue-sessions/restore

Restaure une session d’issue supprimée en soft-delete.

{ "sessionId": "..." }

POST /api/v1/issue-sessions/permanent-delete

Supprime définitivement une session d’issue.

{ "sessionId": "..." }

POST /api/v1/issue-sessions/bulk-delete

Supprime plusieurs sessions d’issue (soft-delete).

{ "sessionIds": ["id1", "id2"] }

POST /api/v1/issue-sessions/start

Démarre une nouvelle session de scan d’issues pilotée par l’IA. Provisionne une sandbox qui analyse votre codebase et découvre des issues.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Scan for security vulnerabilities and performance issues",
    "templateId": "base",
    "memoryMb": 4096,
    "timeoutMs": 600000
  }' \
  https://<deployment>.convex.site/api/v1/issue-sessions/start

Requis : prompt. Optionnel : templateId, memoryMb, cpuCount, timeoutMs.

Réponse (201 Created) :

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

Answering Sessions

Les answering sessions permettent à un agent IA de générer des questions de clarification avant d’entreprendre un travail complexe. Un humain (ou un système automatisé) révise chaque question, en approuvant l’hypothèse de l’agent ou en fournissant une correction. L’agent poursuit ensuite avec les réponses révisées comme contexte additionnel.

Les answering sessions sont liées à une session d’issue via issueSessionId. Le workflow complet est :

  1. Démarrer une session d’issue (POST /api/v1/issue-sessions/start)
  2. Créer une answering session pour elle (POST /api/v1/answering-sessions)
  3. L’agent renseigne les questions via le callback Trigger.dev
  4. Réviser chaque question via PUT /api/v1/session-questions/:id/review
  5. Mettre à jour le statut de la session à reviewed pour signaler à l’agent de poursuivre

Objet Answering Session

{
  "id": "as_...",
  "issueSessionId": "is_...",
  "projectId": "proj_...",
  "status": "pending",
  "questionCount": 5,
  "reviewedCount": 3,
  "createdAt": "2024-01-15T10:00:00Z",
  "completedAt": null
}

Valeurs de statut de session : pending (créée, en attente de questions), active (questions générées, en attente de révision), reviewed (toutes les questions révisées, l’agent peut poursuivre), completed (agent terminé avec les réponses), archived (soft-delete).

GET /api/v1/answering-sessions

Liste les answering sessions du projet.

Paramètres de query :

  • issueSessionId (optionnel) - Filtrer par session d’issue parente
  • status (optionnel) - Filtrer par statut de session
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/answering-sessions?status=active"

GET /api/v1/answering-sessions/:id

Récupère une seule answering session par ID.

curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/answering-sessions/as_..."

Réponse :

{
  "data": {
    "id": "as_...",
    "issueSessionId": "is_...",
    "status": "active",
    "questionCount": 5,
    "reviewedCount": 0,
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

POST /api/v1/answering-sessions

Crée une nouvelle answering session liée à une session d’issue.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "issueSessionId": "is_..."
  }' \
  https://<deployment>.convex.site/api/v1/answering-sessions

Champs du body :

  • issueSessionId (string, requis) - La session d’issue parente à laquelle cette answering session appartient

Réponse (201 Created) :

{ "data": { "id": "as_...", "status": "pending" } }

PUT /api/v1/answering-sessions/:id/status

Met à jour le statut d’une answering session.

curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "reviewed" }' \
  https://<deployment>.convex.site/api/v1/answering-sessions/as_.../status

Champs du body :

  • status (string, requis) - Nouveau statut : pending, active, reviewed, completed, ou archived

DELETE /api/v1/answering-sessions/:id

Archive (soft-delete) une answering session. La session est déplacée vers la corbeille et peut être restaurée. Utilisez le point de terminaison permanent-delete de la corbeille pour la supprimer totalement.

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

Session Questions

Les session questions sont les items individuels de clarification au sein d’une answering session. L’agent IA génère une hypothèse initiale pour chaque question ; les réviseurs peuvent approuver l’hypothèse ou fournir une correction.

Objet Session Question

{
  "id": "sq_...",
  "answeringSessionId": "as_...",
  "question": "Should the dark mode preference persist across browser sessions?",
  "assumption": "Yes -- use localStorage to persist the preference indefinitely.",
  "correction": null,
  "status": "pending",
  "reviewedAt": null,
  "reviewedBy": null
}

Valeurs de statut de question : pending (en attente de révision), approved (le réviseur a accepté l’hypothèse), declined (le réviseur a fourni une correction).

GET /api/v1/session-questions

Liste les questions d’une answering session donnée.

Paramètres de query :

  • answeringSessionId (requis) - L’answering session dont on liste les questions
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/session-questions?answeringSessionId=as_..."

Réponse :

{
  "data": [
    {
      "id": "sq_...",
      "question": "Should the dark mode preference persist?",
      "assumption": "Yes -- use localStorage.",
      "correction": null,
      "status": "pending"
    }
  ]
}

PUT /api/v1/session-questions/:id/review

Révise une question en approuvant l’hypothèse de l’agent ou en la déclinant avec une correction. Si vous déclinez, fournissez la réponse correcte dans correction.

# Approve the assumption
curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "approved" }' \
  https://<deployment>.convex.site/api/v1/session-questions/sq_.../review

# Decline and provide a correction
curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "declined",
    "correction": "No -- use a server-side cookie tied to the user account instead."
  }' \
  https://<deployment>.convex.site/api/v1/session-questions/sq_.../review

Champs du body :

  • status (string, requis) - Décision de révision : approved ou declined
  • correction (string, requis si status vaut declined) - La réponse ou instruction correcte qui prévaut sur l’hypothèse de l’agent

Avertissement

Si vous déclinez une question sans fournir de correction, le point de terminaison renvoie une erreur 400. La correction est la réponse faisant autorité que l’agent utilisera - une correction vide laisserait l’agent sans indication.

PUT /api/v1/session-questions/:id/assumption

Met à jour l’hypothèse générée par l’IA pour une question sans changer son statut de révision. Utilisez ceci pour pré-remplir ou corriger le texte de l’hypothèse avant l’étape de révision formelle.

curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "assumption": "Use localStorage with a 30-day expiry for guest users and sync to the user account on sign-in."
  }' \
  https://<deployment>.convex.site/api/v1/session-questions/sq_.../assumption

Champs du body :

  • assumption (string, requis) - Le texte de l’hypothèse mise à jour

Points de terminaison Work Chain

GET /api/v1/work-chains/list

Liste toutes les work chains du projet.

GET /api/v1/work-chains/get

Récupère une work chain par ID.

  • id (requis) - L’ID du document work chain

GET /api/v1/work-chains/issues

Récupère toutes les issues liées à une work chain.

  • id (requis) - L’ID du document work chain

POST /api/v1/work-chains/create

Crée une nouvelle work chain à partir d’un ensemble d’issues.

{
  "title": "Security Fix Chain",
  "description": "Fix all security issues found in audit",
  "issueIds": ["issue1", "issue2"],
  "workflowId": "...",
  "githubRepoUrl": "https://github.com/org/repo",
  "branchName": "fix/security-issues"
}

POST /api/v1/work-chains/delete

Supprime une work chain.

{ "chainId": "..." }

POST /api/v1/work-chains/start

Démarre l’exécution d’une work chain.

{ "chainId": "..." }

Réponse (201 Created) :

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