OpenAPI (Swagger) definition

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 248 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. The catalog itself has 266 endpoints; the difference is explained below, and every one of them is still callable.

Every action costs the tokens its reference entry states — most cost one — and they come out of the same monthly allowance the rest of the API uses, whether the call arrives through the connector or through an HTTP action. A 402 means the allowance is spent. See Usage & Billing.

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.266.8fa65d.swagger.json.
3. Optional: once you have published a workflow in the Orchestrator, the same page offers a second download that adds your published workflows as extra actions — a whole pipeline as a single step. It adds them up to the connector's operation ceiling of 250, which the 248 DocButterfly actions already use most of, so today 2 of your workflows fit. Past that it keeps the oldest — the ones your existing flows are already built on — and names the ones it left out in the file's own description. Anything left out still runs: POST https://api.docbutterfly.com/api/Webhook/<your-slug> from the built-in HTTP action with the same key. The Connectors page in your portal shows the same arithmetic against your own workflow count before you download.

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 Portal → API Key.
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('Watermark_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 everything that fits. What comes out first is what Microsoft already ships a first-party connector for — a flow that reads a SharePoint file is better served by Microsoft's own SharePoint connector, with your credentials, than by ours. Those endpoints stay in the API and in the Orchestrator, where they are what a pipeline's source and destination pickers are built from.
• It leaves headroom for your own published workflows, which the personalized download adds as extra actions. The ceiling is 250 operations and the 248 actions above already use most of it, so 2 of your workflows fit today — the oldest first. That number is the strongest reason the list above gets shorter, not longer.
• 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.

What is not an action today, and why

18 of the catalog's 266 endpoints are deliberately not connector actions. Each one is live, billed exactly the same, listed in the API Reference, available in the Orchestrator, and one HTTP action away:

If you have imported the connector before and want to know whether anything changed, compare the spec version in your imported connector with 1.266.8fa65d — see Staying current.

Why you cannot find DocButterfly in the connector list

Because it is not there yet. DocButterfly is a custom connector: you import the definition into your own environment, and it appears under Custom rather than in Microsoft's built-in list. Searching the standard action picker for “DocButterfly” before you import will find nothing, and that is expected rather than a fault.

Two consequences worth knowing before you build on it. Your imported connector is your copy, so a new action we ship reaches you when you re-import, not automatically. And a connector imported into one environment is not shared with another — import it into each environment you build in, which is the same file every time.

Staying current

The definition carries a spec version of the form {major}.{endpoint-count}.{hash}, currently 1.266.8fa65d. The middle segment counts the catalog's endpoints, not the connector's actions, so it does not match the action count above and is not meant to. The version moves when the API surface moves — a new endpoint, a renamed or retyped parameter, a changed required flag, or an endpoint leaving the connector's action list. 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, and only the action definitions are refreshed. One thing an update can take away: an action we have removed from the connector stops being available to new steps, and a flow already using it has to move to the HTTP action. When that happens the major segment of the spec version moves, so the version string tells you before the flow does.

If the import misbehaves