Endpoint Operations API

Riferimento completo per gli endpoint REST API di notifiche, merging, analytics, cestino, sprint chain, task ricorrenti, branch, pull request e inbox in CodeCourier.

14 min letto
apinotificationsmerging

L’Operations API copre aspetti trasversali: notifiche, merge di PR, analytics di utilizzo, gestione del cestino, sprint chain, task ricorrenti, gestione branch GitHub, operazioni sulle pull request e gestione dell’inbox. Questi 28 endpoint ti aiutano a monitorare l’attività, unire lavoro completato, tracciare i costi, pianificare automazioni ricorrenti e gestire le risorse eliminate.

Notifiche

GET /api/v1/notifications/list

Elenca le notifiche per l’utente e il progetto correnti.

Parametri di query:

  • filter (opzionale) - Tipo di filtro (ad es., unread, all)
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/notifications/list?filter=unread"

I tipi di notifica includono: run_completed, run_failed, pr_created, pr_merged, pr_failed, member_joined, workflow_completed, sprint_completed, sprint_failed.

GET /api/v1/notifications/unread-count

Ottieni il conteggio delle notifiche non lette.

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

Risposta:

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

POST /api/v1/notifications/mark-read

Segna una singola notifica come letta.

{ "notificationId": "..." }

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

Segna tutte le notifiche del progetto come lette. Nessun body richiesto.

POST /api/v1/notifications/dismiss

Ignora una notifica (la nasconde dalla lista).

{ "notificationId": "..." }

Endpoint REST Inbox / Notification

