Operations-API-Endpunkte

Vollständige Referenz für die REST-API-Endpunkte zu Benachrichtigungen, Merging, Analytics, Papierkorb, Sprint-Chains, wiederkehrenden Aufgaben, Branches, Pull Requests und Inbox in CodeCourier.

14 Min. Lesezeit
apinotificationsmerging

Die Operations-API deckt übergreifende Belange ab: Benachrichtigungen, PR-Merging, Nutzungs-Analytics, Papierkorbverwaltung, Sprint-Chains, wiederkehrende Aufgaben, GitHub-Branch-Management, Pull-Request-Vorgänge und Inbox-Verwaltung. Diese 28 Endpunkte helfen Ihnen, Aktivität zu überwachen, abgeschlossene Arbeit zu mergen, Kosten zu verfolgen, wiederkehrende Automatisierung zu planen und gelöschte Ressourcen zu verwalten.

Benachrichtigungen

GET /api/v1/notifications/list

Benachrichtigungen für den aktuellen Benutzer und das aktuelle Projekt auflisten.

Query-Parameter:

  • filter (optional) -- Filtertyp (z. B. unread, all)
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/notifications/list?filter=unread"

Benachrichtigungstypen umfassen: run_completed, run_failed, pr_created, pr_merged, pr_failed, member_joined, workflow_completed, sprint_completed, sprint_failed.

GET /api/v1/notifications/unread-count

Anzahl ungelesener Benachrichtigungen abrufen.

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

Antwort:

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

POST /api/v1/notifications/mark-read

Eine einzelne Benachrichtigung als gelesen markieren.

{ "notificationId": "..." }

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

Alle Benachrichtigungen des Projekts als gelesen markieren. Kein Body erforderlich.

POST /api/v1/notifications/dismiss

Eine Benachrichtigung verwerfen (blendet sie aus der Liste aus).

{ "notificationId": "..." }

Inbox- / Benachrichtigungs-REST-Endpunkte

