API Reference
This document inventories the currently exposed HTTP API surfaces found in the inspected sources.
It is organized by runtime:
- Orchestrator
- Gateway
- Agent / code-action surface
- MCP informational surface
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:
- FastAPI app in
orchestrator/app.py - default local port
8080
Health
GET /health
Basic orchestrator health endpoint.
GET /v1/harper/health
Harper namespace health endpoint.
Harper control plane
Prefix:
/v1/harper
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:
taskhintmodelprovider
POST /v1/harper/session/clear
Clears Harper chat session state by scope.
Current request model:
scope:singleModel | allModels
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:
cmdphasemodemodelprofileHintexecutionPreferencemethodology,agent,methodology_contextdocRootcoreattachmentsmessagesrunIdhistoryScoperepository_contextflags,genlocalAgentExecutor,localAgentCapabilities,localAgentTimeoutSeconds,localRuntimeidea_mdspec_mdplan_mdkit_mdrelease_notes_mdtelemetrycore_blobsworkspacekit(kit.repair: auto-eval / auto-gate repair request, seeauto-eval.md)evalfinalize_verifyrag_strategycontext_hard_limitproject_idproject_namerag_chunksrag_queriesrag_top_kfiles
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)
POST /v1/applyRemoved 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:
taskhintmodelprovider
RAG API
Prefix:
/v1/rag
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:
profileproject_rootreq_idmodeverdictltcproject_name
Confinement rules (also for /v1/gate/check):
project_rootmust lie underDEV_FOLDER(the host projects dir,CLIKE_PROJECTS_DIRin compose) or under one ofCLIKE_EVAL_ALLOWED_ROOTS(path-separator list); otherwise403. With neither configured, eval/gate are disabled.GET /v1/eval/roots→{roots, stack_dir}: the folders eval reads and where the stack runs from (the extension offersdocker/mount-project.sh).- The LTC is read from the
profilefile under the project root, which is authoritative. An inlineltcis accepted only if identical to that file (409otherwise). An inline-only LTC (no file) is refused (403) unlessCLIKE_ALLOW_INLINE_LTC=1. profilemust stay inside the project root (400on traversal).- Eval commands run without credentials in their environment (API keys,
CLIKE_API_TOKENand any*KEY*/*TOKEN*/*SECRET*/*PASSWORD*-style variables are removed). - In containers the profile is executed by the
eval-sandboxservice (CLIKE_EVAL_SANDBOX_URL); responses carryexecutor: "sandbox" | "local". - Responses carry
missing_tools(catalog programs a check reported missing) andsandbox_exhausted. POST /v1/eval/tools/check{project_root, req_id | profile}→{missing: [{tool, binaries, source: declared | used, about, in_catalog, approved}], approved, installable};POST /v1/eval/tools/install{project_root, tools: ["kafkacat", "jdk@17"]}→ installed programs and versions;GET /v1/eval/tools?project_root=→ catalog (with the project’scustom:entries), installed with versions, approved,updated_days_ago,update_due;POST /v1/eval/tools/update{tools: []}(empty: all) →{updated, changes: {tool: {pkg: [old, new]}}, failed};POST /v1/eval/tools/restore→ rebuilds from the orchestrator’s lock the tools the volume lacks.- Eval and gate responses carry
tools: the versions of the installed eval tools. GET /v1/eval/progress?req_id=&project_root=&project_name=(same confinement) → the live progress of the REQ’s eval or gate in flight:{state: running | done | cancelled, phase: setup | checks | regression | done, checks_total, checks_done, current, passed, failed, regression_total, regression_done, regression_current: [REQ…], partial, started_at, updated_at, ended_at, elapsed_s}, or{state: "unknown"}. Proxied to the eval sandbox’sGET /progresswhen one is configured.- Acceptance integrity: the REQ acceptance surface (
runs/kit/<REQ>/test/**andci/**) is locked server-side the first time it is evaluated after a KIT generation. If files were removed or modified, LTC checks removed/made non-blocking/changed, or skip markers added, eval and gate do not run (reason_codeACCEPTANCE_TAMPERED/GATE_BLOCKED_ACCEPTANCE_TAMPERED). Responses include anintegrityobject (ok,anomalies,added,lock_digest) andintegrity_req_id(the REQ whose surface changed: the candidate or a promoted REQ of its regression). A new/kitre-baselines the lock.POST /v1/acceptance/accept{project_root, req_id, reason, author}(reason ≥ 10 characters, else422) accepts the developer’s edits that weaken nothing into the lock, audited inacceptance_amendments.jsonl→{accepted, rejected: {file: [why]}, audit_id, ok}. /v1/gate/checkrejectsmode=manual(400): use/v1/gate/override.
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:
profileproject_rootmodeverdictreq_idpromoteltcproject_name
Agent code-action API
POST /agent/code
Repository-file oriented AI action endpoint.
Current intent families visible in the route implementation:
docstringrefactortestsfix
Common request fields used by current implementation:
intentpathtextselectionpromptlanguagetemperaturemax_tokensmodel
Gateway API
Base runtime:
- FastAPI app in
gateway/app.py - default local port
8000
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:
modelmessagestemperaturemax_tokensresponse_formattoolstool_choiceprofiletimeoutproviderbase_urlremote_namemax_completion_tokensmode_contract
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:
modelinput
The route enforces:
- non-empty input
- size guard on oversized embedding input
Harper execution
Prefix:
/v1/harper
POST /v1/harper/run
Main Harper execution endpoint on the gateway.
Current request model includes:
composed_messages(required: the phase messages composed by the orchestrator)project_idproject_namecmdphasemodemodelprofileprofileHintdocRootcoreattachmentsmessagesflagsrunIdhistoryScopeidea_mdspec_mdplan_mdtodo_idscore_blobsgenworkspacekitrag_strategycontext_hard_limitrag_chunksrag_queriesrag_top_kin_line_filesrag_files
The gateway route also contains logic for:
- plan JSON derivation
- candidate path enforcement
- RAG retrieval and injection
- telemetry writing
- provider-specific execution
POST /v1/harper/telemetry
Records the telemetry of a local-agent run (usage, API-equivalent cost, model, duration).
Telemetry API
Prefix:
/v1/metrics
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:
- single endpoint:
POST /agent/code - file/path oriented
- code-action oriented
- not Harper-phase oriented
- uses gateway chat under the hood for compatible intents
MCP informational surface
The orchestrator mounts MCP separately from REST.
Mount path:
/mcp
Current exposed tools include:
- capability listing
- health
- model and profile listing
- route resolution
- Harper workflow explanation
- artifact explanation
- document reads
- plan reads
- REQ listing and retrieval
- kit preparation
- RAG search
- run listing and reading
- eval summary reading
- gate decision reading
- status reading
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).