Connecting your own API

Upload your service’s OpenAPI document to Flowker and call its operations from a workflow node. Register the document, point a provider configuration at it, and address one operation per node.

Flowker ships connectors for the services in its catalog. When the service you want to call is your own — an internal API, a partner API, anything with a published OpenAPI document — you upload that document and a workflow node calls its operations directly.

You do this once per document: upload it, create one provider configuration that points at it, then address one operation from each node that calls the service.

Before you begin

---

• Your service’s OpenAPI 3.x document as a file, at most 8 MiB, declaring at least one operation.
• The credentials your service requires, and the authentication method it expects. See Authentication for the methods Flowker supports.
• A deployment whose schema registry has blob storage configured. SCHEMA_REGISTRY_S3_BUCKET holds the OpenAPI documents you upload — see Flowker environment variables.
• A workflow in draft status to edit. An active workflow is locked. Deactivate it first, then move the inactive workflow to draft before editing and activating it again.

The Lerian Console covers the same path. Providers → + New Provider → Add your own API selects an uploaded document and sets the base URL and the authentication — see Adding a provider.

Step 1: Upload the OpenAPI document

---

1. Send the file

   Call Upload an OpenAPI schema as multipart/form-data with three parts: the file, a name, and a version.

   curl -X POST https://your-flowker-host/v1/openapi-schemas \
     -H "Authorization: Bearer $TOKEN" \
     -F "file=@acme-kyc.json" \
     -F "name=acme-kyc" \
     -F "version=v1.0.0"
   
2. Keep the id

   The 201 response describes what Flowker read out of the file. Its id is the value every later step references.

   Field	What it tells you
   id	The document’s identifier. A provider configuration and a webhook trigger point at it.
   name, version	The pair you sent.
   title	The info.title of the document.
   openapiVersion	The openapi version the document declares.
   operationCount	How many path-and-method operations the document declares.
   contentHash, byteSize	The stored file’s digest and size.
   createdBy, createdAt	Who uploaded it and when.

What a stored document is keyed by

name and version are yours to choose, up to 255 characters each. The pair is unique in your tenant: uploading the same name and version again answers FLK-0812. The id Flowker returns is a fresh UUID for each upload, and it is what everything else references — never the name or the version.

Flowker parses the file before it stores it. A file that is not an OpenAPI 3.x document, or one that declares no operation, answers FLK-0900. A file over 8 MiB answers FLK-0901.

Your uploaded documents are yours alone. A document is only visible to the tenant that uploaded it, and an id from another tenant never resolves.

Step 2: Read the operations you can call

---

1. List what you have stored

   List OpenAPI schemas returns your documents as metadata only, without their content. It is paginated: limit, cursor, sortBy and sortOrder, and the response carries nextCursor and hasMore.

2. Read one document's operations

   Get an OpenAPI schema returns the same metadata plus content — the stored file — and operations, one entry per operation the document declares.

   Field	What it tells you
   path	The operation path, exactly as the document writes it, such as /v1/checks.
   method	The operation’s HTTP method.
   operationId	The document’s operationId, when it declares one.
   hasRequest	Whether the operation declares a JSON request body.
   hasResponse	Whether the operation declares a JSON success response.

   Copy the path and the method of the operation you want. Step 4 puts them on the node.

3. Read one operation's field names

   Derive an operation schema takes a path and a method and returns inputSchema for the operation’s application/json request body and outputSchema for its first 2xx application/json response. Either field is absent when the document declares no such schema. For a non-JSON request body, use hasBody, bodyRequired, and bodyContentType. It also returns params, one entry per parameter the operation declares, each with its name, its in location and whether it is required.

   Those are the field names you write as mapping targets and sources in Step 4. Both query parameters are required, and method is case-insensitive and must be one of GET, PUT, POST, DELETE, OPTIONS, HEAD, PATCH or TRACE; a missing path or an unrecognised method answers FLK-0304. A path and method the document does not declare answers FLK-0902.

Step 3: Point a provider configuration at the document

---

Call Create a provider configuration with kind set to external_openapi. That kind is the bring-your-own-OpenAPI connection: it references your uploaded document instead of a catalog provider.

Field	Required	Description
kind	Yes	"external_openapi". You choose the kind when you create the configuration, and it stays the kind the configuration was created with.
providerId	No	Omit it — this connection targets your own document, not a catalog provider. A read of the configuration then returns the reserved id external.openapi.
name	Yes	A name for this connection, 1–100 characters.
config.openapi_schema_id	Yes	The id from Step 1. It must name a document in your tenant.
config.base_url	No	The scheme, host and path prefix Flowker sends requests to. Omit it to use the first usable servers entry of the document.
config.auth	No	A { type, config } authentication block, in the same shape every provider configuration uses. See Authentication for each type and its fields. Omit it for a service that needs no authentication.
allowedHosts	No	The hosts this configuration is allowed to call. Omit it, or send an empty list, to accept any public host.
allowedPrivateHosts	No	Named private hosts this configuration is allowed to reach. Cloud metadata and link-local addresses stay blocked.
schemaBindings	No	The stored documents this configuration binds to. See Bind the document.
description	No	Free text, up to 500 characters.
metadata	No	Your own key-value pairs.

