APIRAPTOR plugin guide for Bubble
Configure the server-side API key, call any of the eleven named service actions, and handle typed JSON, async jobs and secure files without exposing credentials in the browser.
Connect your Bubble app safely
Every APIRAPTOR action runs on Bubble's server. The app owner supplies the APIRAPTOR key; the plugin does not create accounts, keys or billing records of its own.
Add the plugin to your Bubble app and open Settings > API.
Set APIRAPTOR_API_KEY as a private plugin value. Never expose it in page data, URL parameters or client-side workflows.
Run APIRAPTOR - Check Connection from a workflow before connecting a paid service action.
Choose the named action for the service. Set only fields used by the selected request representation.
Store the returned Request ID. For async execution also store the Job ID and query it with the shared async utilities.
Required private setting
Use the exact plugin setting APIRAPTOR_API_KEY and keep its Private checkbox enabled. Use a dedicated, revocable key for each environment.
Eleven service actions, one contract per service
Select the named action instead of sending a service slug through a generic connector. Bubble exposes the fields and typed response carrier declared for that service contract.
APIRAPTOR - Address Check
Validate and normalize a postal address.
APIRAPTOR - Code Generator
Generate supported barcode and QR code artifacts.
APIRAPTOR - Document Translation
Translate supported documents and text inputs.
APIRAPTOR - DOCX to PDF
Render a DOCX input as PDF.
APIRAPTOR - Email Validation
Validate an email address and return its typed result.
APIRAPTOR - HTML to Image
Render HTML as a supported image format.
APIRAPTOR - Invoice & Receipt Extraction
Extract structured invoice or receipt data.
APIRAPTOR - OCR Extract
Extract text from supported image and PDF inputs.
APIRAPTOR - HTML to PDF
Render HTML as PDF.
APIRAPTOR - PII Redaction
Detect or redact personally identifiable information.
APIRAPTOR - URL to PDF
Render a public URL as PDF.
Available execution modes, input representations and delivery modes differ by service. Use the action's dropdowns and the currentpublic API reference; do not assume that every service supports every branch.
Set only the branch you intend to send
Optional request fields have a matching Set control. Representation and scalar-type selectors make union branches explicit and prevent inactive Bubble expressions from being evaluated.
Execution mode
Choose sync for an immediate result or async for a Job ID only when the selected service exposes that mode.
Request representation
Choose JSON or multipart according to the action contract, then fill only fields belonging to that representation.
Optional values
Turn a field's Set control on before supplying its value. Leave Set off to omit the field from the API request.
Keep Request ID, Job ID and File ID separate
The identifiers have different purposes. Do not pass a Job ID to Secure File Download or treat a Request ID as a completed artifact.
APIRAPTOR - Check Connection
Verify the API key and read the service contract catalog without executing a paid service.
APIRAPTOR - Check Async Job Status
Read the status of an existing Job ID.
APIRAPTOR - Get Async File Result
Resolve the completed result for an existing async file job.
APIRAPTOR - Secure File Download
Read an existing APIRAPTOR File ID as a Bubble File or prepare a browser download.
- 1. Run the service action once and store its Job ID.
- 2. Poll with Check Async Job Status using a bounded workflow schedule.
- 3. After status
succeeded, call Get Async File Result with that Job ID. - 4. If the result contains a File ID, pass that File ID to Secure File Download.
Bounded file input and explicit delivery
File handling is intentionally strict. This protects the private key and prevents the connector from becoming a general-purpose URL fetcher.
Supported Bubble uploader input
A public Bubble File Uploader value is accepted only from Bubble's canonical public CDN or the documented legacys3.amazonaws.com/appforest_uf path. The server performs one bounded read without cookies, credentials or redirects and rechecks MIME type and size before reading the API key or sending a paid request.
Maximum decoded file size: 5 MiB.
Rejected file sources
Private Bubble files, Box values, custom domains and arbitrary URLs are not resolved as Bubble File inputs. A native File returned by the plugin is a workflow value; it is not automatically copied to your Bubble storage or database.
Browser download
Choose browser_download, place the APIRAPTOR File Delivery element on the page, and run its explicit Deliver file action with the returned internal bytes and MIME value. Abrowser_download_pending result means the client-side delivery step is still required; it does not prove that a browser saved the file.
Treat every paid POST as a one-shot operation
Validate inputs before dispatch, preserve identifiers for support, and make retries an explicit business decision.
Never automatically retry an APIRAPTOR_CONNECTOR:execution_outcome_unknown error. The provider request may have completed and may have been billed.
Use Bubble conditions to require valid inputs before the service action. Store the returned Request ID and inspect APIRAPTOR Request Logs before deciding whether a distinct retry is safe.
The APIRAPTOR token ledger is the billing source of truth. Bubble workflow completion alone is not proof of a debit or of a no-charge result.
Need integration help?
Include the APIRAPTOR Request ID, service action name and sanitized error code. Never send your API key, complete document contents or signed download URLs.