Designer API

The designer backend (Hono on Node 22) exposes its API at https://designer.<root>/api/*. The API requires sign-in: once the first local admin exists (the setup wizard creates it on first visit) or SSO enforcement is on, every /api/* route outside a short public list answers 401 without a session or an OAuth bearer.

The designer’s PIPEBASE_REQUIRE_AUTH overrides that rule. On the standalone docker-compose.yml it has to be added to the pipebase-designer service’s environment: block, because a project .env only feeds interpolation. true applies the rule from the start, before the first admin exists. false turns it off even when a local admin exists or SSO enforcement is on. Under the default PIPEBASE_WORKSPACE_ENFORCEMENT=report, or under off, a request without a session or bearer then passes, and is refused only where a later check of the caller’s role applies (admin-only routes, for example). Under enforce the workspace access layer still answers such a request 401 on every route that is not public and does not check a token of its own. Set false only on a designer that is reachable from a private network alone.

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
GET	/api/flows/:id/tests	—	Returns the flow’s FlowTestSuite (given/when/then tests), or an empty suite if none exists yet
PUT	/api/flows/:id/tests	FlowTestSuite	Saves the suite; also re-exports a human-readable flow.tests.yaml next to the flow’s Camel YAML
POST	/api/flows/:id/tests/import	—	Imports flow.tests.yaml off disk into the canonical suite store — the escape hatch for hand-edited YAML. 404 when no flow.tests.yaml exists.
POST	/api/flows/:id/tests/run?testId=&runtimeId=	—	Deploys the flow once, then runs the whole suite (or a single test via testId) against the resolved runtime. Returns a SuiteResult.

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

Managed runtimes are opt-in (see Runtimes): unless the designer has both the Docker socket and PIPEBASE_RUNTIME_ROOT_DOMAIN, the feature is off. POST /api/runtimes/managed checks for an installation admin first, so once anyone can sign in only an installation admin gets its 503; anyone else gets 401 or 403. The start, stop and restart routes answer 503 to every request that gets past sign-in and the workspace access layer.

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 in the repository.