Where the credential goes

The secret inside config.auth is write-only on creation and update. Flowker sends it to your secrets backend, removes it from the configuration document before it saves the document, and resolves it from the backend at execution time. For an external_openapi configuration, get-by-id does not resolve or return the secret values in config.auth. Keep credentials in config.auth; other configuration values can be returned by a read.

To rotate a secret later, send the new value in an update. To keep the current one, omit the field or send it blank while auth.type stays the same — see Authentication.

Where the host allow-lists are set

Both allow-lists belong to this create call, and to Update a provider configuration afterwards. allowedHosts names the hosts every node that calls through this configuration may reach; Flowker checks the request URL and each redirect hop against it at run time. An entry with a leading dot matches subdomains, so .acme-kyc.example.com matches api.acme-kyc.example.com. Entries are host names only, with no IP literal, no wildcard and no port.

allowedPrivateHosts is the companion list for a service that lives on a private network. It does not override allowedHosts: when allowedHosts is non-empty, it must also include the private host. A matching allowedPrivateHosts entry only lifts the private or loopback IP block; cloud-metadata and link-local addresses remain blocked.

Bind the document

Add a schemaBindings entry for the document you referenced. Each entry names one stored document: type is "openapi", schemaId is the same id you put in config.openapi_schema_id, and the optional operations array scopes the stored binding and is validated against the document when you save the configuration. It does not verify what workflow nodes call or limit an external_openapi node at execution time; the node uses config.openapi_schema_id, operation_path, and operation_method.

The binding is what makes the document’s dependants visible. With it, List resources referencing an OpenAPI schema reports this configuration, and a delete of the document is refused while the configuration is active — see Removing a document.

Flowker resolves every binding when you save. A schemaId that names no document in your tenant answers FLK-0942, and an operations entry the document does not declare answers FLK-0943, each naming the failing entry. A malformed entry — an unknown type, a schemaId that is not a UUID, operations on a binding that is not openapi, or an operation with no path or method — answers FLK-0293.

Example request

POST /v1/provider-configurations

{
  "name": "Acme KYC production",
  "description": "Production KYC checks",
  "kind": "external_openapi",
  "config": {
    "openapi_schema_id": "018f3e2a-1c4d-7b9e-a1b2-c3d4e5f6a7b8",
    "base_url": "https://api.acme-kyc.example.com",
    "auth": {
      "type": "api_key",
      "config": {
        "key": "sk-live-xxx",
        "header_name": "X-API-Key",
        "location": "header"
      }
    }
  },
  "allowedHosts": ["api.acme-kyc.example.com"],
  "schemaBindings": [
    {
      "type": "openapi",
      "schemaId": "018f3e2a-1c4d-7b9e-a1b2-c3d4e5f6a7b8",
      "operations": [
        { "path": "/v1/checks", "method": "POST" },
        { "path": "/v1/checks/{checkId}", "method": "GET" }
      ]
    }
  ]
}

The response returns the new configuration’s id. Keep it — Step 4 puts it in the providerConfigId of every node that calls this service.

Flowker checks the configuration before it stores it. A config with no openapi_schema_id, or one whose value is not a UUID, answers FLK-0946. An id that names no document in your tenant answers FLK-0947. A config.auth block Flowker cannot read — an unknown type, or a type missing one of its required fields — answers FLK-0948. Flowker does not call your target API here. It does read the referenced document and, when config.auth contains a secret, writes that secret to the configured secrets backend before it persists the configuration.

Step 4: Address an operation from a workflow node

---

An executor node names one operation of the document with two fields in its data, alongside the providerConfigId of the configuration from Step 3.

Field	Required	Description
providerConfigId	Yes	The UUID of the provider configuration that points at the document.
operation_path	To run	The operation path, exactly as the document writes it, including its {...} parameter templates.
operation_method	To run	The operation’s HTTP method. Matching is case-insensitive.
inputMapping	No	Moves values from the workflow context into the request. Each target is a path in the operation’s request body, or a parameter name.
outputMapping	No	Moves values out of the response for later nodes to read.