Zusätzlich zu den Legacy-Endpunkten /notifications/* oben stellt die API eine RESTful Inbox-Schnittstelle unter /api/v1/notifications mit standardmäßigen HTTP-Verben bereit:

GET /api/v1/notifications

Alle Benachrichtigungen des Projekts per REST-stil-URL auflisten.

Query-Parameter:

  • filter (optional) -- unread oder all (Standard: all)
  • limit (optional) -- Maximale Ergebnisse (Standard: 50)
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/notifications?filter=unread&limit=20"

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

Eine bestimmte Benachrichtigung als gelesen markieren.

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

PUT /api/v1/notifications/read-all

Alle Benachrichtigungen des Projekts als gelesen markieren. Kein Body erforderlich.

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

DELETE /api/v1/notifications/:id

Eine bestimmte Benachrichtigung verwerfen und entfernen.

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

Merging

GET /api/v1/merging/list

Alle Merge-Agent-Runs des Projekts auflisten.

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

POST /api/v1/merging/start

Einen Merge-Agenten starten, der mehrere Pull Requests zu einem kombiniert. Der Merge-Agent provisioniert eine Sandbox, holt alle PRs, löst Konflikte und erstellt einen vereinheitlichten PR.

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

Erforderlich: pullRequests (nicht-leeres Array von PR-Objekten).

Optional: baseBranch, config.

Antwort (201 Created):

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

Analytics

GET /api/v1/analytics/usage

Nutzungsdatensätze abrufen (Compute, Tokens, API-Aufrufe) mit Datums- und Service-Filterung.

Query-Parameter:

  • startDate (optional) -- ISO-Datums-String (z. B. 2024-01-01)
  • endDate (optional) -- ISO-Datums-String
  • service (optional) -- Nach Service filtern (z. B. 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

Tägliche aggregierte Statistiken des Projekts abrufen.

Query-Parameter:

  • startDate (optional) -- Beginn des Datumsbereichs
  • endDate (optional) -- Ende des Datumsbereichs

GET /api/v1/analytics/counters

Aktuelle Projektzähler abrufen (Gesamt-Runs, aktive Sandboxes, offene Issues usw.).

Papierkorbverwaltung

GET /api/v1/trash/list

Alle per Soft-Delete gelöschten Ressourcen über alle Entitätstypen hinweg auflisten (Runs, Sandboxes, Workflows, Issue-Sitzungen, Learnings usw.).

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

POST /api/v1/trash/restore

Eine per Soft-Delete gelöschte Ressource aus dem Papierkorb wiederherstellen.

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

Gültige entityType-Werte: run, sandbox, workflow, learning, issueSession.

POST /api/v1/trash/permanent-delete

Eine Ressource dauerhaft aus dem Papierkorb löschen. Kann nicht rückgängig gemacht werden.

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

GET /api/v1/trash

REST-stil-Endpunkt zum Auflisten per Soft-Delete gelöschter Items. Liefert dieselben Daten wie GET /api/v1/trash/list. Unterstützt einen optionalen type-Query-Parameter zur Filterung nach Entitätstyp.

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

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

REST-stil-Wiederherstellung. :type ist der Entitätstyp (z. B. run) und :id ist die Entitäts-ID.

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

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

REST-stil-Permanent-Delete. Entfernt die Entität unwiderruflich aus dem System.

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

Sprint-Chains

Sprint-Chains orchestrieren KI-Arbeit über mehrere Sprints hinweg und führen eine Reihe sequentieller Runs über nummerierte Sprints aus. Eine Sprint-Chain kann pausiert, ab einem bestimmten Sprint-Index fortgesetzt werden und verfolgt die generierten PR-URLs pro Sprint.

Sprint-Chain-Objekt

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

Sprint-Chain-Status-Werte: pending, running, completed, failed, cancelled.

  • sprintRange ([start, end]) -- Erste und letzte Sprint-Nummer in der Chain
  • currentSprintIndex (number) -- Null-basierter Index des aktuell ausgeführten Sprints
  • resumeFromSprint (number | null) -- Falls gesetzt, startet die Chain beim nächsten Run-Versuch ab diesem Sprint-Index neu
  • sprintPrUrls (string[]) -- Geordnete Liste von PR-URLs, die von jedem abgeschlossenen Sprint erzeugt wurden
  • workflowId (string) -- Der Workflow-Blueprint, der für jede Sprint-Ausführung verwendet wird

GET /api/v1/sprint-chains

Alle Sprint-Chains des Projekts auflisten.

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

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

Eine einzelne Sprint-Chain per ID abrufen, inklusive vollständiger Sprint-Metadaten und PR-URLs.

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

POST /api/v1/sprint-chains

Eine neue Sprint-Chain erstellen und starten.

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

Body-Felder:

  • workflowId (string, erforderlich) -- Workflow-Blueprint, der für jeden Sprint ausgeführt wird
  • sprintRange ([number, number], erforderlich) -- Start- und Ende-Sprint-Nummern (inklusive)
  • prompt (string, erforderlich) -- Master-Aufgabenbeschreibung, die über alle Sprints hinweg geteilt wird
  • githubRepoUrl (string, erforderlich) -- Ziel-Repository-URL
  • branchName (string, optional) -- Basis-Branch, von dem aus gearbeitet wird
  • resumeFromSprint (number, optional) -- Ausführung ab einem bestimmten Sprint-Index starten (zur Fortsetzung unterbrochener Chains)

Antwort (201 Created):

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

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

Eine Sprint-Chain abbrechen und löschen. Wenn die Chain derzeit läuft, darf der aktive Sprint zu Ende laufen, bevor die Chain als abgebrochen markiert wird.

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

Wiederkehrende Aufgaben

Wiederkehrende Aufgaben ermöglichen es, einen Workflow-Prompt automatisch in einem festen Takt auszuführen - täglich, wöchentlich, monatlich und mehr. Jede Auslösung erzeugt einen neuen Run mit gesetzten Feldern scheduledFor und recurrencePattern.

Objekt einer wiederkehrenden Aufgabe

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

Frequency-Werte: daily, every_other_day, weekly, biweekly, monthly.

  • timezone (IANA-Zeitzonen-String) -- Zeitzone für die Interpretation von scheduledHour und scheduledMinute
  • scheduledHour (0-23) -- Tagesstunde in der angegebenen Zeitzone, zu der die Aufgabe ausgelöst wird
  • scheduledMinute (0-59) -- Minute innerhalb der Stunde, zu der die Aufgabe ausgelöst wird
  • nextRunAt (ISO-Zeitstempel) -- UTC-Zeitpunkt der nächsten geplanten Ausführung
  • isActive (boolean) -- Ob die Aufgabe derzeit aktiviert ist; inaktive Aufgaben werden nicht ausgeführt

GET /api/v1/recurring-tasks

Alle wiederkehrenden Aufgaben des Projekts auflisten.

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

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

Eine einzelne wiederkehrende Aufgabe per ID abrufen.

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

POST /api/v1/recurring-tasks

Eine neue wiederkehrende Aufgabe erstellen.

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

Body-Felder:

  • title (string, erforderlich) -- Menschenlesbarer Aufgabenname
  • prompt (string, erforderlich) -- Aufgaben-Prompt, der bei jeder Ausführung an den KI-Agenten gesendet wird
  • frequency (string, erforderlich) -- Wiederholungsfrequenz: daily, every_other_day, weekly, biweekly oder monthly
  • targetWorkflowId (string, erforderlich) -- Workflow-Blueprint, der für jeden Run verwendet wird
  • timezone (string, erforderlich) -- IANA-Zeitzonen-String (z. B. America/New_York, UTC)
  • scheduledHour (number, erforderlich) -- Auslösestunde (0-23, in der angegebenen Zeitzone)
  • scheduledMinute (number, erforderlich) -- Auslöseminute (0-59)
  • description (string, optional) -- Erweiterte Beschreibung zu Dokumentationszwecken

Antwort (201 Created):

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

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

Eine wiederkehrende Aufgabe aktualisieren. Alle Felder sind optional; nur die angegebenen Felder werden geändert. Das Aktualisieren von zeitplanbezogenen Feldern (frequency, scheduledHour, scheduledMinute, timezone) berechnet nextRunAt automatisch neu.

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

Eine wiederkehrende Aufgabe dauerhaft löschen. Bereits laufende aktive Runs sind nicht betroffen.

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

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

Eine wiederkehrende Aufgabe aktivieren oder deaktivieren. Eine inaktive Aufgabe bleibt erhalten, wird aber nicht laut Zeitplan ausgelöst. Verwenden Sie dies, um die Automatisierung vorübergehend zu pausieren, ohne die Konfiguration zu löschen.

# 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

Body-Felder:

  • isActive (boolean, erforderlich) -- true zum Aktivieren, false zum Deaktivieren

Info

Wenn Sie eine Aufgabe reaktivieren, wird nextRunAt ab dem aktuellen Zeitpunkt unter Verwendung der Frequenz und des Zeitplans der Aufgabe neu berechnet. Die Aufgabe wird nicht rückwirkend für Ausführungen ausgelöst, die während der Inaktivität versäumt wurden.

Branches

Die Branches-API stellt GitHub-Branches für das konfigurierte Repository des Projekts bereit und ermöglicht es Ihnen, von KI-Runs erstellte Feature-Branches zu inspizieren und aufzuräumen.

GET /api/v1/branches

GitHub-Branches für das Repository des Projekts auflisten. Liefert Branch-Metadaten inklusive letzter Commit-SHA, Autor und Zeitstempel.

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
#       }
#     ]
#   }

Query-Parameter:

  • prefix (optional) -- Branches nach Namens-Präfix filtern (z. B. feature/)
  • limit (optional) -- Maximale Ergebnisse (Standard: 100)

Warnung

Dieser Endpunkt ruft bei jeder Anfrage die GitHub-API auf. Wenn für das Projekt kein GitHub-Provider-Schlüssel konfiguriert ist, liefert er einen 400-Fehler. Vermeiden Sie hochfrequentes Polling; cachen Sie Branch-Listen clientseitig und aktualisieren Sie bei Bedarf.

DELETE /api/v1/branches/:name

Einen GitHub-Branch per Name löschen. Der Branch-Name sollte URL-kodiert sein, wenn er Schrägstriche enthält (z. B. feature%2Fdark-mode). Geschützte Branches und der Default-Branch können über diesen Endpunkt nicht gelöscht werden.

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

Pull Requests

Die Pull-Requests-API ermöglicht es, offene PRs über Runs hinweg aufzulisten und automatisierte Merge-Operationen auszulösen.

GET /api/v1/pull-requests

Pull Requests des Projekts auflisten, inklusive ihres CI-Check-Status. Die Ergebnisse stammen aus den Run-Datensätzen von CodeCourier statt aus direktem GitHub-Polling und spiegeln daher PRs wider, die von KI-Runs innerhalb der Plattform erstellt wurden.

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

Query-Parameter:

  • status (optional) -- Nach PR-Status filtern: creating, created, failed, skipped, merged, blocked_on_ci
  • runId (optional) -- PR für einen bestimmten Run abrufen

Antwort:

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

Den Merge-Agenten für einen bestimmten Pull Request auslösen. Der Parameter :id ist die zur PR gehörende Run-ID, nicht die PR-Nummer. Der Merge-Agent provisioniert eine Sandbox, verifiziert den CI-Status und führt den Merge durch.

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

Optionale Body-Felder:

  • mergeStrategy (string) -- Merge-Strategie: merge, squash oder rebase (Standard: squash)
  • skipCiCheck (boolean) -- Merge erzwingen, auch wenn CI nicht erfolgreich war (mit Vorsicht verwenden)

Antwort (201 Created):

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

Warnung

Das Setzen von skipCiCheck: true umgeht die Durchsetzung des CI-Gates. Verwenden Sie dies nur, wenn Sie sicher sind, dass der Fehler ein flacky Test ist oder nichts mit den Änderungen im PR zu tun hat.