Skip to content

HTTP API

The api installation profile supplies an installed loopback-first server for the Runtime v2 application service:

python -m pip install 'bijux-canon-runtime[api]'
bijux-canon-runtime init --workspace ./canon-workspace --json
bijux-canon-runtime-server --workspace ./canon-workspace

The default bind is 127.0.0.1:8000. Use --host, --port, --log-level, and --no-access-log deliberately when the surrounding deployment supplies its own authentication, authorization, isolation, and request limits. The Runtime server does not provide those controls.

Every v2 request must send Bijux-API-Version: v2. Durable workflow submissions also require an Idempotency-Key of 16 to 200 characters. The response header Bijux-API-Supported-Versions: v2 identifies the supported contract.

Probe The Installed Service

curl --fail-with-body \
  -H 'Bijux-API-Version: v2' \
  http://127.0.0.1:8000/api/v2/live

curl --fail-with-body \
  -H 'Bijux-API-Version: v2' \
  'http://127.0.0.1:8000/api/v2/ready?operation=initialized'

curl --fail-with-body \
  -H 'Bijux-API-Version: v2' \
  http://127.0.0.1:8000/api/v2/capabilities

Liveness proves that the process can answer. Readiness evaluates the requested capability and optional execution profile against the effective workspace. Capability discovery reports configuration identities, installed support, requirements, and remediation without returning credential values.

Implemented V2 Surface

The service composes the same application layer as the Python and CLI adapters:

Operation HTTP route
prepare and inspect a corpus POST /api/v2/corpora/prepare, GET /api/v2/corpora/{corpus_id}
build and inspect an index POST /api/v2/indexes/build, GET /api/v2/indexes/{index_id}
retrieve evidence POST /api/v2/retrievals
answer and research POST /api/v2/answers, POST /api/v2/research
run the linked workflow POST /api/v2/runs
inspect and replay a run GET /api/v2/runs/{run_id}, POST /api/v2/runs/{run_id}/replays
inspect, wait for, resolve, or cancel a job /api/v2/jobs/{job_id} and child routes
compare attempts POST /api/v2/comparisons
page immutable payload bytes GET /api/v2/artifacts/{artifact_id}/payload
evaluate reviewed retrieval cases POST /api/v2/retrieval-evaluations

Submissions return bounded durable job-status documents. Resolve completed results through the job result route. Inspection, comparison, index segments, and artifact payload bytes use explicit limits and opaque continuation cursors. Backup and restore remain local CLI operations because they require direct filesystem authority over a quiescent workspace.

The pinned OpenAPI document and migration policy are under apis/bijux-canon-runtime/v2/. Route behavior, generated OpenAPI, its pin, and the schema hash must agree.

Errors And Correlation

Failures use application/problem+json and the shared Runtime problem fields: code, title, status, retryability, remediation, bounded cause, correlation ID, and optional run ID. Supply X-Correlation-ID, or a request context correlation identity where the schema supports one. Unsupported versions return 406 and the supported-version response header. Validation, not-found, conflict, capability, and operation failures retain distinct typed codes.

V1 Compatibility Status

The installed server command serves v2 only. It does not mount the older v1 application. bijux_canon_runtime.api.v1.app:app remains importable for callers that explicitly host that compatibility module. Its health and readiness probes are implemented, while POST /api/v1/flows/run and POST /api/v1/flows/replay validate their legacy envelopes and then return 501 Not Implemented. A v1 schema or import is not evidence of an executable v1 workflow.