Do not send executorId on such a node. Flowker resolves the provider configuration, recognises the kind, and fills the field in for you before it validates the workflow. The save path can persist a node missing either operation field, but execution then fails with FLK-0950 before Flowker sends a request. Every other node field behaves as Reference the provider configuration from a workflow node describes.

How the request is assembled

Flowker reads the operation out of the stored document at run time and builds the request from it:

• The destination is config.base_url when the configuration sets it, otherwise the first usable servers entry of the document, joined with operation_path.
• A path parameter takes its value from the node’s resolved data first, and from the request body second. Every path parameter needs a value.
• A query or header parameter resolves the same way, and is left out when no value is found.
• The request body with the default request_format (json) is what your inputMapping builds. xml_converted serializes that mapped object as XML; xml_passthrough ignores the mapping and forwards the webhook trigger’s original XML bytes. Write each target exactly as the operation’s request schema names it — there is no wrapper object and no prefix to add. Working with request and response data covers mappings and transformations in full.

Example — a workflow that calls two operations of the document

POST /v1/workflows

{
  "name": "kyc-check",
  "description": "Opens a KYC check on the Acme API and records the result.",
  "nodes": [
    {
      "id": "kyc-received",
      "type": "trigger",
      "name": "KYC request received",
      "position": { "x": 0, "y": 0 },
      "data": {
        "triggerType": "webhook",
        "path": "kyc/requested",
        "method": "POST",
        "input_contract": "open",
        "format": "json"
      }
    },
    {
      "id": "open-check",
      "type": "executor",
      "name": "Open KYC check",
      "position": { "x": 200, "y": 0 },
      "data": {
        "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
        "operation_path": "/v1/checks",
        "operation_method": "POST",
        "inputMapping": [
          { "source": "workflow.documentNumber", "target": "documentNumber" },
          { "source": "workflow.fullName", "target": "fullName" }
        ],
        "outputMapping": [
          { "source": "body.checkId", "target": "checkId" },
          { "source": "body.status", "target": "status" }
        ]
      }
    },
    {
      "id": "record-check",
      "type": "action",
      "name": "Record the check",
      "position": { "x": 400, "y": 0 },
      "data": {
        "actionType": "set_output",
        "output": {
          "checkId": "${open-check.checkId}",
          "status": "${open-check.status}"
        }
      }
    }
  ],
  "edges": [
    { "id": "e1", "source": "kyc-received", "target": "open-check" },
    { "id": "e2", "source": "open-check", "target": "record-check" }
  ]
}

The open-check node sends POST https://api.acme-kyc.example.com/v1/checks with the body its inputMapping built. Its outputMapping lifts two response fields, so the next node reads ${open-check.checkId}.

A node that calls GET /v1/checks/{checkId} instead reads the parameter from the same node scope. Map a value onto checkId, and Flowker substitutes it into the path.

A webhook trigger can validate the inbound payload against one operation of the same document. Set input_contract to "openapi" and give the trigger openapi_schema_id, operation_path and operation_method — see Configuring a webhook trigger.

Step 5: Run it and confirm it worked

---

1. Activate the workflow

   Call Activate a workflow. Activation registers the webhook route and resolves what the trigger’s contract references.

2. Run it

   Call Execute a workflow with a fresh Idempotency-Key header, or send a request to the webhook route.

3. Read the step results

   A node that reached your service records the response under its own id. With an outputMapping, the mapped names sit directly under that id — open-check.checkId. With no outputMapping, the node’s output keeps the response envelope, so the response body sits one level down, under body.

Publishing a new version of your document

---

A stored document does not change. To ship a revision, upload the file again under a new version; that gives you a second stored document with its own id.

Uploading a new document does not change existing configurations. However, each executor node reads its provider configuration when it runs. Updating config.openapi_schema_id can change the document used by later nodes of an in-progress execution, so coordinate the cutover. Send the provider configuration’s config with the new id through Update a provider configuration. config replaces the stored map rather than merging into it, so include any configured base_url and auth values that you need to retain in the same call. Flowker revalidates the new id against your tenant, and answers FLK-0947 when it does not resolve.

Check List resources referencing an OpenAPI schema on the previous document before you retire it. The response is a display list, not a complete inventory: it returns up to 100 entries in each of its two groups. An active provider configuration beyond that display limit still blocks deletion.

Spec versions for the services in the catalog

---

Flowker’s own catalog services resolve against a separate, shared registry of published specs. Three operations manage it. They never touch a document you uploaded in Step 1.

Operation	What it does
List OpenAPI spec versions	Lists the published versions of a service’s spec in versions, and reports the one your tenant has pinned in pinnedVersion. pinnedVersion is empty when your tenant has pinned none.
Pin an OpenAPI spec version	Selects the version your tenant resolves against for that service. It is idempotent: pinning again replaces the version in place. A request missing the service or the version answers FLK-0801.
Upload an OpenAPI spec version	Publishes one version of a service’s spec, for every tenant. Versions are immutable: a service and version pair that already exists answers FLK-0803. The caller needs the create permission on the catalog resource.

