# 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](node-manual-trigger.md): starts the workflow on demand.
- [HTTP Request](node-http-request.md): calls the REST API.
- [Transform](node-transform.md): extracts the fields needed from the response.
- [Script](node-script.md): logs failures on the HTTP Request's error path.

## Steps

:::tip Ask your coding agent
With a coding agent set up, you can skip the manual steps. Ask it:

```text
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](set-up-your-coding-agent.md) describes the setup.
:::

### 1. Create a new workflow and add a trigger

Create a project, as [Your first workflow](your-first-workflow.md#1-build-the-workflow) describes. The canvas opens with a **Manual Trigger** already on it.

### 2. Add and configure the HTTP Request node

1. Select the **+** on the output handle of the Manual Trigger, search for **HTTP Request**, and select it.
2. In the properties panel:
   - Set **Method** to the appropriate verb (`GET`, `POST`, `PUT`, `PATCH`, or `DELETE`).
   - Enter the full **URL** of the endpoint.
   - Under **Headers**, add authentication and content-type headers.

**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

1. Select the **+** on the output handle of the HTTP Request node, search for **Data Transform**, and select it.
2. In the properties panel, map the response fields you need from `$vars.httpRequest1.output.body` to 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

1. 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.
2. Select the **+** on the **Error** handle, search for **Script**, and select it.
3. In the Script node, log the error from `$vars.httpRequest1.error`:

```javascript
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 `code` output. `200` means success; `401` means your authentication is wrong; `404` means 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](node-decision.md) 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](node-scheduled-trigger.md) to run the workflow on a regular interval.

## Next steps

- [Deploy a workflow](deploy-a-workflow.md): make the workflow run without you.
- [Guides](guides.md): more workflows to build.
- [Community](community.md): share what you built, or ask other builders for help.