Guida introduttiva (tutorial API in 5 minuti)

Da zero alla prima chiamata API: crea una chiave con scope, invia una richiesta, interpreta la risposta, gestisci gli errori.

5 min letto
quickstarttutorialgetting-started

Questo tutorial ti porta da un progetto CodeCourier nuovo di zecca a un’integrazione API funzionante in cinque minuti. Creerai una chiave API con scope, farai la tua prima richiesta, leggerai l’envelope di risposta e gestirai un errore comune.

1. Crea una chiave API con scope

  1. Accedi al dashboard CodeCourier.
  2. Apri Project Settings → API Keys.
  3. Clicca su Generate New Key.
  4. Chiamala quickstart e seleziona questi scope: projects:read, workflows:read, runs:read.
  5. Copia il secret (mostrato una sola volta - inizia con cc_live_) nel tuo ambiente:
    export CC_KEY="cc_live_..."
export CC_BASE="https://<your-deployment>.convex.site"

Trova <your-deployment> nel dashboard Convex - somiglia a happy-animal-123. Importante: usa .convex.site, non .convex.cloud.

2. Invia la tua prima richiesta

Chiama /whoami per verificare la chiave e ispezionare i suoi scope:

curl

curl "$CC_BASE/api/v1/whoami" \
  -H "Authorization: Bearer $CC_KEY"

TypeScript (fetch)

const base = process.env.CC_BASE!;
const key = process.env.CC_KEY!;

const res = await fetch(`${base}/api/v1/whoami`, {
  headers: { "Authorization": `Bearer ${key}` },
});
const body = await res.json();
console.log(body.data);

Python (requests)

import os, requests

base = os.environ["CC_BASE"]
key = os.environ["CC_KEY"]

r = requests.get(
    f"{base}/api/v1/whoami",
    headers={"Authorization": f"Bearer {key}"},
    timeout=30,
)
r.raise_for_status()
print(r.json()["data"])

3. Interpreta la risposta

Dovresti vedere:

{
  "data": {
    "keyId": "kak_abc123",
    "projectId": "prj_xyz",
    "name": "quickstart",
    "scopes": ["projects:read", "workflows:read", "runs:read"],
    "createdAt": "2025-01-15T10:04:00Z",
    "lastUsedAt": "2025-01-15T10:05:12Z"
  }
}

Ogni risposta riuscita avvolge il payload in { "data": ... }. Le risposte di lista includono inoltre nextCursor e hasMore - vedi Pagination.

4. Elenca i workflow

curl

curl "$CC_BASE/api/v1/workflows?limit=5" \
  -H "Authorization: Bearer $CC_KEY"

TypeScript

const r = await fetch(`${base}/api/v1/workflows?limit=5`, {
  headers: { "Authorization": `Bearer ${key}` },
});
const { data, hasMore, nextCursor } = await r.json();
console.log(`${data.length} workflows, more=${hasMore}`);

Python

r = requests.get(
    f"{base}/api/v1/workflows",
    headers={"Authorization": f"Bearer {key}"},
    params={"limit": 5},
    timeout=30,
)
body = r.json()
print(f"{len(body['data'])} workflows, more={body['hasMore']}")

5. Gestisci gli errori

Prova uno scope che la chiave non ha per vedere l’envelope di errore:

# Attempt to cancel a run - requires runs:cancel (not granted)
curl -X POST "$CC_BASE/api/v1/runs/run_abc/cancel" \
  -H "Authorization: Bearer $CC_KEY"

# HTTP/2 403
# X-Request-ID: 5b2c1f0a-8e7d-4a4f-bb6d-f0a3c8a1e7e2
# {
#   "error": {
#     "code": "SCOPE_DENIED",
#     "message": "This key does not have the required 'runs:cancel' scope.",
#     "requestId": "5b2c1f0a-8e7d-4a4f-bb6d-f0a3c8a1e7e2"
#   }
# }

Correggilo concedendo runs:cancel nel dashboard (o generando una chiave nuova). Vedi Envelope di errore per la tassonomia completa dei codici.

Prossimi passi