Skip to navigation

Validate Workflow

Validate a workflow definition against the FULL run-start bundle, without saving it.

Runs every gate a run start would apply — validate_definition (structural / port-contract validation) plus every preflight_definition gate (source/output completeness, locale routing, translator coverage) — not the narrower save-time subset POST /workflows and PUT /workflows/{id} use. A definition that saves cleanly can still fail every one of these; that gap is exactly what this endpoint exists to close before a definition is ever persisted.

Always returns 200. valid: false with a populated errors list is itself a successful answer to “is this valid?” — 422 stays reserved for a malformed request body. A true entitlement refusal (a plan-gated node/provider the caller’s plan cannot use, ErrorCode.FORBIDDEN) is reported separately in blocked: not fixable by editing the graph. A voice-ownership violation (unauthorized/unknown/unsupported voice reference) is ErrorCode.VALIDATION_ERROR instead — an LLM fixes it the same way it fixes any other rule, by picking a different voice/model — so it is folded into errors like every other rule violation, not blocked.

No side effects — nothing is read from or written to the workflows table. Requires at least editor role. Scope is workflows:write deliberately: a caller who cannot create a workflow should not receive a validation result that exists only to gate creation.

Authentication

AuthorizationBearer
Clerk JWT token
OR
AuthorizationBearer

Onepin live API key (op_live_...). Test and public keys are reserved in Phase 1.

Headers

X-Workspace-Idstring or nullOptional

Request

This endpoint expects an object.
definitionobjectRequired
Graph and execution config to validate. Nothing is persisted.

Response

Successful Response
dataobject

Result of validating a definition against the full run-start bundle, without saving it.

valid reflects errors only — a non-empty blocked does not flip it to False, since blocked entries are not graph defects (see ValidationBlockedOut).

metaobject

Errors

422
Unprocessable Entity Error