API Overview

The CodeCourier REST API provides full programmatic access to every feature available in the web dashboard. With 171 endpoints across 26 resource categories, an LLM or automation script can do everything a human can do -- create projects, configure workflows, launch AI coding runs, manage learnings, configure contexts and assets, schedule recurring tasks, and more. All endpoints are authenticated via project-scoped API keys and return consistent JSON responses.

Base URL

All REST API endpoints are served from your Convex deployment's HTTP Actions URL under the /api/v1/ prefix:

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

Important: The base URL ends in .convex.site -- NOT .convex.cloud. The .convex.cloud domain is the Convex data WebSocket URL used internally. The .convex.site domain is the HTTP Actions endpoint that serves the REST API. Using the wrong domain will result in connection failures.

You can find your deployment name in the Convex dashboard. It typically looks like happy-animal-123, giving you a base URL of: https://happy-animal-123.convex.site/api/v1/

Authentication

Every request requires a project API key passed as a Bearer token in the Authorization header. Keys are generated through the dashboard or via the API itself. See the Authentication page for full details on creating and managing keys.

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

Important: The header is Authorization: Bearer <key> -- NOT x-api-key, NOT X-API-Key. API keys start with cc_live_ (production) or cc_test_ (test environments).

Response Format

All successful responses return:

{ "data": <result> }

All error responses return:

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

Standard HTTP status codes:

• 200 -- Success
• 201 -- Created (for action endpoints like start)
• 400 -- Bad request (missing fields, invalid JSON)
• 403 -- Forbidden (invalid or revoked API key)
• 404 -- Resource not found
• 500 -- Internal server error

Resource IDs: id vs _id

Every resource returned by the REST API exposes its canonical identifier under two field names: id (REST convention) and _id (Convex internal alias, retained for back-compat). Both hold the same opaque string and can be passed interchangeably to any endpoint that accepts an ID.

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

New integrations should read id. The _id field is retained on every projection through the v1 envelope sunset on 2026-10-24; after that date it may be removed from REST responses without further notice. Convex internal queries are unaffected - _id remains the document field name in the database.

Quick Start: Start a Run and Get Its Output

Here is the minimal sequence an agent or script needs to start a run and retrieve the full AI conversation output:

Step 1 - Get a workflow ID

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

Step 2 - Start a 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" } }

Note: githubRepoUrl is required in practice. Without it the sandbox has no project code to work with and git operations fail immediately with exit status 128.

Step 3 - Wait, then list runs to get the 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", ... }] }

Step 4 - Get sandbox IDs for the 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", ... }] }

Step 5 - Get the full conversation output

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

Why not use /api/v1/runs/detail? That endpoint returns run metadata and execution steps, but NOT the AI conversation text. The actual agent output lives in the sandbox messages.

API Sections

The API is organized into the following sections. Each is documented in detail on its own page:

Project Management -- 16 endpoints

Read, update, and delete your project. Manage project settings (system prompts, env vars, git config), team members (invite, remove, update roles), provider API keys (E2B, Anthropic, GitHub, etc.), project API keys (generate, revoke), and view project counters.

Workflows -- 10 endpoints

List, get, create, update, delete, restore, permanently delete, duplicate, rename, and bulk-delete workflow blueprints.

Personas -- 9 endpoints

List, get, view analytics, create, update, delete, duplicate, toggle enable/disable, and bulk-delete AI agent personas.

Runs -- 11 endpoints

List, get, get-by-number (human-facing runNumber lookup for diagnostics), filter by workflow or chain, rename, delete, restore, permanently delete, bulk-delete, and start new workflow runs. Includes fields for recurring run scheduling (scheduledFor, timezone, recurrencePattern), CI check status, error details, quality scores, token usage, and run step quality and test result details.

Issues, Sessions, Answering Sessions & Work Chains -- 30 endpoints

CRUD operations for issues (list, get, create, update, delete, link-run, bulk-delete). Manage issue scanning sessions (list, get, rename, delete, restore, permanent-delete, bulk-delete, start). Answering sessions (list, get, create, update status, delete) and session questions (list, review, update assumption). Plus work chains (list, get, get issues, create, delete, start).

Sandboxes -- 7 endpoints

List, get, view messages, rename, delete, restore, and permanently delete sandboxes.

Learnings & Versions -- 19 endpoints

Full lifecycle management for learnings (list, stats, preview, by-sandbox, create, update-status, update-content, delete, restore, permanent-delete, bulk-update-status, bulk-delete) and learning versions (list, get, active, compile, activate, deactivate).

Contexts & Assets -- 31 endpoints

Manage contexts (reusable project knowledge documents with version history), skills (multi-file reusable agent behaviors), commands (single-file AI commands), and scripts (executable automation scripts). Each asset type supports full CRUD plus versioned publish workflows.

Operations -- 28 endpoints

Notifications (list, unread-count, mark-read, mark-all-read, dismiss), merging (list, start), analytics (usage, daily-stats, counters), trash (list, restore, permanent-delete), sprint chains (list, get, create, delete), recurring tasks (list, get, create, update, delete, toggle), GitHub branches (list, delete), pull requests (list, trigger merge), and inbox/notification REST-style endpoints.

Webhooks & Callbacks

Clerk webhook handling, Trigger.dev internal callback endpoint (with complete operation reference organized by domain), signature verification, and notification events.

Legacy Read-Only Endpoints

The original 7 read-only endpoints at /api/v1/projects, /api/v1/workflows, /api/v1/runs, /api/v1/runs/detail, and /api/v1/learnings remain available for backward compatibility. The new section-specific endpoints (e.g., /api/v1/runs/list) provide the same data plus write operations and more filtering options.

OpenAPI Discovery

The full OpenAPI 3.1 specification is served live at GET /api/v1/openapi.json. This endpoint requires no authentication and is the recommended way for LLM agents and tooling to discover every endpoint, parameter, and response shape without having to access the docs site.

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

CORS

All /api/v1/* endpoints support CORS via a global OPTIONS preflight handler. Responses include Access-Control-Allow-Origin: * headers.

Rate Limits

The API inherits Convex platform rate limits. For high-throughput integrations, implement exponential backoff on 429 responses. There are no additional per-key rate limits beyond what Convex enforces.