REST API

The service exposes a full JSON API: run triggering and inspection, live SSE run tailing, pipeline/step CRUD with validation, per-pipeline and per-step analytics, calibration bins, prompt/agent version history, readiness readouts, accuracy feedback, Prometheus metrics, and health probes.

Every route below except GET /health/GET /favicon.svg/GET /metrics (open by default) requires a bearer token — each section names the role it needs. See Security for the token/role model.

This page covers the core management endpoints — triggering and inspecting runs, feedback, pipeline listing, metrics, and health. For the read-only pipeline/step/agent analytics endpoints, see Analytics API. For the endpoints that create, update, validate, and delete pipelines and steps, see Write API — both were added to back the VectorStep Service MCP.

Triggering runs

POST /webhook?source=<source>

Role: webhook

Trigger a run. Returns immediately — the pipeline runs in the background.

• → {"status": "accepted", "run_id": "<uuid>"}
• → {"status": "deduplicated", "run_id": "<uuid>", "reason": "..."} — see Webhooks for idempotency and deduplication.
• → {"status": "skipped_testing", "pipeline": "...", "reason": "..."} — see Pipeline stages; pass ?allow_testing=true to run a stage: testing pipeline from this source anyway.

POST /pipelines/{name}/run

Role: operator

Manually trigger a pipeline by name — powers the UI’s Run now button.

Note

Gated at operator rather than webhook — this is an internal/management action, at the same trust boundary as /reload’s admin gate but one step down, not the public ingestion path that a webhook-role token authenticates. Runs triggered here are unattributed (team=None) regardless of who’s authenticated, since a session/token here carries no team the way a webhook-role token does.

• body: same shape as a generic webhook payload (see Webhooks), pipeline forced from the path
• → {"status": "accepted", "run_id": "<uuid>", ...}

Reload

POST /reload

Role: admin

Reload the step library and all pipeline YAMLs from disk without restarting.

→ {"status": "reloaded", "pipelines_loaded": 3}

SIGHUP also triggers a reload:

kill -HUP <uvicorn-pid>

Schedules

GET /schedules

Role: viewer

List active cron schedules.

→ {"schedules": [{"pipeline": "...", "cron": "...", "next_run": "..."}]}

Runs

GET /runs

Role: viewer

List runs, newest first.

Filters: ?status=escalated, ?pipeline=alert-triage-critical, ?team=payments, ?stage=production|testing.

Pagination: ?limit=50&offset=0 (max 200).

→ {"runs": [{id, pipeline_name, source, status, team, stage, triggered_at, completed_at}, ...]}

stage is "testing" or "production" (see Pipeline stages), included on both this list and the full detail response below — it’s persisted per-run, so it reflects the pipeline’s stage at the time the run was triggered rather than its current config.

GET /runs/{run_id}

Role: viewer

Full run detail — includes all steps with confidence scores and parsed output.

POST /runs/{run_id}/rerun

Role: operator

Re-run a pipeline from a specific step.

• body: {"from_step": "step-name"}

Feedback

POST /runs/{run_id}/feedback

Role: operator

Submit or update human accuracy feedback for a run (outcome: correct | partial | incorrect).

• body: {"outcome": "correct", "notes": "..."}
• → {"run_id": "...", "outcome": "correct", "notes": "...", "submitted_at": "..."}

Upserts — submitting again overwrites the previous outcome and notes.

GET /runs/{run_id}/feedback

Role: viewer

Get current feedback for a run.

→ {"feedback": {run_id, outcome, notes, submitted_at}} or {"feedback": null}

POST /runs/{run_id}/steps/{step_name}/feedback

Role: operator

Submit or update human accuracy feedback for a single step execution (outcome: correct | partial | incorrect). step_name may contain / for fan-out branches (e.g. triage/0) — the route uses a path converter to match it.

• body: {"outcome": "correct", "notes": "..."}
• → {"run_id": "...", "step_name": "...", "outcome": "correct", "notes": "...", "submitted_at": "..."}

Upserts — submitting again overwrites the previous outcome and notes.

GET /runs/{run_id}/steps/{step_name}/feedback

Role: viewer

Get current feedback for a single step execution.

→ {"feedback": {run_id, step_name, outcome, notes, submitted_at}} or {"feedback": null}

Live tailing

GET /ui/runs/{run_id}/stream

Role: viewer (401s rather than redirecting when missing — see Security)

Server-Sent Events stream for live run tailing. See UI: run detail.

Pipelines and observability

GET /pipelines

Role: viewer

List loaded pipelines — includes stage and tags alongside name/description/version.

GET /metrics

Role: none by default; viewer when auth.metrics_auth: true

Prometheus metrics — runs/steps by status, step duration histograms, verifier veto rate.

GET /health

Role: none

Liveness/readiness probe — also surfaces in-process concurrency state.

→ {"status": "ok", "version": "...", "active_runs": 0, "max_concurrent_runs": 10}