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.

	Custom connector	Built-in HTTP action
Picking an action	Search a named list — “Convert HTML to PDF”	You type the URL yourself
Parameters	Typed fields with descriptions and auto-complete	A JSON body you hand-write
The API key	Entered once on the connection; the platform sends the header	Pasted into every action as an `X-API-Key` header
Licensing	Custom connector (premium)	HTTP action (premium)
Coverage	The actions in the definition	Every endpoint, always

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 250 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.

Sign in and open Portal → Connectors.
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.
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.

The file contains no API key. It declares an X-API-Key header credential, and you supply the key when you create the connection.

Import into Power Automate

Go to make.powerautomate.com → More → Discover all → Custom connectors.
+ New custom connector → Import an OpenAPI file. Not Import from URL — the definition is a download, not a hosted URL.
Name it DocButterfly and upload the file you downloaded.
On the Security tab the API key authentication is already filled in (API Key, parameter label X-API-Key, location Header). Click Create connector.
Test → + New connection, and paste the key from Portal → API Key.
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.

In the Azure portal, create a Logic Apps Custom Connector resource in the region your Logic App lives in.
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.
On the Security step, confirm the API Key definition (header, X-API-Key), then Update connector.
In your Logic App, add an action, choose the Custom tab, pick DocButterfly, and create the connection with your API key.
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:

File in — SharePoint or OneDrive hands you binary content

base64(body('Get_file_content'))

File out — base64 back to a file for Create file

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

One endpoint is the exception: Convert HTML to PDF. Its Return Base64 field defaults to false, and left alone the action hands back the raw PDF bytes rather than a JSON body — so body('Convert_HTML_to_PDF')?['pdf'] is empty and you write a zero-byte file. Set Return Base64 to true on that action. Only Convert HTML to PDF, Vault Fill Form and Vault Fill SF-85 behave this way; every other binary-producing endpoint already returns base64 JSON (#2227).

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.

Method	`POST`
URI	`https://api.docbutterfly.com/api/<EndpointName>` — the exact name is the heading of its reference entry
Headers	`X-API-Key` : your key • `Content-Type` : `application/json`
Body	The endpoint's documented JSON, with dynamic content from earlier steps

HTTP action — the body for one call

{
  "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

2 of the catalog's 250 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:

Endpoint	Why it is not an action
`SftpWatchPoll` SFTP: Poll Watcher	It polls a watcher you already created in the portal, and that watcher runs on its own schedule — so there is nothing for a Power Automate flow to do with it that the watcher is not already doing. It is still live, still billed the same, still in the Orchestrator and the docs, and reachable from the HTTP action with the same X-API-Key.
`AdoUploadAttachment` Azure DevOps: Upload Attachment	It is one half of a two-call pattern — upload the file, then relate the url it returns on an Azure DevOps work item — so on its own it does nothing useful, and Power Automate already has Microsoft's own Azure DevOps connector for work items. DocButterfly's own web form destination calls it server-side. It is still live, still billed the same, and reachable from the HTTP action.

If you have imported the connector before and want to know whether anything changed, compare the spec version in your imported connector with 1.250.52926c — 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.250.52926c. 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.

Download the current definition from Portal → Connectors.
Power Automate: Custom connectors → your connector → Edit → Update from OpenAPI file. Logic Apps: Edit → Upload an OpenAPI file.
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

Symptom	Cause
Import is rejected outright	You chose Import from URL. The definition is a downloaded file — use Import an OpenAPI file.
Actions missing right after import	Power Automate indexes a large action list for a moment. Reopen the step picker.
`401` on every call	The connection carries a wrong key, or the key was regenerated. Recreate the connection.
`402`	The account is out of tokens.
`404` on a call you are sure is right	The request reached the website host instead of `https://api.docbutterfly.com`. See Base URL & hosts.

Prefer to try an action before wiring any of this up? The API Testbed runs endpoints from the browser on our test key, so it costs you nothing and needs no account.