Local service HTTP API

The local integration point for the Yam app and any other client (REQ-ADE-1, LLD §13.5). Bound to 127.0.0.1, behind a bearer token printed on stdout. Every handler calls the same function the CLI calls; no logic lives here.

OpenAPI 3.1.0, service version 0.1.0. The document itself is openApiDocument() in @svatah/yam-service; the Python and Java clients under clients/ and @svatah/yam-sdk are generated from it.

Method	Path	Summary
GET	/project	Config, flows, stories, compositions, run blocks and API names
GET	/flows/{file}	Read a flow file
PUT	/flows/{file}	Write a flow file
POST	/compile	Compile and lint
GET	/plan	The compiled plan, story by story
POST	/run	Start a run; step events arrive on the stream
GET	/runs	Every run's summary
GET	/runs/{id}	One run's summary
POST	/runs/{id}/stop	Stop a run that is going
GET	/runs/{id}/results	One run's step results
GET	/runs/{id}/audit	One run's audit log
GET	/bindings	The bindings store
GET	/bindings/{id}	One binding
PUT	/data	Write data.yaml
GET	/data	Run data, with secrets redacted
GET	/runs/{id}/screenshots/{name}	A screenshot a run wrote
POST	/api/request	Execute one API request ad hoc
PUT	/api/{name}	Save a named request under api/.yaml
GET	/api	Named API requests
POST	/record	Start a recording session; decisions arrive on the stream
POST	/capture	Record a flow from what a person does; sentences arrive on the stream
POST	/capture/{id}/stop	End a capture, writing the flow and its bindings
POST	/record/{id}/decision	Accept, re-pick or reject the grounding a session is waiting on
POST	/record/{id}/stop	Stop a recording session
POST	/migrate	Import a Yam prototype's electron-db directory into this project
POST	/bindings/verify	Dry-resolve the store, or one binding
POST	/heal	Heal a run; proposals arrive on the stream
POST	/surface/{session}/snapshot	The driven session's snapshot, for the picker and the explorer
POST	/trajectory/compile	Compile a captured trajectory into proposals//
GET	/agents/clients	Who is connected over MCP right now
GET	/tools	The tools this project exposes, and every invocation served
GET	/targets	Discover available targets and adapter readiness (SF-04)
GET	/sessions	List active surface sessions (SF-05)
POST	/sessions	Connect to a target and open a surface session (SF-04)
DELETE	/sessions/{session}	Close a surface session (SF-05)
GET	/sessions/{session}/capabilities	A session's adapter capabilities (SF-09)
POST	/sessions/{session}/snapshot	A semantic snapshot of the surface (SF-10)
POST	/sessions/{session}/act	Perform a validated action on the surface (SF-11)
POST	/sessions/{session}/read	Read a value from the surface (SF-11)
POST	/sessions/{session}/check	Check a predicate against the surface (SF-11)
POST	/sessions/{session}/describe	Describe a specific element on the surface (SF-10)
GET	/sessions/{session}/events	What this session did, and the steps a proposal compiles from (T17, SF-19)
POST	/sessions/{session}/control	Take, release or report who holds a target (T16, SF-13)
POST	/sessions/{session}/request	Send an HTTP request on an HTTP surface (T15, SF-04)
POST	/sessions/{session}/screenshot	Take a screenshot of the current surface (SF-11)
GET	/events	The event stream (WebSocket)
GET	/events/sse	The event stream (server-sent events)
GET	/openapi.json	This document
GET	/health	Liveness, for the app's spawn handshake