Skip to content

api_basics.md

Latest commit

 

History

History
266 lines (196 loc) · 5.87 KB

api_basics.md

File metadata and controls

266 lines (196 loc) · 5.87 KB

API Basics

This document covers the most important API fundamentals for v1. It does not replace a complete OpenAPI specification, but it covers current practical usage.

Basics

  • Health: GET /health
  • protected API: /api/*
  • Content-Type: application/json

If CC_API_TOKEN is set, a bearer token must be provided for /api/*:

Authorization: Bearer <token>

Error format

Errors are returned as JSON in this shape:

{
  "error": {
    "statusCode": 404,
    "message": "Repository 99999 not found."
  }
}

Typical status codes:

  • 400: validation error
  • 401: missing or invalid authentication
  • 404: resource not found
  • 409: domain conflict or policy blocker
  • 202: accepted but blocked by open approvals

Core resources

Repositories

Key endpoints:

  • GET /api/repos
  • POST /api/repos
  • GET /api/repos/:id
  • POST /api/repos/inspect
  • POST /api/repos/:id/scan
  • POST /api/repos/:id/worktrees

Example:

POST /api/repos
{
  "name": "codex-command-center",
  "localPath": "C:\\Users\\wecke\\Projects\\codex-command-center",
  "allowWrite": true,
  "allowNetwork": false,
  "allowCommit": false,
  "requireWorktree": false
}

Tasks

Key endpoints:

  • GET /api/tasks
  • POST /api/tasks
  • GET /api/tasks/:id
  • PATCH /api/tasks/:id
  • POST /api/tasks/:id/run
  • POST /api/tasks/:id/policy-check
  • GET /api/tasks/:id/events
  • POST /api/tasks/:id/sessions

Allowed type values:

  • prompt_task
  • review_task
  • repo_health_check
  • investigate_failure

Allowed priority values:

  • low
  • normal
  • high

Example:

POST /api/tasks
{
  "repositoryId": 1,
  "type": "prompt_task",
  "title": "Review the current auth flow",
  "prompt": "Inspect the login flow and summarize the main risks.",
  "priority": "normal",
  "approvalRequired": false,
  "requestedBy": "web"
}

Run example:

POST /api/tasks/42/run
{
  "model": "gpt-5.4",
  "sandbox": "workspace-write",
  "worktreePath": "C:\\worktrees\\cc-review-auth-flow",
  "branchName": "cc/review-auth-flow",
  "allowNetwork": false,
  "allowCommit": false
}

If open approvals are required, the server responds with 202 and a blocked policy result instead of a direct run.

Sessions

Key endpoints:

  • GET /api/sessions
  • GET /api/sessions/:id
  • PATCH /api/sessions/:id
  • POST /api/sessions/:id/stop
  • POST /api/sessions/:id/steer
  • GET /api/sessions/:id/events

Sessions carry the concrete execution state for a task run. Transitions to active states are policy-checked again.

POST /api/sessions/:id/steer requires an active app-server-backed session whose codexRef includes thread and turn ids. It maps the message to app-server turn/steer and records request/acknowledgement events on the session timeline.

Example:

POST /api/sessions/12/steer
{
  "message": "Continue, but use the smaller test fixture.",
  "requestedBy": "mobile-web"
}

Codex App Threads

These endpoints require CC_CODEX_RUNNER_MODE=app-server.

Key endpoints:

  • GET /api/codex/bridge/health
  • GET /api/codex/threads/loaded
  • GET /api/codex/threads?query=<text>&limit=20
  • POST /api/codex/threads/:threadId/prompt

The bridge health endpoint probes thread/loaded/list and returns connected, disabled, or unavailable with the configured command, transport, and a diagnostic message. In proxy transport, Command Center invokes codex app-server proxy to reach the local Codex App control plane. In spawn transport, it starts codex app-server --listen stdio:// as a Command Center-managed app-server process.

The loaded endpoint maps to app-server thread/loaded/list. The stored endpoint maps to thread/list.

Prompting a thread resumes it by default with thread/resume, then starts a new turn with turn/start.

Example:

POST /api/codex/threads/thr_123/prompt
{
  "repositoryId": 1,
  "cwd": "C:\\Users\\wecke\\Projects\\codex-command-center",
  "prompt": "Continue from mobile and check the latest failing test.",
  "resume": true
}

Command Center reuses one local task per Codex thread and creates a new session for each prompted turn. The session codexRef starts with app-server: and includes Codex thread and turn ids for later approvals and steering; sessions without that prefix are Command Center-managed CLI/stub sessions.

Approvals

Key endpoints:

  • GET /api/approvals
  • GET /api/approvals/:id
  • POST /api/approvals
  • POST /api/approvals/:id/resolve

Allowed resolve statuses:

  • approved
  • rejected

Example:

POST /api/approvals/7/resolve
{
  "status": "approved",
  "resolvedBy": "mobile-web",
  "resolutionNote": "Approved from iPhone."
}

Expired approvals cannot be approved retroactively.

Automations

Key endpoints:

  • GET /api/automations
  • POST /api/automations
  • GET /api/automations/:id
  • PATCH /api/automations/:id
  • POST /api/automations/:id/run

Supported scheduleExpr values in v1:

  • hourly
  • hourly:2 through hourly:24
  • daily@09:00

Example:

POST /api/automations
{
  "repositoryId": 1,
  "title": "Morning repo check",
  "scheduleExpr": "daily@09:00",
  "enabled": true,
  "payload": {
    "taskType": "repo_health_check",
    "taskTitle": "Daily health check",
    "prompt": "Inspect the repo state and report unusual failures.",
    "priority": "normal",
    "runInput": {
      "sandbox": "read-only"
    }
  }
}

Events and telemetry

Key endpoints:

  • GET /api/events
  • GET /api/telemetry/summary

These endpoints power the dashboard, timeline, and mobile overviews.

Telegram

Important endpoint:

  • POST /api/telegram/webhook

The webhook is not intended for general clients; it is only for Telegram updates with a matching secret.

Typical flow

  1. Create or inspect a repository.
  2. Create a task.
  3. Optionally run policy-check.
  4. Start the task.
  5. Watch sessions, events, and approvals.
  6. Resolve open approvals via web or Telegram.