Core concepts

Understand the building blocks of Flowker: workflows, nodes, edges, catalog, provider configurations, templates, executions, and dashboard.

Flowker is built around a set of interconnected concepts. Understanding how they relate to each other helps you design, configure, and run workflows effectively. 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 — what you might call 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	Always the first node. 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 read-only registry of all built-in providers, executors, and triggers available in Flowker. You cannot create or modify catalog entries — you discover them.

Before configuring any integration, browse the catalog to see what’s already available:

• Catalog executors are the built-in components a workflow node invokes — the generic HTTP connector, and the operations of native providers such as the Midaz ledger and Tracer. You discover them; you never create them.
• 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. Recognized sensitive leaves are written to the secrets backend and replaced by secretRef; legacy configurations without secretRef can contain inline values.
• 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.

Executor configuration registry

---

Flowker keeps a registry of executor configuration records. The registry exposes four operations:

Operation	Endpoint
List	GET /v1/executors
Get	GET /v1/executors/{id}
Update	PATCH /v1/executors/{id}
Delete	DELETE /v1/executors/{id}

Every record carries a status, which the API reports in each response:

Status	Description
unconfigured	The record has no connection details yet.
configured	The record carries connection details.
tested	The record was verified.
active	The record is in service.
disabled	The record is out of service.

The update body does not include status, but the list operation accepts it as a query filter. Update applies to records in unconfigured or configured status; delete applies to records in unconfigured, configured, or disabled status. No operation in this version moves a record into tested, active, or disabled; the table lists those values because responses report them and the list filter accepts them.

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.

The catalog ships the tracer-midaz-validation template (“Tracer Validation + Midaz Transaction”): it receives a webhook request, validates the transaction through Tracer, and creates the transaction in Midaz when Tracer approves it.

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. If lookup is unavailable or fails, it returns the original schema instead.

To inspect a template:

1. List the catalog templates.
2. Get the template detail to see its parameter schema.
3. 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 it 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 returns HTTP 200 and includes idempotencyReplayed 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 — useful for building operational dashboards and monitoring tools. 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:

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

Ready to see this in practice? Follow the Getting started guide to run your first workflow end to end.