API agents are the simplest way to turn a fixed HTTP request into a reusable node. They do not rely on an LLM prompt or model to decide what to do. Instead, they take inputs, render a request, call the API, and return the response.
Use an API agent when you want a predictable external call like:
looking up data
creating or updating records
calling an internal endpoint
uploading a file to an API
How to build with an existing integration
Add an API node to your automation.
Choose an Integration.
If no relevant integration appears, contact your Deployment Strategist so it can be added.
Custom Host is for your own endpoint or a non-standard API host.
Choose Authentication.
If no relevant auth appears, contact your Deployment Strategist so it can be added.
Add the inputs the request needs.
Examples: order_number, patient_info, repo_name
Use @ in editors to insert inputs instead of hardcoding values.
Fill in the URL.
Include the full endpoint and any dynamic path pieces.
Add Query parameters if needed.
Good for filters, pagination, and search terms.
Add HTTP headers if needed.
Good for content type, custom request metadata, or auth headers when your setup requires them.
Choose the Action.
GET for reads
POST for creates
PUT / PATCH for updates
DELETE for deletes
If the method supports a body, choose a Body type.
JSON for most APIs
Multipart Form Data for form-style endpoints and file uploads
Set Output JMESPath if you want to shape the response.
Leave it blank to return the full response.
Use it when downstream steps only need part of the payload.
Example: data.items[*].{id: id, name: name}
Decide whether to enable Cache responses across runs.
This reuses successful identical requests to reduce latency and cost.
The default TTL is 7 days.
Use Try it to test the request before wiring it into the rest of the flow.
How to build with a custom host
Credential Configuration
Tip: Before you start, make sure you have added your API credentials to a 1Password vault, as a Password.
1. Navigate to Workspace settings
2. Click "Add"
3. Click the Credential dropdown menu.
4. Select "1Password for custom API" from the list.
5. Fill in the relevant fields of the Authentication. The name, Vault ID, Item ID, Available Factors and 1Password service account secret name.
6. The Vault ID will be prefilled with the Magical Vault ID. Please replace this with your own.
7. Select "Password" from the options in Available Factors. This assumes your API credential has been set up as a password in 1Password.
8. Click "Add" to save the new authentication.
Creating the API Agent
9. Select "API" from the Environment sidebar.
10. Click "Select integration" in the agent configuration.
11. Click "Custom Host"
12. Select the newly created 1Password authentication.
Tip: Now you can reference the Authentication by using [[@password]] in any of the text fields of the API Agent (ex. Headers, Query Params, or JSON body for a POST request).
Best practices
Keep each API agent focused on one endpoint or one job.
Use inputs for anything that changes run to run.
Keep secrets in saved authentications, not hardcoded in headers or bodies.
Use Output JMESPath to return a clean, small payload for downstream nodes.
Use Multipart Form Data only when the endpoint actually expects it.
Common gotchas
The full form does not really become useful until you pick an integration.
If you switch body type or change to a method without a body, the existing body can be cleared.
JSON bodies must be valid JSON to save correctly.
For custom-host auth, credential factors can appear in the @ menu and be inserted into the URL, headers, or body.