# Service API Boundary

Date: 2026-05-06

## 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.

## Implemented MVP Resource Shape

Implemented in `KONT-WP-0009-T001`:

- `GET /health`
- `GET /ready`
- `GET /version`
- `GET /api/v1/health`
- `GET /api/v1/ready`
- `GET /api/v1/version`
- `GET /openapi.json`

Implemented in `KONT-WP-0009-T002`:

- `POST /api/v1/assets`
- `GET /api/v1/assets`
- `GET /api/v1/assets/{asset_id}`
- `POST /api/v1/assets/{asset_id}/metadata`
- `GET /api/v1/assets/{asset_id}/metadata`
- `POST /api/v1/assets/{asset_id}/lifecycle`
- `POST /api/v1/relationships`
- `GET /api/v1/relationships`
- `GET /api/v1/audit/events`
- `POST /api/v1/policy/evaluate`

Implemented in `KONT-WP-0009-T003`:

- `GET /api/v1/ingestion/capabilities`
- `POST /api/v1/ingestion/jobs`
- `GET /api/v1/ingestion/jobs`
- `GET /api/v1/ingestion/jobs/{job_id}`
- `POST /api/v1/retrieval/index/refresh`
- `POST /api/v1/retrieval/assets`
- `POST /api/v1/retrieval/context-entities`
- `POST /api/v1/retrieval/relationships`
- `POST /api/v1/retrieval/feedback`
- `GET /api/v1/retrieval/feedback`
- `GET /api/v1/retrieval/quality`
- `GET /api/v1/transformations/operations`
- `POST /api/v1/transformations/runs`
- `GET /api/v1/transformations/runs`
- `GET /api/v1/transformations/runs/{run_id}`
- `POST /api/v1/transformations/runs/{run_id}/retry`
- `POST /api/v1/transformations/runs/{run_id}/cancel`
- `POST /api/v1/workflows/templates`
- `GET /api/v1/workflows/templates`
- `GET /api/v1/workflows/templates/{template_id}`
- `POST /api/v1/workflows/runs`
- `POST /api/v1/workflows/runs/queue`
- `GET /api/v1/workflows/runs`
- `GET /api/v1/workflows/runs/{run_id}`
- `POST /api/v1/workflows/runs/{run_id}/resume`
- `POST /api/v1/workflows/runs/{run_id}/retry`
- `POST /api/v1/workflows/runs/{run_id}/cancel`
- `GET /api/v1/workflows/runs/{run_id}/reconstruction`
- `GET /api/v1/workflows/reviews`
- `GET /api/v1/workflows/exceptions`
- `POST /api/v1/workflows/runs/{run_id}/reviews/{review_id}/decision`

Implemented in `KONT-WP-0009-T004`:

- `GET /api/v1/context`
- Actor headers: `X-Actor-Id`, `X-Actor-Type`, `X-Actor-Display-Name`,
  `X-Actor-External-Ref`, `X-Actor-Groups`.
- Delegation headers: `X-Delegated-Actor-Id`, `X-Delegated-Actor-Type`,
  `X-Delegated-Actor-Display-Name`, `X-Delegated-Actor-External-Ref`,
  `X-Delegated-Actor-Groups`.
- Agent headers: `X-Agent-Id`, `X-Agent-Name`, `X-Agent-Run-Id`,
  `X-Agent-Tool`.
- Scope headers: `X-Request-Scope` and `X-Policy-Scope` as JSON objects.
- Redacted HTTP authorization error payloads.

Implemented in `KONT-WP-0009-T005`:

- `GET /api/v1/agents/operations`
- `GET /api/v1/agents/operations/{operation_id}`
- `POST /api/v1/agents/operations/{operation_id}`
- Catalog entries declare input/output shape notes, permissions, audit
  operation, failure modes, and dry-run support.
- Execution is limited to documented operation IDs and emits separate
  `agent.operation.*` audit events before dispatching through existing service
  contracts.

Implemented in `KONT-WP-0009-T006`:

- `GET /api/v1/context-packages/schema`
- `POST /api/v1/context-packages`
- Context packages are assembled from governed retrieval results.
- Payloads carry source refs, snippets, metadata, relationships, policy
  constraints, opaque external memory refs, and audit/policy references.
- The `markitect` format emits a Markitect-compatible envelope while keeping
  markdown rendering and selector semantics delegated to `markitect-tool`.

Implemented in `KONT-WP-0009-T007`:

- Agent operation policies can return `require_review` and receive structured
  `review_required` envelopes with review obligations.
- Agent operation policies can return `dry_run_only` and receive
  `dry_run_required` envelopes unless the request is already a dry run.
- Review and dry-run outcomes are audited with explicit `review_required` and
  `dry_run` audit outcomes.
- Partial-failure job envelopes are covered by contract tests.

Implemented in `KONT-WP-0010`:

- `GET /api/v1/operations/metrics`
- `GET /api/v1/operations/jobs`
- `GET /api/v1/operations/events`
- `GET /api/v1/operations/recovery/actions`
- `POST /api/v1/operations/recovery/{action}`
- `POST /api/v1/exports`
- `POST /api/v1/exports/validate`
- `POST /api/v1/governance/report`
- `GET /api/v1/extensions/catalog`
- `POST /api/v1/extensions/events`
- `POST /api/v1/quality/signals`
- `GET /api/v1/quality/cost`
- `GET /api/v1/performance/smoke`
- `GET /api/v1/compliance/mvp`
- Operator/readiness endpoints remain policy checked and audit backed.

The unversioned health/readiness/version endpoints are operational probes. The
versioned `/api/v1/*` endpoints establish the MVP API namespace. Future
domain-resource endpoints should live under `/api/v1`.

The service dependency is optional. Importing `kontextual_engine` and
`kontextual_engine.api` does not require FastAPI; calling `create_app()` does.
Install the `service` extra to run the HTTP adapter:

```bash
python3 -m pip install -e '.[service]'
```

## Planned Resource Shape

Remaining planned endpoint groups:

- `POST /collections`, `GET /collections`, `GET /collections/{id}`
- `POST /artifacts`, `GET /artifacts/{id}`, `GET /artifacts`
- `POST /context/artifact/{id}`

For the governed asset registry architecture, these planned groups should be
translated to assets, metadata, context packages, and bounded agent operation
resources.

## MVP API Versioning Policy

- `/api/v1` is the first stable namespace for implemented service resources.
- Backward-incompatible changes require a new namespace such as `/api/v2`.
- Additive response fields are allowed inside a version.
- Structured diagnostics and error codes are part of the contract and should
  remain stable inside a version.
- Unversioned operational probes may remain as aliases for the active API
  generation, but domain-resource endpoints must be versioned.

## 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

No MVP service API task remains deferred in this workplan.
- Streaming run execution.
- Provider-backed assisted steps.