The pin is per tenant. Publishing a version changes nothing for a tenant until that tenant pins it, so a new upload never moves a running workflow onto a different spec. Flowker reads your pinned version when it reports that service’s executor schemas in the catalog, so Get a catalog executor describes the version you chose.

Removing a document

---

1. Check what would break

   List resources referencing an OpenAPI schema returns two groups, providerConfigurations and workflows. Both are always present, each carries up to 100 entries, and each entry carries an id, a name and a status. It is a display list, not a complete inventory: an active provider configuration beyond the display limit still blocks the delete, while an inactive entry only warns.

2. Delete it

   Delete an OpenAPI schema answers by what still references the document:

   Outcome	What it means
   204 No Content	Nothing referenced the document. It is gone.
   200 OK	Only inactive referrers held it — a draft or inactive workflow, or a disabled provider configuration. The document is gone, and the body shows its warnings under warnings and providerConfigurationWarnings; provider-configuration display details can be capped at 100.
   409 with FLK-0945	An active provider configuration binds the document. Nothing is deleted, and the body shows the referring provider configurations and workflows; provider-configuration display details can be capped at 100.
   409 with FLK-0936	An active workflow references the document from a webhook trigger. Nothing is deleted.

To clear a block, disable the provider configuration or deactivate the active workflow. Move an inactive workflow to draft only if you need to edit it.

What goes wrong

---

Symptom	Cause	Fix
The upload is refused although the file opens in your editor.	The document declares an openapi version outside the 3.x series, or declares no operation.	Check the openapi field and the paths object, then upload again.
The create call reports the schema id is unknown.	The id belongs to another tenant, or the document was deleted.	Call List OpenAPI schemas and take the id from the response.
The workflow is refused with FLK-0150.	The node’s providerConfigId names a configuration that does not exist, or one that is disabled.	Confirm the UUID on the node, and enable the configuration with Enable provider configuration.
The node fails without reaching your service.	The operation is absent from the document, or no base URL resolves.	Compare operation_path and operation_method with the operations list from Step 2, and set config.base_url when the document declares no servers entry.
The service answers that a required field is missing.	A mapping target does not match the operation’s request schema.	Read inputSchema from Derive an operation schema and write each target exactly as it appears there.
The service is never reached and the step reports a rejected URL.	allowedHosts does not cover the destination host.	Add the host to allowedHosts on the provider configuration.

Error code	When	What it means
FLK-0150	Create or activate the workflow	The node’s providerConfigId names a configuration that does not exist, or one that is not active.
FLK-0812	Upload	A document with this name and version already exists. Choose another version.
FLK-0900	Upload	The file does not parse as an OpenAPI 3.x document, or it declares no operation.
FLK-0901	Upload	The file is over 8 MiB.
FLK-0811	Read, derive, delete	The document id does not resolve for your tenant.
FLK-0902	Derive an operation schema	The document declares no operation with that path and method.
FLK-0304	Derive an operation schema	The path query parameter is missing, or method is missing or is not an HTTP method.
FLK-0946	Create or update the provider configuration	config.openapi_schema_id is missing, or is not a UUID.
FLK-0947	Create or update the provider configuration, and run time	The referenced document does not exist in your tenant.
FLK-0948	Create or update the provider configuration	The config.auth block is malformed.
FLK-0293	Create or update the provider configuration	A schemaBindings entry is malformed.
FLK-0942	Create or update the provider configuration	A schemaBindings entry names a document that does not exist in your tenant.
FLK-0943	Create or update the provider configuration	A schemaBindings entry restricts to an operation the document does not declare.
FLK-0949	Run time	Neither config.base_url nor a usable servers entry resolves a base URL. The node fails without calling the service.
FLK-0950	Run time	The bound operation is absent from the document, or a path parameter found no value. The node fails without calling the service.
FLK-0945	Delete the document	An active provider configuration binds it.
FLK-0936	Delete the document	An active workflow references it from a webhook trigger.
FLK-0803	Upload a spec version	That service and version pair is already published. Versions are immutable.
FLK-0801	Pin a spec version	The request is missing the service or the version.

See the Flowker error list for every code.

What’s next

---

Working with request and response data

Map values into the operation’s request body and read its response back out.

Configuring a webhook trigger

Validate an inbound payload against one operation of the same document.

Integration guide

Set the authentication, the retries and the circuit breaker every provider configuration shares.

OpenAPI schemas API

Explore the schema registry endpoints.