Issue-, Antwortsitzungs- & Work-Chain-API-Endpunkte

Vollständige Referenz für die REST-API-Endpunkte zu Issues, Issue-Sitzungen, Antwortsitzungen, Sitzungsfragen und Work Chains - Issues im Codebase per KI entdecken, klären, verfolgen und beheben.

15 Min. Lesezeit
apiissuesissue-sessions

Issues repräsentieren entdeckte Bugs, Verbesserungen oder Aufgaben in Ihrem Codebase. Issue-Sitzungen sind KI-gestützte Scan-Läufe, die automatisch Issues finden. Antwortsitzungen ermöglichen es einem KI-Agenten, vor dem Ausführen komplexer Arbeit Klärungsfragen zu generieren und prüfen zu lassen. Work Chains gruppieren Issues zu Ausführungs-Sequenzen. Zusammen ermöglichen diese 30 Endpunkte einen vollständigen Discover-Clarify-Track-Resolve-Workflow.

Issue-Endpunkte

GET /api/v1/issues/list

Issues mit optionaler Filterung auflisten.

Query-Parameter:

  • status (optional) -- Nach Issue-Status filtern
  • sessionId (optional) -- Nach Issue-Sitzung filtern
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/issues/list?status=open"

GET /api/v1/issues/get

Ein einzelnes Issue per ID abrufen.

  • id (erforderlich) -- Die Issue-Dokument-ID

POST /api/v1/issues/create

Ein neues Issue manuell erstellen.

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

Body-Felder:

  • title (string, erforderlich) -- Issue-Titel
  • description (string, optional) -- Detaillierte Beschreibung
  • priority (string, optional) -- Prioritätsstufe (z. B. high, medium, low)
  • suggestedPrompt (string, optional) -- KI-Prompt zur Behebung des Issues
  • sessionId (string, optional) -- Verknüpfung zur Discovery-Sitzung

POST /api/v1/issues/update

Ein bestehendes Issue aktualisieren.

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

Felder: issueId (erforderlich) sowie optional title, description, priority, suggestedPrompt.

POST /api/v1/issues/delete

Ein Issue löschen.

{ "issueId": "..." }

POST /api/v1/issues/link-run

Einen Workflow-Run mit einem Issue verknüpfen (markiert das Issue als in Bearbeitung).

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

POST /api/v1/issues/bulk-delete

Mehrere Issues löschen.

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

Issue-Sitzungs-Endpunkte

GET /api/v1/issue-sessions/list

Alle Issue-Scanning-Sitzungen des Projekts auflisten.

GET /api/v1/issue-sessions/get

Eine einzelne Issue-Sitzung abrufen.

  • id (erforderlich) -- Die Dokument-ID der Sitzung

POST /api/v1/issue-sessions/rename

Eine Issue-Sitzung umbenennen.

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

POST /api/v1/issue-sessions/delete

Eine Issue-Sitzung per Soft-Delete löschen.

{ "sessionId": "..." }

POST /api/v1/issue-sessions/restore

Eine per Soft-Delete gelöschte Issue-Sitzung wiederherstellen.

{ "sessionId": "..." }

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

Eine Issue-Sitzung dauerhaft löschen.

{ "sessionId": "..." }

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

Mehrere Issue-Sitzungen per Soft-Delete löschen.

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

POST /api/v1/issue-sessions/start

Eine neue KI-gestützte Issue-Scanning-Sitzung starten. Provisioniert eine Sandbox, die Ihren Codebase analysiert und Issues entdeckt.

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

Erforderlich: prompt. Optional: templateId, memoryMb, cpuCount, timeoutMs.

Antwort (201 Created):

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

Antwortsitzungen

Antwortsitzungen ermöglichen es einem KI-Agenten, vor der Bearbeitung komplexer Arbeit Klärungsfragen zu generieren. Ein Mensch (oder ein automatisiertes System) prüft jede Frage, indem er entweder der Annahme des Agenten zustimmt oder eine Korrektur liefert. Der Agent fährt anschließend mit den geprüften Antworten als zusätzlichem Kontext fort.

Antwortsitzungen sind über issueSessionId mit einer Issue-Sitzung verknüpft. Der vollständige Workflow ist:

  1. Eine Issue-Sitzung starten (POST /api/v1/issue-sessions/start)
  2. Eine Antwortsitzung dafür erstellen (POST /api/v1/answering-sessions)
  3. Der Agent füllt die Fragen über den Trigger.dev-Callback
  4. Jede Frage über PUT /api/v1/session-questions/:id/review prüfen
  5. Den Sitzungsstatus auf reviewed aktualisieren, um dem Agenten den Fortgang zu signalisieren

