guide-board/docs/LOCAL-SERVICE-API.md

Guide Board Local Service API

Status: draft Created: 2026-05-07

Purpose

The local service API is a thin HTTP facade over the same discovery, validation, planning, execution, and report contracts used by the CLI. It is intended for local development, containerized operation, and future UI integration.

It does not change certification boundaries: guide-board prepares structured evidence and assessment packages, but it does not issue certifications or audit assurance.

Start

PYTHONPATH=src python3 -m guide_board serve --host 127.0.0.1 --port 8080

External extension repositories use the same top-level option as the CLI:

PYTHONPATH=src python3 -m guide_board \
  --extension-dir ../open-cmis-tck \
  serve --host 127.0.0.1 --port 8080

Paths supplied to request bodies are resolved relative to the configured --root unless they are absolute paths.

Endpoints

GET /health

Returns service status, configured root, and in-memory job counts.

GET /extensions

Lists bundled and configured external extensions using the same discovery logic as guide-board extensions list.

POST /profiles/validate

Validates a target or assessment profile.

{
  "kind": "target",
  "path": "profiles/targets/sample-repository.json"
}

Use "kind": "assessment" for assessment profiles.

POST /assessments/plan

Builds a run plan without starting a run.

{
  "target": "profiles/targets/sample-repository.json",
  "assessment": "profiles/assessments/sample-noop.json"
}

An optional extension_dirs array can add request-specific external extension locations.

POST /runs

Starts an assessment run in a background thread and returns a job record.

{
  "target": "profiles/targets/sample-repository.json",
  "assessment": "profiles/assessments/sample-noop.json",
  "output_dir": "runs/sample-noop"
}

The HTTP job status is queued, running, succeeded, or failed. A succeeded job means the guide-board executor completed and wrote its normal run directory; the assessment result itself is still reported separately as completed, failed, blocked, or infrastructure_error.

GET /runs

Lists known in-memory jobs for the current service process. Job records are not durable across service restarts.

GET /runs/{job_id}

Returns a single job record with request metadata, result paths, or execution errors.

GET /runs/{job_id}/reports

Returns the Markdown report content, assessment package JSON, retention summary, submission package JSON when present, and their filesystem paths after a job has succeeded.

GET /retained-runs

Lists durable retained run summaries by scanning a runs directory. Without a query parameter, the service scans <root>/runs.

GET /retained-runs?runs_dir=/runs

GET /retained-runs/latest

Selects the latest retained run, optionally filtered by target and assessment profile refs.

GET /retained-runs/latest?runs_dir=/runs&target=sample-repository&assessment=sample-noop-assessment

GET /retained-runs/{run_id}/reports

Returns the retained summary plus safe report paths for a durable run. This works after a service restart because it reads retention-summary.json from disk instead of in-memory job records.

GET /retained-runs/{run_id}/artifact-manifest

Returns the assessment package artifact_manifest for a retained run. If the run predates assessment packages, the response is compatible and returns an empty manifest with compatibility: "assessment-package-missing".

Retained-run endpoints validate report and artifact paths before returning them. A path that escapes the selected run directory is rejected.

Container Mode

The core container can run the service through the existing entrypoint:

podman run --rm -p 8080:8080 \
  -v "$PWD/runs:/runs" \
  guide-board-core:local \
  --root /opt/guide-board serve --host 0.0.0.0 --port 8080

The service keeps job state in memory. Durable run evidence remains in the mounted output directory and can be discovered through GET /retained-runs after restart. See docs/SERVICE-JOB-DURABILITY.md for the explicit recovery contract.