Designer API

The designer backend (Hono on Node 22) exposes its API at https://designer.<root>/api/*. No auth required for the API itself — Pipebase’s threat model assumes the designer is on a private network or behind your own SSO layer.

Flows

Method	Path	Body	Behaviour
GET	/api/flows	—	Returns FlowSummary[]
POST	/api/flows	{name?}	Generates uuid7 + writes a deployable seed YAML. Returns full FlowDocument, 201.
GET	/api/flows/:id	—	Returns FlowDocument
PUT	/api/flows/:id	{name?, yaml, layout}	Atomic disk write, mutates index entry
DELETE	/api/flows/:id	—	Removes index + <id>/. 204.
POST	/api/flows/:id/deploy	—	Push YAML to runtime via PUT /_api/flows/:id. Stamps lastDeployedAt.
POST	/api/flows/:id/undeploy	—	Remove from runtime; keep on designer disk
POST	/api/flows/:id/promote	{targetRuntimeId}	Promote via the upstream promotesTo chain
GET	/api/flows/:id/deployments	—	Per-runtime deployment matrix (in-sync / stale / not-deployed / unreachable)
GET	/api/flows/_deployments	—	Bulk version of the above for every flow
GET	/api/flows/:id/params	—	{params: {k:v,...}}
PUT	/api/flows/:id/params	{params: {k:v,...}}	Replace; validates each pair
POST	/api/flows/:id/test	{method?, path, headers?, body?}	Forwards an HTTP request to the runtime
GET	/api/flows/:id/runs?limit=N	—	Run history from runtime’s in-memory ring buffer

Runtimes (multi-runtime registry)

Method	Path	Body	Behaviour
GET	/api/runtimes	—	List RuntimeSummary[]
POST	/api/runtimes	CreateRuntimeBody	Connect an existing external runtime
POST	/api/runtimes/managed	ProvisionRuntimeBody	Provision a new container via Docker daemon
GET	/api/runtimes/:id	—	Full record (no token)
PUT	/api/runtimes/:id	UpdateRuntimeBody	Sparse update; supports promotesTo
DELETE	/api/runtimes/:id	—	Remove (cascade-tears-down container if managed)
GET	/api/runtimes/:id/health	—	Live RuntimeHealth from /_api/health
GET	/api/runtimes/:id/container	—	Docker container state (managed runtimes only)
POST	/api/runtimes/:id/start	—	Start the container
POST	/api/runtimes/:id/stop	—	Stop
POST	/api/runtimes/:id/restart	—	Restart

Auth & RBAC (Phase 3)

Method	Path	Body	Behaviour
POST	/api/oauth/token	client_credentials grant	Issue a Bearer JWT
GET	/api/oauth-clients	—	List clients
POST	/api/oauth-clients	CreateOAuthClientBody	Create client (returns plaintext secret once)
PUT	/api/oauth-clients/:id	UpdateOAuthClientBody	Update
DELETE	/api/oauth-clients/:id	—	Remove
GET	/api/roles	—	List roles
POST	/api/roles	CreateRoleBody	Create
PUT	/api/roles/:id	UpdateRoleBody	Update
DELETE	/api/roles/:id	—	Remove

Mappings

Method	Path	Behaviour
GET/POST/PUT/DELETE	/api/value-mappings(/...)	Key→value lookup tables
POST	/api/value-mappings/:id/deploy	Push to runtime
GET/POST/PUT/DELETE	/api/message-mappings(/...)	JSON↔XML mapping documents
POST	/api/message-mappings/:id/deploy	Compile to XSLT, push

Monitor / messages

Method	Path	Behaviour
GET	/api/messages	Cross-runtime message log fan-out
GET	/api/messages/stats	Aggregated counts + buckets
GET	/api/trace/stream	SSE — live trace events
GET	/api/logs/stream	SSE — live log events

Source of truth

This table is a snapshot. The actual route table lives in designer/packages/backend/src/routes/*.ts — see the GitHub source.