- Get started
- Build
- Deploy and run
- Examples
- Reference
Call an external API
Build a workflow step by step that calls an API with HTTP Request, then reshapes the response with Transform and Script.
What you build
A workflow that calls an authenticated Representational State Transfer (REST) API, handles the response, and makes the extracted data available to the nodes after it. A REST API is a web service that other software can call over HTTP. The pattern applies to any system that exposes an HTTP API.
Before you start
- The target API's base URL, endpoint path, and authentication details (API key, bearer token, or basic auth credentials).
Nodes used
- Manual Trigger: starts the workflow on demand.
- HTTP Request: calls the REST API.
- Transform: extracts the fields needed from the response.
- Script: logs failures on the HTTP Request's error path.
Steps
With a coding agent set up, you can skip the manual steps. Ask it:
Build a Maestro Automate workflow that starts manually with a userId, calls GET https://dummyjson.com/users/{userId} with an HTTP Request node, returns the user's name and email, and logs the error on the node's error path if the call fails.
Build a Maestro Automate workflow that starts manually with a userId, calls GET https://dummyjson.com/users/{userId} with an HTTP Request node, returns the user's name and email, and logs the error on the node's error path if the call fails.
Then open the workflow on the canvas, check it against the steps below, and test it. Set up your coding agent describes the setup.
1. Create a new workflow and add a trigger
Create a project, as Your first workflow describes. The canvas opens with a Manual Trigger already on it.
2. Add and configure the HTTP Request node
- Select the + on the output handle of the Manual Trigger, search for HTTP Request, and select it.
- In the properties panel:
- Set Method to the appropriate verb (
GET,POST,PUT,PATCH, orDELETE). - Enter the full URL of the endpoint.
- Under Headers, add authentication and content-type headers.
- Set Method to the appropriate verb (
For bearer token authentication:
Add a header with the key Authorization and the value Bearer {{ secret.apiKey }}. The secret. prefix reads the value from the secure variable store. The key is never pasted directly into the field.
For basic authentication:
Add a header with the key Authorization and the value Basic {{ secret.encodedCredentials }}, where encodedCredentials is the base64-encoded username:password string.
3. Extract the data you need
- Select the + on the output handle of the HTTP Request node, search for Data Transform, and select it.
- In the properties panel, map the response fields you need from
$vars.httpRequest1.output.bodyto named output variables.
For example, to extract a user's name and email from a response like { "user": { "name": "Alex", "email": "alex@example.com" } }, map:
$vars.httpRequest1.output.body.user.name→userName$vars.httpRequest1.output.body.user.email→userEmail
4. Add error handling
- Select the HTTP Request node, open the Error handling tab, and turn on Enable error handling. An Error handle appears below the main output handle.
- Select the + on the Error handle, search for Script, and select it.
- In the Script node, log the error from
$vars.httpRequest1.error:
const error = $vars.httpRequest1.error;
console.log('API call failed:', error.message, '| Status:', error.status);
return null;
const error = $vars.httpRequest1.error;
console.log('API call failed:', error.message, '| Status:', error.status);
return null;
5. Test and debug
Select Run Debug (▶) in the bottom toolbar of the canvas. In the execution trace:
- Check the HTTP Request node's
codeoutput.200means success;401means your authentication is wrong;404means the URL is incorrect. - Check the Data Transform node's output to confirm the fields were extracted correctly.
- To test the error path, temporarily set the URL to an invalid value and verify the error path executes.
Result
The workflow calls the REST API, extracts the fields from the response, and logs failures on the error path. The execution trace shows the HTTP status code and the extracted values for both paths.
Extend this workflow
- Handle pagination: if the API returns results across multiple pages, add follow-up HTTP Request nodes to fetch additional pages, branching with a Decision on whether the response includes a next-page cursor.
- Write results to another system: after the Data Transform node, add another HTTP Request node or an integration node to push the data downstream.
- Schedule it: replace the Manual Trigger with a Scheduled Trigger to run the workflow on a regular interval.
Next steps
- Deploy a workflow: make the workflow run without you.
- Guides: more workflows to build.
- Community: share what you built, or ask other builders for help.