Skip to the content.

API Reference

This document inventories the currently exposed HTTP API surfaces found in the inspected sources.

It is organized by runtime:

Authentication

All orchestrator and gateway endpoints except GET /health require Authorization: Bearer <CLIKE_API_TOKEN>. Missing or wrong token → 401; token not configured on the server → 503; unexpected Host header → 403. No CORS headers are emitted. The gateway telemetry API also accepts the clike_token cookie set by POST /v1/metrics/login (GET only).

Orchestrator API

Base runtime:

Health

GET /health

Basic orchestrator health endpoint.

GET /v1/harper/health

Harper namespace health endpoint.

Harper control plane

Prefix:

GET /v1/harper/version

Returns orchestrator version info.

GET /v1/harper/models

Returns model list from loaded config.

GET /v1/harper/models/defaults

Returns default model/profile values for Harper UX.

GET /v1/harper/profiles

Returns available profile names.

GET /v1/harper/routing/resolve

Returns routing choice for a Harper task.

Query parameters used by current code:

POST /v1/harper/session/clear

Clears Harper chat session state by scope.

Current request model:

GET /v1/harper/runs/{run_id}

Returns run bundle information for a given run ID.

POST /v1/harper/idea

Runs IDEA phase.

POST /v1/harper/spec

Runs SPEC phase.

POST /v1/harper/plan

Runs PLAN phase.

POST /v1/harper/kit

Runs KIT phase.

POST /v1/harper/finalize

Runs FINALIZE phase (with finalize_verify: the solution eval profile, the REQs’ eval profiles and a verification repair).

POST /v1/harper/extend

Runs EXTEND phase: /extend (append REQs to the plan) and /idea --extend (release cascade: IDEA, SPEC, TECH_CONSTRAINTS merged, PLAN delta). Options in gen (anchorReq, explicitReq, rawInput).

POST /v1/harper/eval

Prepares the optional local-agent /eval pre-pass package; never a verdict (the canonical eval is POST /v1/eval/run).

POST /v1/harper/local-agent/complete

Normalizes a local-agent result (stdout/stderr/exit code and produced files) and validates its write roots.

Current request model used by these phase endpoints:

Legacy / generic orchestrator APIs

GET /v1/models

Lists models from legacy orchestrator surface.

POST /v1/chat

Legacy chat endpoint used by extension and helper flows.

POST /v1/generate

Legacy generation endpoint for coding / harper style generation.

POST /v1/apply (removed)

Removed in the 2026-10 hardening: it wrote request-supplied files to arbitrary paths. The VS Code extension applies generated files locally (it is the only workspace writer).

Router API

GET /v1/router/resolve

Shared routing resolution endpoint.

Current query parameters:

RAG API

Prefix:

POST /v1/rag/fetch

Fetches RAG materials by query/path strategy.

POST /v1/rag/fetch_by_paths

Fetches docs directly by paths.

POST /v1/rag/reindex

Reindexes repository materials.

POST /v1/rag/index

Indexes repository or provided files into RAG.

POST /v1/rag/search

Searches indexed RAG materials.

POST /v1/rag/purge

Purges RAG documents by project and path prefix, or, with paths: [...], every chunk of those exact paths.

POST /v1/rag/sources

Lists every indexed path of a project with its chunk count ({ project_id } → { ok, sources: [{ path, chunks }], total_chunks }); an unreachable store returns ok: false.

Eval / gate API

POST /v1/eval/run

Runs eval against REQ-scoped candidate artifacts.

Current request fields accepted by the request model and query merge logic include:

Confinement rules (also for /v1/gate/check):

POST /v1/gate/override

Developer override of a gate. Body: project_root, project_name, req_id, reason (≥ 10 characters), author. The project root is confined like eval/gate. The override is appended to an audit log (CLIKE_STATE_DIR/audit/gate_overrides.jsonl) with a digest of the REQ artifacts and returned with status: "OVERRIDE" (never PASS), gate: "pass" (promotable) and an override object (audit_id, author, reason, at, artifacts).

POST /v1/acceptance/lock

Acceptance-first KIT: lock the tests and eval profile written by the acceptance stage before the code KIT runs. Body: {project_root|project_name, req_id} → {files, digest, generation}.

POST /v1/acceptance/amend

Govern acceptance files a local agent changed during a repair or a code-only KIT. Body: {project_root|project_name, req_id, changes: {path: content}, previous: {path: content}, evidence, reason} → {accepted, rejected: {path: [reasons]}, test_fixes, audit_id}. Rejected files must be restored by the caller.

Eval/gate body fields: regression: true (re-run the checks of promoted REQs), strict: true (gate only: warnings block).

POST /v1/gate/check

Runs gate checks and promotion decisions.

Current request fields include:

Agent code-action API

POST /agent/code

Repository-file oriented AI action endpoint.

Current intent families visible in the route implementation:

Common request fields used by current implementation:

Gateway API

Base runtime:

Health

GET /health

Basic gateway health endpoint.

Model catalog

GET /v1/models

Returns model catalog with alias-aware information.

GET /v1/models/validate

Returns model catalog validation information.

GET /v1/providers

Returns which providers are configured.

Chat and completions

POST /v1/chat/completions

Main provider-routed chat endpoint.

Current request model includes:

Embeddings

POST /v1/embeddings

Embeddings endpoint for provider-routed embedding requests; input may be a list (one vector per item, one provider call).

Current request body is request-json driven and includes:

The route enforces:

Harper execution

Prefix:

POST /v1/harper/run

Main Harper execution endpoint on the gateway.

Current request model includes:

The gateway route also contains logic for:

POST /v1/harper/telemetry

Records the telemetry of a local-agent run (usage, API-equivalent cost, model, duration).

Telemetry API

Prefix:

GET /v1/metrics/harper/files

Lists telemetry files.

GET /v1/metrics/harper/projects

Lists projects found in telemetry data.

GET /v1/metrics/harper/aggregate

Aggregate telemetry view.

GET /v1/metrics/harper/series

Series telemetry view.

GET /v1/metrics/harper/top

Top-file or top-project style telemetry view.

GET /v1/metrics/harper/raw

Raw telemetry view.

GET /v1/metrics/harper/aggregate_file

Aggregate-by-file view.

GET /v1/metrics/harper/series_file

Series-by-file view.

GET /v1/metrics/harper/top_file

Top-by-file view.

GET /v1/metrics/harper/raw_file

Raw-by-file view.

Telemetry UI

GET /v1/metrics/harper/ui

Serves HTML telemetry UI.

POST /v1/metrics/login, POST /v1/metrics/logout

Telemetry UI login with the service token (HttpOnly cookie) and logout.

Agent surface summary

Although the agent route lives in the orchestrator runtime, it is conceptually its own file-oriented API surface.

Current characteristics:

MCP informational surface

The orchestrator mounts MCP separately from REST.

Mount path:

Current exposed tools include:

The orchestrator MCP is read-only and should not be treated as a writable or phase-executing API. Phases, eval_run and gate_check are exposed by the VS Code extension MCP server (see mcp.md).