# 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

```sh
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:

```sh
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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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, export manifest 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`.

```text
GET /retained-runs?runs_dir=/runs
```

### `GET /retained-runs/latest`

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

```text
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:

```sh
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.