REST API

Valved is headless by default. valved serve exposes a FastAPI REST API with full parity to the CLI — every action Valved’s own agents can take is available to any external agent, chat tool, or script.

valved serve [--port N] [--host H] [--workers N]
# defaults to http://127.0.0.1:8765

Discovering the surface

The OpenAPI schema is served live, and there’s interactive Swagger:

curl -s http://127.0.0.1:8765/api/openapi.json    # machine-readable schema
open http://127.0.0.1:8765/api/docs               # Swagger UI

The MCP server is generated from exactly this schema, so the REST surface and the MCP tool catalog are always in lockstep.

Health

curl -s http://127.0.0.1:8765/healthz             # liveness
curl -s http://127.0.0.1:8765/readyz              # readiness (200 once migrations are at head)

Resource routers

The API is organized into routers under /api/v1, mirroring the CLI groups:

Router	Resource
plans	draft plans (create, refine, show)
builds	build runs against a plan
pipelines	pipeline definitions + lineage
runs	on-demand runs, logs, and the event stream
schedules	live schedule (pause/resume/set-cron), audited changes
deploys	promote built code via the configurable handoff
jobs / workers	the queue and worker pool
asks / investigations	read-only Q&A and recovery records
components / targets	component references and connection targets
agents / skills / mcp_servers	extensibility
memory / metrics	project memory and cost/usage rollups
tokens / webhooks	API token lifecycle and run-completion webhooks

Auth

Requests carry a bearer token. valved serve bootstraps one to .valved/token on first run; mint or rotate with:

valved auth rotate                                # prints the new token once
# then:
curl -s http://127.0.0.1:8765/api/v1/pipelines \
  -H "Authorization: Bearer $VALVED_API_TOKEN"

Programmatic token lifecycle is REST-native: POST /api/v1/tokens and DELETE /api/v1/tokens/{id}.

Streaming & webhooks

• Run event stream — GET /api/v1/runs/{run_id}/stream streams live run events (this is what valved run --watch consumes). Because it’s a stream, it is not exposed as an MCP tool.
• Webhooks — register a webhook to receive run-completion callbacks; manage them under /api/v1/webhooks (create, patch, rotate-secret, delete).

Example: plan → build → run over HTTP

BASE=http://127.0.0.1:8765/api/v1
AUTH="Authorization: Bearer $VALVED_API_TOKEN"

PLAN=$(curl -s "$BASE/plans" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"goal":"ingest the Stripe charges API into raw_stripe"}' | jq -r .id)

curl -s "$BASE/builds" -H "$AUTH" -H 'Content-Type: application/json' \
  -d "{\"plan_id\":\"$PLAN\"}"

curl -s "$BASE/runs" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"pipeline":"stripe_charges"}'