Power Automate & Logic Apps Connector

What a custom connector gives you

A custom connector teaches Power Automate, Logic Apps and Power Apps how to call a REST API as a first-class action. You import a definition once per environment, create one connection with your API key, and after that DocButterfly behaves like any built-in connector.

The definition currently carries 250 actions in 21 groups, generated straight from the same catalog that produces the API Reference — so an action list and the reference can never disagree.

Get the definition

The connector definition is a Swagger 2.0 JSON file, generated live. It is on the Connectors page in your portal, which needs an account — signing up is free and the file is ready the moment you land there.

1. Sign in and open Portal → Connectors.
2. Click Download Connector Definition. The filename carries the spec version, so you can always tell which one you imported — currently docbutterfly-connector-v1.250.52926c.swagger.json.
3. Optional: once you have published a workflow in the Orchestrator, the same page offers a second download that adds one action per published workflow — a whole pipeline as a single step.

Import into Power Automate

1. Go to make.powerautomate.com → More → Discover all → Custom connectors.
2. + New custom connector → Import an OpenAPI file. Not Import from URL — the definition is a download, not a hosted URL.
3. Name it DocButterfly and upload the file you downloaded.
4. On the Security tab the API key authentication is already filled in (API Key, parameter label X-API-Key, location Header). Click Create connector.
5. Test → + New connection, and paste the key from your portal's API Key page.
6. Add a step in any flow, search DocButterfly, and pick an action. Documents travel as base64 strings in both directions — see Sending and saving files.

Import into Azure Logic Apps

The same file imports into Logic Apps. It was verified end to end on 2026-09-05: every operation was accepted unmodified, and a Logic App called through the connector and got a real PDF back.

1. In the Azure portal, create a Logic Apps Custom Connector resource in the region your Logic App lives in.
2. Open it → Edit → Upload an OpenAPI file and select the downloaded definition. Leave the host as it is: the definition already names the API host.
3. On the Security step, confirm the API Key definition (header, X-API-Key), then Update connector.
4. In your Logic App, add an action, choose the Custom tab, pick DocButterfly, and create the connection with your API key.
5. Logic Apps Standard: keep the key in an app setting and reference it with @appsetting('DocButterflyApiKey') rather than typing it into the workflow definition.

Authentication

One header, everywhere: X-API-Key: df_…. The connector declares it as an API-key credential, so Power Automate and Logic Apps prompt for it once when you create the connection and attach it to every call afterwards. Nothing else is needed — there is no OAuth flow, no tenant registration and no consent screen.

A wrong or missing key answers 401. An empty token balance answers 402. A 404 almost always means the request went to the website host rather than the API host — see Base URL & hosts.

Sending and saving files

Documents cross the wire as base64 strings in both directions, which is what makes the connector work the same way in every platform. Two expressions cover almost every flow:

base64(body('Get_file_content'))

base64ToBinary(body('Convert_HTML_to_PDF')?['pdf'])

The field name on the way out is whatever the endpoint documents — pdf, image, file, zip. Each endpoint's reference entry shows a real response sample, so you can read the field name off the page rather than guess it.

Every other endpoint is one HTTP action away

The connector is a convenience, not a gate. Anything it does not carry is still a normal DocButterfly endpoint and is reachable from the same flow with the built-in HTTP action, using the same key. Nothing is ever API-only or connector-only.

{
  "pdf": "@{base64(body('Get_file_content'))}",
  "watermark": { "text": "CONFIDENTIAL" },
  "returnBase64": true
}

Then base64ToBinary(body('HTTP')?['pdf']) into a Create file action, exactly as with a connector step. Keep the key in an environment variable or a Key Vault reference rather than typing it into the flow definition.

How many actions the connector carries, and why that is capped

The Power Platform puts a ceiling on a single custom connector: a maximum number of actions, and a maximum size for the definition file. Crossing either is not a soft failure — the import is simply refused.

DocButterfly's catalog is bigger than it was and keeps growing, so the connector cannot carry every endpoint forever. The plan is deliberate and it is written down here so nobody has to discover it:

• The connector carries the most-used actions, chosen from real usage rather than from a guess about which ones matter.
• It leaves headroom for your own published workflows, which are added as extra actions by the personalized download.
• Everything else stays a first-class endpoint, documented in the API Reference, and is one HTTP action away with the same key. An endpoint never leaves the API — at most it leaves the connector's action list.

Today the connector carries all 250 actions. If you have imported it before and want to know whether anything changed, compare the spec version in your imported connector with 1.250.52926c — see Staying current.

Staying current

The definition carries a spec version of the form {major}.{action-count}.{hash}, currently 1.250.52926c. It moves only when the API surface itself moves — a new endpoint, a renamed or retyped parameter, a changed required flag. If the version you imported still matches the one shown here, there is nothing to do.

1. Download the current definition from Portal → Connectors.
2. Power Automate: Custom connectors → your connector → Edit → Update from OpenAPI file. Logic Apps: Edit → Upload an OpenAPI file.
3. Update the connector. Existing connections and keys survive; only the action definitions are refreshed, and running flows keep working.

If the import misbehaves