Ensure flow (config-as-code converge)

POST

/v1/flows/ensure

Idempotently converge a repo-defined flow definition onto the platform. Identity is name + account scope. Hash-only probes skip the payload in the steady state (a miss is a normal 200 definitionRequired response, not an error); full requests create the flow or append a new version when the canonical content hash differs. Non-executing: never touches the execution pipeline — the deploy-time sibling of the dispatch-coupled flowMode: "upsert" (which saves and runs in one request). The response always carries the server-computed canonical hash. Set dryRun to plan without writing (CI drift gate), onConflict: “overwrite” to converge over dashboard/API edits, and release: “publish” to also re-aim the published-version pointer.

Idempotently converge a repo-defined flow definition onto the platform. Identity is name + account scope. Hash-only probes skip the payload in the steady state (a miss is a normal 200 `definitionRequired` response, not an error); full requests create the flow or append a new version when the canonical content hash differs. Non-executing: never touches the execution pipeline — the deploy-time sibling of the dispatch-coupled `flowMode: "upsert"` (which saves and runs in one request). The response always carries the server-computed canonical hash. Set dryRun to plan without writing (CI drift gate), onConflict: "overwrite" to converge over dashboard/API edits, and release: "publish" to also re-aim the published-version pointer.

Authentication

AuthorizationBearer

API key or Clerk session token

Request

This endpoint expects an object.

namestringRequired>=1 character

contentHashstringOptionalformat: "^[0-9a-f]{64}$"

definitionobjectOptional

dryRunbooleanOptional

expectedRemoteHashstringOptionalformat: "^[0-9a-f]{64}$"

onConflictenumOptional

Allowed values:

releaseenumOptional

Allowed values:

Response

Converge result: unchanged | created | updated | definitionRequired (hash miss — retry with the full definition) | plan (dryRun)

object

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

409

Conflict Error

422

Unprocessable Entity Error

500

Internal Server Error

$	curl -X POST https://api.runtype.com/v1/flows/ensure \
>	-H "Authorization: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"name": "user-registration-flow"
>	}'

1	{
2	"contentHash": "a3f5c2d4e6b7890f1234567890abcdef1234567890abcdef1234567890abcdef",
3	"flowId": "flow_9876543210abcdef",
4	"result": "unchanged",
5	"versionId": "version_20240601_153000"
6	}