kontextual-engine/docs/service-api-boundary.md

Service API Boundary

Date: 2026-05-05

Decision

The first service boundary will be an optional FastAPI layer over the programmatic contracts implemented in kontextual_engine. The service must not define separate business behavior; it should expose the same artifact, collection, relationship, ingestion, query, workflow, and context operations as HTTP resources.

First Resource Shape

Planned endpoint groups:

• GET /health
• POST /collections, GET /collections, GET /collections/{id}
• POST /artifacts, GET /artifacts/{id}, GET /artifacts
• POST /relationships, GET /relationships
• POST /ingest
• POST /query/artifacts, POST /query/relationships
• POST /runs, GET /runs/{id}, GET /runs/{id}/manifest
• POST /context/artifact/{id}

Rules

• The Python API is canonical until contracts stabilize.
• HTTP handlers must translate request/response envelopes only.
• Markdown parsing, document transforms, selectors, contracts, and local indexes must remain adapter calls to markitect-tool.
• Provider calls must remain adapter calls to llm-connect.
• Structured diagnostics and errors must be preserved in responses.

Deferred

• Authentication and authorization.
• Durable database backend.
• OpenAPI model polishing.
• Streaming run execution.
• Provider-backed assisted steps.