VegaFlow API reference

The VegaFlow service API is scoped by organization and workspace. Use the API base shown by your deployment.

Read API fundamentals for service base paths, bearer/API-key authentication and tenant scope.

{api-base}/orgs/{org_id}/workspaces/{workspace_id}

Core QuickFlow resources include an additional /vegaflow path segment. Pipeline project resources are rooted directly below the workspace path.

Resource groups

Group	Root	Operations
Connector catalog	`/vegaflow/connectors`	list connectors, read property schema
Connections	`/vegaflow/connections`	validate, create, list, get, update, delete, discover catalog
Compute environments	`/vegaflow/clusters`	create, list, get, update, delete, start, stop
QuickFlows	`/vegaflow/quickflows`	upsert, list, get, delete, versions, runs, schedules
Git integrations	`/git-integrations`	create, list, get, update, delete
Pipeline projects	`/pipeline-projects`	CRUD/archive, purge, repository, definition roots, revisions, reconciliations, environments, deployments, sessions
Pipelines	`/pipelines`	list/get, versions, publication, schedules, triggers, executions
Permissions	resource `/permissions` paths	assign, remove and inspect user/group/role/service-principal access

Request conventions

Send and receive JSON unless an endpoint documents another content type.
IDs are resolved inside the organization/workspace path; cross-workspace IDs do not grant access.
Timestamps are ISO 8601 strings.
List endpoints return summary items and can support bounded paging/filter parameters described by their schema.
PUT replaces the editable resource contract; omitted fields can return to defaults. Use the current resource version when the schema exposes optimistic concurrency.
Delete usually archives or retires user-facing definitions. Purge is a separate operation where irreversible removal exists.

Example request

curl --request GET \
  --header "Authorization: Bearer $VEGALAKE_ACCESS_TOKEN" \
  --header "Accept: application/json" \
  "https://api.example.com/api/v1/vegaflow/orgs/org_01/workspaces/ws_01/vegaflow/quickflows"

Keep access tokens in environment-backed secret storage. Do not commit them to examples, scripts or pipeline repositories.

Starting/stopping compute, source reconciliation, deployment preparation, execution, cancellation, retry and purge can be asynchronous. A successful mutation means the request was accepted and returns a resource whose state must be observed.

Do not poll without bounds. Use increasing intervals, honor server retry guidance and stop when the resource reaches a terminal state.

Error model

Errors use an HTTP status plus structured JSON details. Clients should preserve the machine-readable code, message, field/location details and request identity when available.

Status	Meaning
`400`	Invalid syntax, field value or state transition.
`401`	Missing or invalid authentication.
`403`	Principal lacks a required permission or dependency use grant.
`404`	Resource is not visible in the scoped workspace.
`409`	Name/version conflict, active-run conflict or incompatible lifecycle state.
`422`	Semantically invalid definition or connector configuration.
`429`	Admission or request-rate limit.
`5xx`	Service failure; retry only safe/idempotent operations.

Idempotency

Start, cancel, webhook and reconciliation paths protect against duplicate control requests according to their resource identity. For external event ingestion, supply a stable source event ID. Never assume an arbitrary failed POST is safe to replay unless the endpoint provides an idempotency identity or the returned resource can be reconciled first.