Getting Started (5-Minute API Tutorial)

From zero to first API call: create a scoped key, send a request, interpret the response, handle errors.

5 min read
quickstarttutorialgetting-started

This tutorial takes you from a fresh CodeCourier project to a working API integration in five minutes. You will create a scoped API key, make your first request, read the response envelope, and handle a common error.

1. Create a Scoped API Key

  1. Sign in to the CodeCourier dashboard.
  2. Open Project Settings → API Keys.
  3. Click Generate New Key.
  4. Name it quickstart and select these scopes: projects:read, workflows:read, runs:read.
  5. Copy the secret (shown once - starts with cc_live_) to your environment:
    export CC_KEY="cc_live_..."
export CC_BASE="https://<your-deployment>.convex.site"

Find <your-deployment> in the Convex dashboard - it looks like happy-animal-123. Important: use .convex.site, not .convex.cloud.

2. Send Your First Request

Call /whoami to verify the key and inspect its 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. Interpret the Response

You should see:

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

Every successful response wraps the payload in { "data": ... }. List responses additionally include nextCursor and hasMore - see Pagination.

4. List 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. Handle Errors

Try a scope the key lacks to see the error envelope:

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

Fix it by granting runs:cancel in the dashboard (or generate a fresh key). See Error envelope for the full code taxonomy.

Next Steps