Core concepts

Flowker is built around a set of interconnected concepts. The last section on this page shows how everything connects.

Workflows

A workflow is the definition of a business process, the sequence of steps Flowker follows to complete an operation. Workflows go through a lifecycle:

Status	Description
`draft`	Created and editable. Not yet runnable.
`active`	Ready to execute. Structure is locked.
`inactive`	Deactivated. No new executions accepted.

To move a workflow between states, use the activate, deactivate, and move to draft endpoints.

Nodes and edges

Nodes are the individual steps of a workflow, or tasks in business terms. Each node is a unit of work: receive an event, call a service, evaluate a condition, or perform an action. Flowker supports four node types:

Type	Purpose	When to use
`trigger`	Entry point for the workflow	Starts execution when an event occurs.
`executor`	Calls an external service through a provider configuration	When you need to call an external API or integration.
`conditional`	Branches execution based on conditions	When the next step depends on the result of a previous one.
`action`	Performs a built-in action; the available type is `set_output`, which sets the execution’s final output	For setting the workflow’s final output without an external call.

Edges connect nodes and define the order of execution. Branching lives in the conditional node, not in the edge: the conditional node evaluates its condition and produces an outcome handle, and Flowker follows the single outgoing edge whose sourceHandle matches that handle. Every other node type follows all of its outgoing edges.

Catalog

The catalog is the registry of the built-in providers, executors, and triggers available in Flowker. Before configuring any integration, browse the catalog to see what’s already available:

Catalog executors are the built-in components a workflow node invokes. They include the generic HTTP connector, and the operations of native providers such as the Midaz ledger and Tracer.
Triggers define the event types that can start a workflow (e.g., webhooks).

Use these endpoints to explore what’s available:

List catalog executors and List catalog triggers to discover executor and trigger types.
List catalog providers (GET /v1/catalog/providers) to list all available providers.
Get catalog provider (GET /v1/catalog/providers/{id}) to get details for a specific provider.
List executors by provider (GET /v1/catalog/providers/{id}/executors) to list the executors available for a specific provider.

Provider configurations

A provider configuration is your connection to one live instance of an external service. It is the object a workflow node points at, and the object Flowker reads when that node runs. Flowker separates the type of service from your connection to it:

Concept	What it is	Nature
Provider	A type of external service (e.g., Midaz, Tracer, a generic HTTP endpoint).	Static — published in the catalog.
Provider configuration	Your connection to one instance of that provider.	Dynamic — you create and manage these.

Each provider configuration holds:

config: the connection details for that instance, such as the base URL and authentication credentials. For the default catalog kind, Flowker validates this map against the catalog provider’s JSON Schema. For external_openapi, it uses an external-OpenAPI configuration validator. A read never returns the credential the authentication type declares.
allowedHosts: the public hosts this configuration is allowed to call.
allowedPrivateHosts: named private hosts your operations team allows this configuration to reach. It lifts only Flowker’s private or loopback restriction: if allowedHosts is non-empty, it must also include the host. Cloud metadata and link-local addresses stay blocked.
schemaBindings: the XSD or OpenAPI schemas bound to this configuration, each with an optional restriction to specific OpenAPI operations.

A configuration also carries a kind. Supported values are catalog (the default), which connects to a catalog provider, and external_openapi, which connects to an OpenAPI document you uploaded yourself so a workflow node calls your own API’s operations. See Connecting your own API. Provider configurations have two statuses: active (in use) and disabled (temporarily offline). Use Disable provider configuration to take a connection out of service and Enable provider configuration to bring it back.

How a workflow reaches it

Every executor node can carry a providerConfigId, the identifier of the provider configuration it calls through. At run time, Flowker builds each outgoing request from the base URL of that provider configuration plus the path on the node, and the node fails if the provider configuration is not active. Use the Provider configurations endpoints to create, read, update, disable, enable, and delete your connections.

Templates

Workflow templates are pre-built workflow patterns published in the catalog. Each template describes a known integration pattern and the parameters that pattern expects. Each template has a parameter schema that defines what inputs it expects (e.g., which provider configuration to use, threshold values). When Flowker can retrieve active provider configurations, it enriches referenced parameter fields with selectable options. To inspect a template:

List the catalog templates.
Get the template detail to see its parameter schema.
Validate a set of parameters against that schema.

Executions

An execution is a runtime instance of a workflow. A trigger normally starts a new execution. A retry that reuses an existing idempotency key returns the pre-existing execution instead of creating another. Each execution tracks:

executionId: unique identifier for this run.
status: current state (pending, running, completed, or failed).
stepResults: the output of each executed executor, conditional, or action node, in order. Trigger nodes start graph traversal and do not create execution-step records.
finalOutput: the final value persisted for the execution. When a set_output action produces an object, Flowker uses that object. Otherwise Flowker returns the accumulated workflow context.

Use Get execution status to monitor progress and Get execution results to retrieve the full output.

The status endpoint returns the execution record, including its current status. The dedicated results endpoint (GET /v1/executions/{id}/results) returns status, stepResults, and finalOutput when present. A failed step can include errorMessage. This response has no top-level error-details field.

Idempotency

Direct execution requests require a non-empty Idempotency-Key string. Flowker does not enforce UUID format. The webhook header is optional. If Flowker receives a second request with the same Idempotency-Key, it returns the pre-existing execution instead of creating another. A direct replay includes idempotencyReplayed: true in the response.

Idempotency-Key: 7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b

Use a new key when you intentionally want a new execution. Reuse the same key only when retrying the exact same request.

Dashboard

The Dashboard API provides aggregated summaries of your workflows and executions. Use it whenever you need a high-level view of system health without querying individual executions.

Workflow summary returns totals and breakdowns by status (draft, active, inactive).
Execution summary returns totals and breakdowns by status, with optional time range and status filters.

Example response from GET /v1/dashboards/executions:

{
  "total": 12847,
  "completed": 11903,
  "failed": 712,
  "pending": 130,
  "running": 102
}

Common use cases:

Monitoring execution health: track completion and failure rates over time to spot degradation early.
Building status pages: surface workflow throughput and success metrics in internal or client-facing dashboards.
Alerting on failure rate spikes: compare failed / total against a threshold to trigger alerts before issues cascade.

How it all fits together

Flowker’s concepts build on each other in a clear sequence:

Explore the catalog to discover available providers, catalog executors, triggers, and templates.
Create provider configurations to connect Flowker to live instances of external services.
Define workflows: each executor node names a catalog executor and the provider configuration it calls through.
Execute workflows to run your business process and retrieve results.
Monitor: use the dashboard for operational summaries and the executions API for step-level detail.

Follow the Getting started guide to run your first workflow end to end.

Overview

Guides

Console

Operations

Workflows

Nodes and edges

Catalog

Provider configurations

How a workflow reaches it

Templates

Executions

Idempotency

Dashboard

How it all fits together

​Workflows

​Nodes and edges

​Catalog

​Provider configurations

​How a workflow reaches it

​Templates

​Executions

​Idempotency

​Dashboard

​How it all fits together

Workflows

Nodes and edges

Catalog

Provider configurations

How a workflow reaches it

Templates

Executions

Idempotency

Dashboard

How it all fits together