Panoramica dell'API

L’API REST CodeCourier fornisce accesso programmatico completo a ogni funzionalità disponibile nel dashboard web. Con 171 endpoint su 26 categorie di risorse, un LLM o uno script di automazione può fare tutto ciò che può fare un umano - creare progetti, configurare workflow, avviare run di coding IA, gestire learning, configurare contesti e asset, pianificare task ricorrenti e altro. Tutti gli endpoint sono autenticati tramite chiavi API con scope di progetto e restituiscono risposte JSON coerenti.

URL di base

Tutti gli endpoint dell’API REST sono serviti dall’URL delle HTTP Action del tuo deployment Convex, sotto il prefisso /api/v1/:

https://<your-deployment>.convex.site/api/v1/

Importante: L’URL di base termina con .convex.site - NON .convex.cloud. Il dominio .convex.cloud è l’URL WebSocket dei dati Convex usato internamente. Il dominio .convex.site è l’endpoint HTTP Action che serve l’API REST. Usare il dominio sbagliato causerà errori di connessione.

Puoi trovare il nome del tuo deployment nel dashboard Convex. Di solito somiglia a happy-animal-123, dandoti un URL di base di: https://happy-animal-123.convex.site/api/v1/

Autenticazione

Ogni richiesta richiede una chiave API di progetto passata come bearer token nell’header Authorization. Le chiavi vengono generate tramite il dashboard o tramite l’API stessa. Vedi la pagina Autenticazione per tutti i dettagli sulla creazione e gestione delle chiavi.

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

Importante: L’header è Authorization: Bearer <key> - NON x-api-key, NON X-API-Key. Le chiavi API iniziano con cc_live_ (produzione) o cc_test_ (ambienti di test).

Formato della risposta

Tutte le risposte riuscite restituiscono:

{ "data": <result> }

Tutte le risposte di errore restituiscono:

{ "error": "Human-readable error message" }

Codici di stato HTTP standard:

• 200 - Successo
• 201 - Creato (per endpoint di azione come start)
• 400 - Richiesta non valida (campi mancanti, JSON non valido)
• 403 - Vietato (chiave API non valida o revocata)
• 404 - Risorsa non trovata
• 500 - Errore interno del server

ID delle risorse: id vs _id

Ogni risorsa restituita dall’API REST espone il suo identificatore canonico con due nomi di campo: id (convenzione REST) e _id (alias interno Convex, mantenuto per retrocompatibilità). Entrambi contengono la stessa stringa opaca e possono essere passati indifferentemente a qualsiasi endpoint che accetta un ID.

{
  "data": {
    "id":  "k57a8...",   // ← preferred in new code
    "_id": "k57a8...",   // ← retained for back-compat through 2026-10-24
    "name": "..."
  }
}

Le nuove integrazioni dovrebbero leggere id. Il campo _id è mantenuto su ogni proiezione fino al sunset dell’envelope v1 il 2026-10-24; dopo quella data potrebbe essere rimosso dalle risposte REST senza ulteriore preavviso. Le query interne Convex non sono influenzate - _id rimane il nome del campo di documento nel database.

Quick Start: avviare un run e ottenerne l’output

Ecco la sequenza minima di cui un agente o uno script ha bisogno per avviare un run e recuperare l’output completo della conversazione IA:

Passo 1 - Ottenere un workflow ID

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/workflows/list
# → { "data": [{ "id": "jx7...", "_id": "jx7...", "name": "My Workflow", ... }] }

Passo 2 - Avviare un run

curl -X POST \
  -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "jx7...",
    "prompt": "Add a dark mode toggle to the settings page",
    "githubRepoUrl": "https://github.com/org/repo"
  }' \
  https://<deployment>.convex.site/api/v1/runs/start
# → { "data": { "id": "abc...", "status": "running" } }

Nota: githubRepoUrl è di fatto obbligatorio. Senza di esso la sandbox non ha codice di progetto su cui lavorare e le operazioni git falliscono immediatamente con exit status 128.

Passo 3 - Attendere, poi elencare i run per ottenere il run ID

curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/runs?limit=5"
# → { "data": [{ "id": "r_abc...", "_id": "r_abc...", "status": "completed", ... }] }

Passo 4 - Ottenere i sandbox ID del run

curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/sandboxes/list?runId=r_abc..."
# → { "data": [{ "id": "s_xyz...", "_id": "s_xyz...", "status": "killed", ... }] }

Passo 5 - Ottenere l’output completo della conversazione

curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/sandboxes/messages?id=s_xyz..."
# → { "data": [{ "role": "assistant", "content": "...", "timestamp": ... }] }

