API Contract

CORE's HTTP API is the boundary that core (core-cli) and any other client builds against. Its contract is published as an OpenAPI document.

Machine-readable contract	openapi.json — committed in the CORE repository, regenerated by core-admin docs generate --write
Served live by a running CORE	GET /v1/openapi.json, browsable at /docs
Base URL	http://127.0.0.1:8000 by default; clients read CORE_API_URL

No authentication

The open-source API runs in trusted-localhost mode: it binds to loopback and accepts every request. Routes marked governor-only are not protected by any credential. Anyone who can reach the API can approve and execute proposals. Keep it on 127.0.0.1.

What is in the contract

Only public routes appear in the OpenAPI document. Internal routes — the CORE installation's own machinery (daemon control, vector and database sync, CI gate dispatch) — are reachable but absent from it, and can change in any release.

Public routes cover the operations a user runs on the repository CORE governs — audits, checks, fixes, the proposal lifecycle, the assisted-remediation lane, onboarding, read-only inspection — and the read and management surfaces that dashboards and other integrations use. Which public routes the core CLI wraps is in the core reference; every public route is in the contract.

Stability

The contract follows ADR-087:

• The /v1/ prefix is the major version. Breaking changes to a public route — removing it, renaming a field, narrowing what it accepts — happen only at /v2/.
• Additive changes (new routes, new optional fields) can land in any release.
• A public route is deprecated before it is removed: it carries deprecated: true in the contract and answers with Deprecation and Sunset headers (RFC 9745, RFC 8594). It keeps working unchanged for at least six months.
• The document's info.version is the core-runtime version that produced it.

Deprecated routes

Route	Deprecated	Sunset	Use instead
POST /v1/project/docs	2026-10-03	2027-04-03	core-admin docs generate