Antwortsitzungs-Objekt

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

Sitzungsstatus-Werte: pending (erstellt, wartet auf Fragen), active (Fragen erzeugt, wartet auf Prüfung), reviewed (alle Fragen geprüft, Agent darf fortfahren), completed (Agent ist mit den Antworten fertig), archived (per Soft-Delete gelöscht).

GET /api/v1/answering-sessions

Antwortsitzungen des Projekts auflisten.

Query-Parameter:

  • issueSessionId (optional) -- Nach übergeordneter Issue-Sitzung filtern
  • status (optional) -- Nach Sitzungsstatus filtern
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/answering-sessions?status=active"

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

Eine einzelne Antwortsitzung per ID abrufen.

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

Antwort:

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

POST /api/v1/answering-sessions

Eine neue Antwortsitzung erstellen, die mit einer Issue-Sitzung verknüpft ist.

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

Body-Felder:

  • issueSessionId (string, erforderlich) -- Die übergeordnete Issue-Sitzung, zu der diese Antwortsitzung gehört

Antwort (201 Created):

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

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

Den Status einer Antwortsitzung aktualisieren.

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

Body-Felder:

  • status (string, erforderlich) -- Neuer Status: pending, active, reviewed, completed oder archived

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

Eine Antwortsitzung archivieren (Soft-Delete). Die Sitzung wandert in den Papierkorb und kann wiederhergestellt werden. Verwenden Sie den Permanent-Delete-Papierkorb-Endpunkt, um sie vollständig zu entfernen.

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

Sitzungsfragen

Sitzungsfragen sind die einzelnen Klärungsobjekte innerhalb einer Antwortsitzung. Der KI-Agent erzeugt eine initiale Annahme für jede Frage; Prüfer können die Annahme akzeptieren oder eine Korrektur liefern.

Sitzungsfrage-Objekt

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

Frage-Status-Werte: pending (wartet auf Prüfung), approved (Prüfer hat die Annahme akzeptiert), declined (Prüfer hat eine Korrektur geliefert).

GET /api/v1/session-questions

Fragen für eine gegebene Antwortsitzung auflisten.

Query-Parameter:

  • answeringSessionId (erforderlich) -- Die Antwortsitzung, deren Fragen aufgelistet werden sollen
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/session-questions?answeringSessionId=as_..."

Antwort:

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

Eine Frage prüfen, indem Sie der Annahme des Agenten zustimmen oder sie mit einer Korrektur ablehnen. Bei Ablehnung liefern Sie die korrekte Antwort 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

Body-Felder:

  • status (string, erforderlich) -- Prüfentscheidung: approved oder declined
  • correction (string, erforderlich wenn status declined ist) -- Die korrekte Antwort oder Anweisung, die die Annahme des Agenten überschreibt

Warnung

Wenn Sie eine Frage ablehnen, ohne eine correction anzugeben, gibt der Endpunkt einen 400-Fehler zurück. Die Korrektur ist die maßgebliche Antwort, die der Agent verwenden wird - eine leere Korrektur würde den Agenten ohne Orientierung lassen.

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

Die KI-generierte Annahme einer Frage aktualisieren, ohne ihren Prüfstatus zu verändern. Damit können Sie den Annahmetext vor dem eigentlichen Prüfschritt vorbefüllen oder korrigieren.

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

Body-Felder:

  • assumption (string, erforderlich) -- Der aktualisierte Annahmetext

Work-Chain-Endpunkte

GET /api/v1/work-chains/list

Alle Work Chains des Projekts auflisten.

GET /api/v1/work-chains/get

Eine Work Chain per ID abrufen.

  • id (erforderlich) -- Die Dokument-ID der Work Chain

GET /api/v1/work-chains/issues

Alle mit einer Work Chain verknüpften Issues abrufen.

  • id (erforderlich) -- Die Dokument-ID der Work Chain

POST /api/v1/work-chains/create

Eine neue Work Chain aus einer Menge von Issues erstellen.

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

Eine Work Chain löschen.

{ "chainId": "..." }

POST /api/v1/work-chains/start

Die Ausführung einer Work Chain starten.

{ "chainId": "..." }

Antwort (201 Created):

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