REST API

Action API

Reduce action results over HTTPS and read contentless usage and savings.

The action API is what the CLI and SDKs speak. Base URL https://api.codag.ai, authenticated with Authorization: Bearer <token> using a workspace API key (cdk_ prefix). You do not need this API to use Codag with Claude Code or Codex; codag setup covers that. It exists for harnesses, CI systems, and backends that embed reduction directly.

Endpoints

POST /v1/actions/reduce: reduce one action result. Never returns or retains the original.
POST /v1/metrics/batch: submit contentless accounting events.
GET /v1/usage/summary, /v1/usage/timeseries, /v1/usage/breakdown, /v1/usage/reliability: workspace usage, savings estimates, and reliability.
GET /v1/trials/report: trial savings report.
GET /v1/model-prices: the public model price catalog used for dollar estimates.
GET/PUT /v1/workspace/policy: workspace policy (enabled action classes, mode, version pinning).
GET /v1/service/status: service status. GET /health is unauthenticated.

Reduce an action

Send the tool call, its raw result, and the action kind. The response is either a reduction or an explicit passthrough.

# POST /v1/actions/reduce
# Authorization: Bearer cdk_...
{
  "id": "act_01",
  "kind": "test_build_lint",
  "tool": { "name": "bash", "arguments": { "command": "npm test" } },
  "result": "<the full tool output, up to 32 MiB>",
  "task": "Fix the failing checkout tests",
  "harness": "claude-code"
}
                        

{
  "action_id": "act_01",
  "kind": "test_build_lint",
  "decision": "reduced",
  "content": "<the evidence your agent reads>",
  "selectors": [
    { "id": "s1", "type": "lines", "label": "passing suites", "start": 1, "end": 412 }
  ],
  "usage": { "bytes_in": 183204, "bytes_out": 2114, "elapsed_ms": 640 }
}
                        

Notes on the contract:

kind is one of log, test_build_lint, search, file_list, document_read, agent_handoff, query, verbatim, or unknown.
decision is reduced or passthrough. Unknown kinds, validation failures, and internal errors return passthrough with a reason instead of an error status. The original is never stored.
selectors describe the omitted sections by line range, JSON path, or group so a client that kept the original can retrieve exact slices locally. The CLI's local service does this for attached agents.
Money fields across the API are integers in microUSD and are estimates derived from the public model price catalog.

The full contract is published as OpenAPI in the codag-sdk repository.