ControlPlane API

Deprecation Notice

The ControlPlane and manual compilation may be removed in a future release. Startup Compilation is the preferred approach - flows are automatically compiled when workers start, eliminating the need for manual compilation in most workflows.

The ControlPlane edge function exposes HTTP endpoints for compiling TypeScript flows to SQL. The pgflow compile CLI uses these endpoints internally.

Note

For how to compile flows manually, see Manual Compilation.

Base URL

Local development:

http://127.0.0.1:54321/functions/v1/pgflow

Production (Supabase.com):

https://<project-ref>.supabase.co/functions/v1/pgflow

Endpoints

GET /flows/:slug

Compiles a flow definition to SQL statements.

Request:

GET /functions/v1/pgflow/flows/greetUser
Authorization: Bearer <anon_key>

Success Response (200):

{
  "flowSlug": "greetUser",
  "sql": [
    "SELECT pgflow.create_flow('greetUser');",
    "SELECT pgflow.add_step('greetUser', 'fullName', 'single', 0, NULL);",
    "SELECT pgflow.add_step('greetUser', 'greeting', 'single', 0, ARRAY['fullName']);"
  ]
}

Flow Not Found (404):

{
  "error": "Flow Not Found",
  "message": "Flow 'unknown' not found. Did you add it to supabase/functions/pgflow/index.ts?"
}

Compilation Error (500):

{
  "error": "Compilation Error",
  "message": "Detailed error message from compileFlow()"
}

Response Fields

Field	Type	Description
flowSlug	string	The slug identifier of the compiled flow
sql	string[]	Array of SQL statements to execute in order
error	string	Error type (only present on error responses)
message	string	Human-readable error description (only present on error responses)

Authentication

The ControlPlane requires a valid Supabase anon key in the Authorization header. For local development, this is your project’s local anon key from supabase status.

Usage with CLI

The pgflow compile command handles authentication and request formatting automatically:

npx pgflow@latest compile greetUser

For custom tooling or debugging, you can call the endpoint directly:

curl -H "Authorization: Bearer $SUPABASE_ANON_KEY" \
  http://127.0.0.1:54321/functions/v1/pgflow/flows/greetUser