HTTP API
The CLI, TUI, and web UI use the service HTTP API for project operations; live updates use WebSocket /ws. Local configuration, filesystem and service-management actions also happen outside the API. The machine-readable HTTP contract is the OpenAPI 3.1 specification:
- From a running service:
GET /v1/openapi.yaml(always describes exactly the build it came from) - In the repository:
docs/api/openapi.yaml
A contract test keeps the specification's path inventory in sync with the router in both directions, so it cannot silently drift from the code.
Base URL and authentication
The service listens on localhost only by default (127.0.0.1:4040 native,
localhost:4040 in the Docker stack). In the default single_user mode,
clients use the installation token. In multi_user mode, non-browser clients
use a scoped Codifix service token:
curl -s http://127.0.0.1:4040/v1/query \
-H "Authorization: Bearer $CODIFIX_CLIENT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"project": "demo", "query": "How does reinforcement work?"}'The bundled browser UI uses an Authentik-backed HttpOnly session plus CSRF
protection in multi-user mode. 401 means authentication failed; 403 means
the principal is valid but lacks the required role or project. Read
Authentication and access for configuration,
roles, token lifecycle, and migration.
API version and stability
The /v1 prefix is the HTTP API namespace; it is not the Codifix product
release number. The current source workspace declares 3.0.0; packaged
builds with that version may precede later source increments. Fetch the
specification from the selected service when upgrading a direct integration.
Every operation in the spec carries an x-stability marker:
core— the supported integration boundary documented by that build. Additive fields may appear, and clients must ignore unknown fields.internal— the service control plane (loops, watchers, agent workspaces, admin, embeddings management). Used by the bundled UIs; may change between minor versions.
For the Memory Layer-to-Codifix cutover and package boundaries, read the Update guide. Historical route changes belong to their original release notes.
Core endpoints
| Endpoint | What it does |
|---|---|
POST /v1/query | Query one project's memory: hybrid retrieval plus a cited, synthesized answer — or an honest refusal (insufficient_evidence). |
POST /v1/query/global | The same across every project. |
POST /v1/capture/task | Capture completed work — the HTTP write entry point, optionally with pre-distilled structured_candidates. The CLI spelling is codifix capture. |
POST /v1/curate | Curate raw captures into canonical memories. |
GET /v1/memory/{id} | One memory with tags, sources, relations, and scores. |
GET /v1/memory/{id}/history | Full version history, including tombstones. |
GET /v1/projects/{slug}/memories | List a project's canonical memories. |
GET /v1/projects/{slug}/memory-graph | Memory/source nodes with provenance and relation edges, plus decayed ACT-R activation per memory. |
GET /v1/projects/{slug}/overview | Counts, watchers, recent activity. |
POST /v1/projects/{slug}/resume | Resume briefing for project re-entry. |
GET /v1/projects/{slug}/activities | The activity timeline. |
POST /v1/provenance/verify | Verify source provenance against the filesystem. |
POST /v1/projects/{slug}/bundle/export · import | Shareable, privacy-safe codifix bundles (with /preview variants). |
GET /healthz | Health probe. |
Capture requests still require writer_id as an advisory activity label, but
the service derives durable authorship and permissions from the authenticated principal.
Changing the label does not impersonate another principal or grant access.
A five-line integration
import requests
BASE, TOKEN = "http://127.0.0.1:4040", "<your Codifix service token>"
r = requests.post(f"{BASE}/v1/query", json={"project": "demo", "query": "How does auth work?"},
headers={"Authorization": f"Bearer {TOKEN}"})
print(r.json()["answer"], r.json()["answer_citations"])Typed Python and TypeScript clients generated from the spec are on the roadmap.
Related
- Authentication and access · Environment variables · Global config
- MCP server — ordinary memory reads plus separately gated control-plane and expertise tools over the Model Context Protocol.
- Glossary — the concepts the API speaks in.