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

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

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