Prise en main (tutoriel API en 5 minutes)

De zéro au premier appel API : créez une clé à scope, envoyez une requête, interprétez la réponse, gérez les erreurs.

5 min lire
quickstarttutorialgetting-started

Ce tutoriel vous mène d’un projet CodeCourier tout neuf à une intégration API fonctionnelle en cinq minutes. Vous créerez une clé API à scope, ferez votre première requête, lirez l’enveloppe de réponse et gérerez une erreur courante.

1. Créer une clé API à scope

  1. Connectez-vous au dashboard CodeCourier.
  2. Ouvrez Project Settings → API Keys.
  3. Cliquez sur Generate New Key.
  4. Nommez-la quickstart et sélectionnez ces scopes : projects:read, workflows:read, runs:read.
  5. Copiez le secret (affiché une seule fois - commence par cc_live_) dans votre environnement :
    export CC_KEY="cc_live_..."
export CC_BASE="https://<your-deployment>.convex.site"

Trouvez <your-deployment> dans le dashboard Convex - il ressemble à happy-animal-123. Important : utilisez .convex.site, pas .convex.cloud.

2. Envoyer votre première requête

Appelez /whoami pour vérifier la clé et inspecter ses scopes :

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. Interpréter la réponse

Vous devriez voir :

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

Chaque réponse réussie enveloppe la charge utile dans { "data": ... }. Les réponses de liste incluent en outre nextCursor et hasMore - voir Pagination.

4. Lister les workflows

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. Gérer les erreurs

Essayez un scope que la clé ne possède pas pour voir l’enveloppe d’erreur :

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

Corrigez-le en accordant runs:cancel dans le dashboard (ou en générant une nouvelle clé). Voir Enveloppe d’erreur pour la taxonomie complète des codes.

Prochaines étapes