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, and their filesystem paths after a job has succeeded.

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. See docs/SERVICE-JOB-DURABILITY.md for the explicit restart and recovery contract.