Perché non usare /api/v1/runs/detail? Quell’endpoint restituisce i metadati del run e gli step di esecuzione, ma NON il testo della conversazione IA. L’output effettivo dell’agente risiede nei messaggi della sandbox.

Sezioni dell’API

L’API è organizzata nelle seguenti sezioni. Ciascuna è documentata in dettaglio nella propria pagina:

Gestione dei progetti - 16 endpoint

Leggi, aggiorna ed elimina il tuo progetto. Gestisci le impostazioni del progetto (system prompt, env var, config git), i membri del team (invitare, rimuovere, aggiornare i ruoli), le chiavi API dei provider (E2B, Anthropic, GitHub, ecc.), le chiavi API di progetto (generare, revocare) e visualizza i contatori del progetto.

Workflow - 10 endpoint

Elenca, ottieni, crea, aggiorna, elimina, ripristina, elimina in modo permanente, duplica, rinomina ed elimina in blocco i blueprint di workflow.

Personas - 9 endpoint

Elenca, ottieni, visualizza le analytics, crea, aggiorna, elimina, duplica, abilita/disabilita ed elimina in blocco le personas di agente IA.

Run - 11 endpoint

Elenca, ottieni, ottieni per numero (ricerca per runNumber orientata all’uomo per la diagnostica), filtra per workflow o chain, rinomina, elimina, ripristina, elimina in modo permanente, elimina in blocco e avvia nuovi run di workflow. Include campi per la pianificazione di run ricorrenti (scheduledFor, timezone, recurrencePattern), lo stato dei check CI, i dettagli dell’errore, i punteggi di qualità, l’utilizzo dei token e i dettagli di qualità e risultati dei test dei run step.

Issue, Sessioni, Answering Session & Work Chain - 30 endpoint

Operazioni CRUD per le issue (list, get, create, update, delete, link-run, bulk-delete). Gestisci le sessioni di scan delle issue (list, get, rename, delete, restore, permanent-delete, bulk-delete, start). Answering session (list, get, create, update status, delete) e session question (list, review, update assumption). Più le work chain (list, get, get issues, create, delete, start).

Sandbox - 7 endpoint

Elenca, ottieni, visualizza i messaggi, rinomina, elimina, ripristina ed elimina in modo permanente le sandbox.

Learning & Versioni - 19 endpoint

Gestione completa del ciclo di vita per i learning (list, stats, preview, by-sandbox, create, update-status, update-content, delete, restore, permanent-delete, bulk-update-status, bulk-delete) e le learning version (list, get, active, compile, activate, deactivate).

Contesti & Asset - 31 endpoint

Gestisci i contesti (documenti di conoscenza del progetto riutilizzabili con cronologia delle versioni), gli skill (comportamenti di agente riutilizzabili multi-file), i command (comandi IA a file singolo) e gli script (script di automazione eseguibili). Ogni tipo di asset supporta un CRUD completo più workflow di pubblicazione versionati.

Operazioni - 28 endpoint

Notifiche (list, unread-count, mark-read, mark-all-read, dismiss), merging (list, start), analytics (usage, daily-stats, counters), trash (list, restore, permanent-delete), sprint chain (list, get, create, delete), task ricorrenti (list, get, create, update, delete, toggle), branch GitHub (list, delete), pull request (list, trigger merge) ed endpoint inbox/notification in stile REST.

Webhook & Callback

Gestione dei webhook Clerk, endpoint di callback interno Trigger.dev (con un riferimento completo delle operazioni organizzato per dominio), verifica della firma ed eventi di notifica.

Endpoint legacy in sola lettura

I 7 endpoint originali in sola lettura a /api/v1/projects, /api/v1/workflows, /api/v1/runs, /api/v1/runs/detail e /api/v1/learnings rimangono disponibili per la retrocompatibilità. I nuovi endpoint specifici per sezione (ad es., /api/v1/runs/list) forniscono gli stessi dati più operazioni di scrittura e più opzioni di filtraggio.

Discovery OpenAPI

La specifica OpenAPI 3.1 completa è servita in tempo reale a GET /api/v1/openapi.json. Questo endpoint non richiede autenticazione ed è il modo consigliato per gli agenti LLM e il tooling di scoprire ogni endpoint, parametro e forma di risposta senza dover accedere al sito di docs.

curl https://<your-deployment>.convex.site/api/v1/openapi.json

CORS

Tutti gli endpoint /api/v1/* supportano il CORS tramite un handler globale di preflight OPTIONS. Le risposte includono header Access-Control-Allow-Origin: *.

Rate limit

L’API eredita i rate limit della piattaforma Convex. Per integrazioni ad alto throughput, implementa un backoff esponenziale sulle risposte 429. Non ci sono rate limit aggiuntivi per chiave oltre a quelli che Convex applica.