HTTP API and OKF source authoring
Beta.2 adds Knowledge Consolidation and indexing resource budgets; see those guides for their complete YAML, API/library contracts and boundaries.
The first beta guide documents the current evidence/publication, operation, scoped-access and runtime contracts. It supplements the compatibility interfaces described below.
The OpenAPI 3.2.1 contract is the machine-readable reference. knowledge openapi prints it without loading a config/models/keys. A running server serves /openapi.json behind the same bearer authentication as its data routes. TLS, host/origin policy, rate limits, resource budgets and read/admin roles apply to every route; see security.
Routes
| Method and route | Role | Purpose |
|---|---|---|
GET /healthz, /v1/status, /v1/bundle |
Read/admin | Health, indexing/jobs, explicit OKF bundle description |
GET /v1/documents?path=..., /v1/graph?from=...&hops=... |
Read/admin | Indexed document/graph with provenance |
POST /v1/search, /v1/context, /v1/ask |
Read/admin | Retrieval, cited context, grounded generation |
POST /v1/admin/reconcile, /v1/admin/retry |
Admin | Reconcile sources, requeue processing |
GET /v1/files?path=...&include_data=false |
Read/admin | Actual source file text/hash; optional base64 for binary assets |
GET /v1/captures?directory=... |
Read/admin | Current app-managed capture files and tree hash |
POST /v1/admin/pages |
Admin | Create/update structured OKF Markdown/YAML |
POST /v1/admin/assets |
Admin | Create/update supported binary/HTML assets |
POST /v1/admin/capture |
Admin | Archive an allowed static web page and optional assets |
DELETE /v1/admin/files?path=...&expected_sha256=... |
Admin | Delete one checked regular source file |
DELETE /v1/admin/capture?directory=...&expected_sha256=... |
Admin | Delete a checked app-managed capture and its content/assets |
Source mutations additionally require server.allow_source_writes: true. It defaults to false in the library config; the shipped knowledge.yml explicitly enables it for the admin credential. URL capture independently requires urls.enabled and an origin allowlist. A read token never gains write access from either setting.
Search and RAG
POST /v1/search
{"query":"sensor calibration","mode":"hybrid","limit":5,"graph_hops":1,"rerank":"mmr","vector_backend":"float32"}
Use lexical, vector or hybrid modes. A representation filter can select native_video_frame, remote_image, etc. MMR/coverage are deterministic rerankers; http selects a configured learned reranker. Context/ask requests nest these settings:
POST /v1/ask
{"search":{"query":"Who owns sensor calibration?","mode":"hybrid","graph_hops":1},"max_chars":6000}
Results expose channel ranks, fusion/reranking details, stage timings, graph evidence, stale state, source versions and chunk locators. Scores are not probabilities. Raw image/audio vectors alone provide no textual answer context. Returned citation IDs are checked; factual quality is still model/corpus dependent.
Create and update a page
POST /v1/admin/pages
{
"path":"procedures/calibration.md",
"content":"# Calibration\n\nThe sensor is calibrated every forty-two days.\n",
"metadata":{
"type":"Procedure",
"title":"Sensor calibration",
"tags":["maintenance"],
"sources":[{"id":"handbook","resource":"/media/handbook.pdf"}],
"relations":[{"predicate":"documented_by","target":"/media/handbook.pdf"}]
}
}
The app serializes metadata as YAML frontmatter and writes the Markdown body. It preserves unknown metadata. Ordinary pages default to type: Note if omitted. Do not supply an additional frontmatter block as content; it is body data. Reserved index.md/log.md have no concept frontmatter; only the bundle-root index may declare okf_version: 0.2. The API enforces these authoring rules; it does not attest the truth of supplied trust/provenance fields or execute referenced computations.
Creates omit expected_sha256 and fail with 409 if the path exists. Updates must include the hash from GET /v1/files; a missing/stale hash is a conflict. Re-read and merge edits before retrying. API operations share a writer lock and atomically rename staged files; this is not a cross-process filesystem compare-and-swap. External editors can still race between the final hash check and rename.
Paths are portable bundle-relative paths: no traversal, absolute/drive paths, hidden components, symlinks, control characters or Windows device names. Parent directories may be created. The writer does not silently rewrite existing navigation indexes or authored links. The root index cannot be deleted via the API.
Upload assets
POST /v1/admin/assets
{"path":"media/handbook.pdf","mime_type":"application/pdf","data_base64":"BASE64_BYTES"}
Use the file's real bytes, not this placeholder. Supported extensions are listed in formats. MIME, when supplied, must match the extension. Markdown concepts use /pages; link uploaded media from a concept using resource, sources and/or body links. The app stores raw bytes in the OKF folder, then the selected decoder/model pipeline processes them. Upload acceptance does not prove a PDF/video is decodable or that models are configured.
server.max_upload_bytes defaults to 33,554,432 decoded bytes. Upload JSON has a separate base64-adjusted body ceiling; ordinary request bodies retain max_body_bytes (default 65,536). The source indexing.max_file_bytes limit also applies. This is bounded whole-body upload, not streaming, resumable or multipart upload. Very large recordings need external staging/conversion or a later streaming adapter.
Archive and delete a web capture
POST /v1/admin/capture
{"directory":"references/sensor-handbook","url":"https://docs.example.com/handbook","title":"Sensor handbook","include_assets":true}
The origin must be explicitly allowed. A successful capture creates a new subfolder containing page.md (valid OKF concept and provenance), index.md, original source.html, allowed media under assets/, and hidden capture bookkeeping. A staged folder is renamed into place only after all selected content is ready. Existing directories are never overwritten. Relative src/poster URLs resolve against the page URL and use the same fetch policy. Disallowed origins/unsupported asset types are skipped with a count. Asset-count/byte/download failures abort publication of the folder; fetched bytes may remain in the SQLite cache.
Capture preserves static readable text, original HTML and explicit media attachments. It does not reproduce a browser-rendered page, execute JavaScript, mirror CSS/fonts/scripts, expand srcset, authenticate into sites or follow redirects. It is not a recursive website downloader. The original HTML and derived page text may both be indexed; MMR can reduce duplicate results. Captures disable automatic URL re-fetch on their generated page so the archive is a snapshot; ordinary URL-derived knowledge has the separate refresh behavior described in formats.
Inspect a capture with GET /v1/captures?directory=references/sensor-handbook. Delete it with that snapshot's SHA-256 via DELETE /v1/admin/capture. A changed tree returns 409. Bulk deletion requires the app's capture marker and refuses symlinks, unknown/hidden files and resource-budget violations. One-file deletion uses /v1/admin/files and its file hash. Other concepts' links may become dangling; they remain preserved as graph references.
Completion and failures
Source mutations return 202 Accepted with source_saved, mutation, indexing and the scan report when available. The response means the source operation committed. Model work is asynchronous: the default watcher drains queued jobs; with server.watch:false, run CLI work or a host-managed worker. Inspect status/the document for completion or failure. A failed scan after a source commit returns indexing: scan_failed; correct the problem and reconcile. HTTP timeouts do not guarantee a source operation was rolled back; inspect the file/hash before retrying.
Deletion removes current source and active index entries on successful reconcile. Historical SQLite source versions, remote versions, caches and external backups remain; deletion is not secure erasure. Capture cleanup failures can leave hidden trash for operator cleanup. There is no automatic history/cache retention policy yet.
Errors include 400 malformed requests, 401 missing/invalid auth, 403 role/policy refusal, 409 version conflicts, 413 body/upload limits, 422 invalid data/configuration, 429 capacity, 502 upstream failure and 504 deadlines. Internal details and credential values are not returned. Request logs include route templates/status/timing, not query/source bodies or tokens.