Oltre agli endpoint legacy /notifications/* sopra, l’API espone un’interfaccia inbox RESTful sotto /api/v1/notifications usando i verbi HTTP standard:

GET /api/v1/notifications

Elenca tutte le notifiche del progetto usando URL in stile REST.

Parametri di query:

  • filter (opzionale) - unread o all (predefinito: all)
  • limit (opzionale) - Risultati massimi (predefinito: 50)
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/notifications?filter=unread&limit=20"

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

Segna una notifica specifica come letta.

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

PUT /api/v1/notifications/read-all

Segna tutte le notifiche del progetto come lette. Nessun body richiesto.

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

DELETE /api/v1/notifications/:id

Ignora e rimuove una notifica specifica.

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

Merging

GET /api/v1/merging/list

Elenca tutti i run dell’agente di merge del progetto.

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

POST /api/v1/merging/start

Avvia un agente di merge che combina più pull request in una sola. L’agente di merge effettua il provisioning di una sandbox, recupera tutte le PR, risolve i conflitti e crea una PR unificata.

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

Obbligatorio: pullRequests (array non vuoto di oggetti PR).

Opzionale: baseBranch, config.

Risposta (201 Created):

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

Analytics

GET /api/v1/analytics/usage

Recupera i record di utilizzo (compute, token, chiamate API) con filtri per intervallo di date e servizio.

Parametri di query:

  • startDate (opzionale) - Stringa data ISO (ad es., 2024-01-01)
  • endDate (opzionale) - Stringa data ISO
  • service (opzionale) - Filtra per servizio (ad es., 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

Ottieni le statistiche aggregate giornaliere del progetto.

Parametri di query:

  • startDate (opzionale) - Inizio dell’intervallo di date
  • endDate (opzionale) - Fine dell’intervallo di date

GET /api/v1/analytics/counters

Ottieni i contatori attuali del progetto (run totali, sandbox attive, issue in sospeso, ecc.).

Gestione del cestino

GET /api/v1/trash/list

Elenca tutte le risorse eliminate con soft-delete in tutti i tipi di entità (run, sandbox, workflow, issue session, learning, ecc.).

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

POST /api/v1/trash/restore

Ripristina una risorsa eliminata con soft-delete dal cestino.

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

Valori validi per entityType: run, sandbox, workflow, learning, issueSession.

POST /api/v1/trash/permanent-delete

Elimina definitivamente una risorsa dal cestino. Non può essere annullato.

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

GET /api/v1/trash

Endpoint in stile REST per elencare gli elementi eliminati con soft-delete. Restituisce gli stessi dati di GET /api/v1/trash/list. Supporta un parametro di query type opzionale per filtrare per tipo di entità.

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

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

Ripristino in stile REST. :type è il tipo di entità (ad es., run) e :id è l’ID dell’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

Eliminazione definitiva in stile REST. Rimuove irreversibilmente l’entità dal sistema.

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

Sprint Chain

Le sprint chain orchestrano lavoro IA multi-sprint, eseguendo una serie di run sequenziali attraverso sprint numerati. Una sprint chain può essere messa in pausa, ripresa da un indice di sprint specifico, e tiene traccia degli URL delle PR generate per ogni sprint.

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

Valori di stato della sprint chain: pending, running, completed, failed, cancelled.

  • sprintRange ([start, end]) - I numeri di sprint iniziale e finale della chain
  • currentSprintIndex (number) - Indice a base zero dello sprint attualmente in esecuzione
  • resumeFromSprint (number | null) - Se impostato, la chain ripartirà da questo indice di sprint al prossimo tentativo di run
  • sprintPrUrls (string[]) - Lista ordinata degli URL delle PR generate da ogni sprint completato
  • workflowId (string) - Il blueprint di workflow usato per ogni esecuzione di sprint

GET /api/v1/sprint-chains

Elenca tutte le sprint chain del progetto.

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

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

Ottieni una singola sprint chain per ID, inclusi tutti i metadati di sprint e gli URL delle PR.

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

POST /api/v1/sprint-chains

Crea e avvia una nuova 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

Campi del body:

  • workflowId (string, obbligatorio) - Blueprint di workflow da eseguire per ogni sprint
  • sprintRange ([number, number], obbligatorio) - Numeri di sprint iniziale e finale (inclusi)
  • prompt (string, obbligatorio) - Descrizione del task principale condivisa tra tutti gli sprint
  • githubRepoUrl (string, obbligatorio) - URL del repository di destinazione
  • branchName (string, opzionale) - Branch di base da cui lavorare
  • resumeFromSprint (number, opzionale) - Avviare l’esecuzione da un indice di sprint specifico (per riprendere chain interrotte)

Risposta (201 Created):

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

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

Annulla ed elimina una sprint chain. Se la chain è attualmente in esecuzione, allo sprint attivo è permesso terminare prima che la chain venga contrassegnata come annullata.

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

Task ricorrenti

I task ricorrenti ti permettono di pianificare un prompt di workflow da eseguire automaticamente a una cadenza fissa - giornaliera, settimanale, mensile e altro. Ogni attivazione crea un nuovo run con i campi scheduledFor e recurrencePattern popolati.

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

Valori di frequenza: daily, every_other_day, weekly, biweekly, monthly.

  • timezone (stringa fuso orario IANA) - Fuso orario per interpretare scheduledHour e scheduledMinute
  • scheduledHour (0-23) - Ora del giorno nel fuso orario specificato in cui il task si attiva
  • scheduledMinute (0-59) - Minuto nell’ora in cui il task si attiva
  • nextRunAt (timestamp ISO) - Data/ora UTC della prossima esecuzione pianificata
  • isActive (boolean) - Se il task è attualmente abilitato; i task inattivi non vengono eseguiti

GET /api/v1/recurring-tasks

Elenca tutti i task ricorrenti del progetto.

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

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

Ottieni un singolo task ricorrente per ID.

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

POST /api/v1/recurring-tasks

Crea un nuovo task ricorrente.

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

Campi del body:

  • title (string, obbligatorio) - Nome del task leggibile
  • prompt (string, obbligatorio) - Il prompt del task inviato all’agente IA a ogni esecuzione
  • frequency (string, obbligatorio) - Frequenza di ricorrenza: daily, every_other_day, weekly, biweekly, o monthly
  • targetWorkflowId (string, obbligatorio) - Blueprint di workflow da usare per ogni run
  • timezone (string, obbligatorio) - Stringa fuso orario IANA (ad es., America/New_York, UTC)
  • scheduledHour (number, obbligatorio) - Ora di attivazione (0-23, nel fuso orario specificato)
  • scheduledMinute (number, obbligatorio) - Minuto di attivazione (0-59)
  • description (string, opzionale) - Descrizione estesa a scopo di documentazione

Risposta (201 Created):

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

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

Aggiorna un task ricorrente. Tutti i campi sono opzionali; vengono modificati solo i campi forniti. Aggiornare campi relativi alla pianificazione (frequency, scheduledHour, scheduledMinute, timezone) ricalcola automaticamente 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

Elimina definitivamente un task ricorrente. I run attivi già in corso non vengono influenzati.

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

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

Attiva o disattiva un task ricorrente. Un task inattivo viene preservato ma non si attiverà secondo la sua pianificazione. Usa questo per mettere in pausa temporaneamente l’automazione senza eliminare la configurazione.

# 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

Campi del body:

  • isActive (boolean, obbligatorio) - true per attivare, false per disattivare

Informazioni

Quando riattivi un task, nextRunAt viene ricalcolato dall’ora corrente usando la frequenza e la pianificazione del task. Il task non si attiverà retroattivamente per le esecuzioni mancate mentre era inattivo.

Branch

La Branches API espone i branch GitHub del repository configurato del progetto, permettendoti di ispezionare e ripulire i branch di feature creati dai run IA.

GET /api/v1/branches

Elenca i branch GitHub del repository del progetto. Restituisce i metadati del branch inclusi lo SHA dell’ultimo commit, l’autore e il timestamp.

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

Parametri di query:

  • prefix (opzionale) - Filtra i branch per prefisso del nome (ad es., feature/)
  • limit (opzionale) - Risultati massimi (predefinito: 100)

Avvertimento

Questo endpoint chiama l’API GitHub a ogni richiesta. Se il progetto non ha configurato una chiave di provider GitHub, restituisce un errore 400. Evita il polling ad alta frequenza; metti in cache le liste di branch lato client e aggiorna su richiesta.

DELETE /api/v1/branches/:name

Elimina un branch GitHub per nome. Il nome del branch deve essere codificato per URL se contiene slash (ad es., feature%2Fdark-mode). I branch protetti e il branch predefinito non possono essere eliminati tramite questo endpoint.

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

Pull Request

La Pull Requests API ti permette di elencare le PR aperte tra i run e di attivare operazioni di merge automatizzate.

GET /api/v1/pull-requests

Elenca le pull request del progetto, incluso il loro stato dei check CI. I risultati provengono dai record dei run di CodeCourier anziché dal polling diretto di GitHub, quindi riflettono le PR create dai run IA all’interno della piattaforma.

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

Parametri di query:

  • status (opzionale) - Filtra per stato della PR: creating, created, failed, skipped, merged, blocked_on_ci
  • runId (opzionale) - Ottieni la PR per un run specifico

Risposta:

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

Attiva l’agente di merge per una pull request specifica. Il parametro :id è l’ID del run associato alla PR, non il numero della PR. L’agente di merge effettua il provisioning di una sandbox, verifica lo stato CI ed esegue il merge.

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

Campi del body opzionali:

  • mergeStrategy (string) - Strategia di merge: merge, squash, o rebase (predefinito: squash)
  • skipCiCheck (boolean) - Forza il merge anche se la CI non è passata (usa con cautela)

Risposta (201 Created):

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

Avvertimento

Impostare skipCiCheck: true aggira l’applicazione del gate CI. Usalo solo se sei certo che il fallimento sia un test instabile o non correlato alle modifiche nella PR.