Erste Schritte (5-Minuten-API-Tutorial)

Von null zum ersten API-Aufruf: einen scoped Key erstellen, eine Anfrage senden, die Antwort interpretieren, Fehler behandeln.

5 Min. Lesezeit
quickstarttutorialgetting-started

Dieses Tutorial führt Sie in fünf Minuten von einem frischen CodeCourier-Projekt zu einer funktionierenden API-Integration. Sie erstellen einen scoped API-Key, senden Ihre erste Anfrage, lesen den Response-Envelope und behandeln einen typischen Fehler.

1. Scoped API-Key erstellen

  1. Melden Sie sich im CodeCourier-Dashboard an.
  2. Öffnen Sie Projekteinstellungen → API-Keys.
  3. Klicken Sie auf Neuen Key generieren.
  4. Nennen Sie ihn quickstart und wählen Sie diese Scopes: projects:read, workflows:read, runs:read.
  5. Kopieren Sie das Secret (wird nur einmal angezeigt - beginnt mit cc_live_) in Ihre Umgebung:
    export CC_KEY="cc_live_..."
export CC_BASE="https://<your-deployment>.convex.site"

Sie finden <your-deployment> im Convex-Dashboard - es sieht aus wie happy-animal-123. Wichtig: verwenden Sie .convex.site, nicht .convex.cloud.

2. Erste Anfrage senden

Rufen Sie /whoami auf, um den Key zu verifizieren und die Scopes zu prüfen:

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. Antwort interpretieren

Sie sollten Folgendes sehen:

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

Jede erfolgreiche Antwort verpackt die Payload in { "data": ... }. Listenantworten enthalten zusätzlich nextCursor und hasMore - siehe Paginierung.

4. Workflows auflisten

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. Fehler behandeln

Probieren Sie einen Scope, den der Key nicht hat, um den Error-Envelope zu sehen:

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

Beheben Sie es, indem Sie runs:cancel im Dashboard vergeben (oder einen neuen Key erzeugen). Siehe Error-Envelope für die vollständige Code-Taxonomie.

Nächste Schritte