Endpoint Issue, Answering Session & Work Chain API

Riferimento completo per gli endpoint REST API di issue, issue session, answering session, session question e work chain - scopri, chiarisci, monitora e risolvi le issue della codebase tramite IA.

15 min letto
apiissuesissue-sessions

Le issue rappresentano bug, miglioramenti o task scoperti nella tua codebase. Le issue session sono run di scansione basati sull’IA che trovano issue automaticamente. Le answering session permettono a un agente IA di generare domande di chiarimento fatte revisionare prima di intraprendere un lavoro complesso. Le work chain raggruppano issue in sequenze di esecuzione. Insieme, questi 30 endpoint abilitano un workflow completo di scoperta-chiarimento-monitoraggio-risoluzione.

Endpoint Issue

GET /api/v1/issues/list

Elenca le issue con filtri opzionali.

Parametri di query:

  • status (opzionale) - Filtra per stato dell’issue
  • sessionId (opzionale) - Filtra per issue session
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/issues/list?status=open"

GET /api/v1/issues/get

Recupera una singola issue per ID.

  • id (obbligatorio) - L’ID del documento issue

POST /api/v1/issues/create

Crea manualmente una nuova issue.

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

Campi del body:

  • title (string, obbligatorio) - Titolo dell’issue
  • description (string, opzionale) - Descrizione dettagliata
  • priority (string, opzionale) - Livello di priorità (ad es., high, medium, low)
  • suggestedPrompt (string, opzionale) - Prompt IA per risolvere l’issue
  • sessionId (string, opzionale) - Collegamento alla session di scoperta

POST /api/v1/issues/update

Aggiorna un’issue esistente.

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

Campi: issueId (obbligatorio), più i campi opzionali title, description, priority, suggestedPrompt.

POST /api/v1/issues/delete

Elimina un’issue.

{ "issueId": "..." }

POST /api/v1/issues/link-run

Collega un run di workflow a un’issue (segna l’issue come in lavorazione).

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

POST /api/v1/issues/bulk-delete

Elimina più issue.

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

Endpoint Issue Session

GET /api/v1/issue-sessions/list

Elenca tutte le session di scansione issue del progetto.

GET /api/v1/issue-sessions/get

Recupera una singola issue session.

  • id (obbligatorio) - L’ID del documento session

POST /api/v1/issue-sessions/rename

Rinomina una issue session.

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

POST /api/v1/issue-sessions/delete

Elimina (soft-delete) una issue session.

{ "sessionId": "..." }

POST /api/v1/issue-sessions/restore

Ripristina una issue session eliminata con soft-delete.

{ "sessionId": "..." }

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

Elimina definitivamente una issue session.

{ "sessionId": "..." }

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

Elimina (soft-delete) più issue session.

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

POST /api/v1/issue-sessions/start

Avvia una nuova session di scansione issue basata sull’IA. Effettua il provisioning di una sandbox che analizza la tua codebase e scopre le issue.

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

Obbligatorio: prompt. Opzionale: templateId, memoryMb, cpuCount, timeoutMs.

Risposta (201 Created):

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

Answering Sessions

Le answering session permettono a un agente IA di generare domande di chiarimento prima di intraprendere un lavoro complesso. Un umano (o un sistema automatizzato) revisiona ogni domanda, approvando l’assunzione dell’agente oppure fornendo una correzione. L’agente procede quindi con le risposte revisionate come contesto aggiuntivo.

Le answering session sono collegate a una issue session tramite issueSessionId. Il workflow completo è:

  1. Avvia una issue session (POST /api/v1/issue-sessions/start)
  2. Crea una answering session per essa (POST /api/v1/answering-sessions)
  3. L’agente popola le domande tramite il callback Trigger.dev
  4. Revisiona ogni domanda tramite PUT /api/v1/session-questions/:id/review
  5. Aggiorna lo stato della session a reviewed per segnalare all’agente di procedere

Oggetto Answering Session

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

Valori di stato della session: pending (creata, in attesa di domande), active (domande generate, in attesa di revisione), reviewed (tutte le domande revisionate, l’agente può procedere), completed(agente terminato con le risposte), archived(soft-delete).

GET /api/v1/answering-sessions

Elenca le answering session del progetto.

Parametri di query:

  • issueSessionId (opzionale) - Filtra per issue session genitore
  • status (opzionale) - Filtra per stato della session
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/answering-sessions?status=active"

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

Recupera una singola answering session per ID.

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

Risposta:

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

POST /api/v1/answering-sessions

Crea una nuova answering session collegata a una issue session.

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

Campi del body:

  • issueSessionId (string, obbligatorio) - La issue session genitore a cui appartiene questa answering session

Risposta (201 Created):

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

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

Aggiorna lo stato di una 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

Campi del body:

  • status (string, obbligatorio) - Nuovo stato: pending, active, reviewed, completed, o archived

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

Archivia (soft-delete) una answering session. La session viene spostata nel cestino e può essere ripristinata. Usa l’endpoint permanent-delete del cestino per rimuoverla definitivamente.

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

Session Questions

Le session question sono i singoli elementi di chiarimento all’interno di una answering session. L’agente IA genera un’assunzione iniziale per ogni domanda; i revisori possono approvare l’assunzione o fornire una correzione.

Oggetto 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
}

Valori di stato della domanda: pending (in attesa di revisione), approved (il revisore ha accettato l’assunzione), declined (il revisore ha fornito una correzione).

GET /api/v1/session-questions

Elenca le domande di una data answering session.

Parametri di query:

  • answeringSessionId (obbligatorio) - La answering session di cui elencare le domande
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/session-questions?answeringSessionId=as_..."

Risposta:

{
  "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

Revisiona una domanda approvando l’assunzione dell’agente oppure rifiutandola con una correzione. Se rifiuti, fornisci la risposta corretta in 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

Campi del body:

  • status (string, obbligatorio) - Decisione di revisione: approved o declined
  • correction (string, obbligatorio se lo status è declined) - La risposta o istruzione corretta che sovrascrive l’assunzione dell’agente

Avvertimento

Se rifiuti una domanda senza fornire una correction, l’endpoint restituisce un errore 400. La correzione è la risposta autorevole che l’agente userà - una correzione vuota lascerebbe l’agente senza indicazioni.

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

Aggiorna l’assunzione generata dall’IA per una domanda senza cambiarne lo stato di revisione. Usa questo per pre-popolare o correggere il testo dell’assunzione prima della fase di revisione formale.

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

Campi del body:

  • assumption (string, obbligatorio) - Il testo dell’assunzione aggiornata

Endpoint Work Chain

GET /api/v1/work-chains/list

Elenca tutte le work chain del progetto.

GET /api/v1/work-chains/get

Recupera una work chain per ID.

  • id (obbligatorio) - L’ID del documento work chain

GET /api/v1/work-chains/issues

Recupera tutte le issue collegate a una work chain.

  • id (obbligatorio) - L’ID del documento work chain

POST /api/v1/work-chains/create

Crea una nuova work chain a partire da un insieme di issue.

{
  "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

Elimina una work chain.

{ "chainId": "..." }

POST /api/v1/work-chains/start

Avvia l’esecuzione di una work chain.

{ "chainId": "..." }

Risposta (201 Created):

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