> ## Documentation Index
> Fetch the complete documentation index at: https://docs.royaltyport.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Request

> Make HTTP calls to external APIs and services from your automation workflows

## Overview

The API Request step lets you call any external API or web service. Configure the method, URL, headers, authentication, and body to integrate with third-party services or internal APIs.

## Configuration

| Field            | Options                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| **Method**       | GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS                                                    |
| **URL**          | Target endpoint (supports [template variables](/automations/steps/overview#template-variables)) |
| **Headers**      | Key-value header pairs                                                                          |
| **Query Params** | Key-value query parameters                                                                      |
| **Auth**         | None, Basic Auth, Bearer Token, API Key, OAuth2, Royaltyport API                                |
| **Body**         | None, Text (JSON / XML / Raw), or Form (with multipart toggle)                                  |
| **Pagination**   | Optional — automatically page through multi-page API responses                                  |

### Authentication

Select an auth type to attach credentials from your [secrets](/automations/secrets) to the request:

| Auth Type           | Description                                          |
| ------------------- | ---------------------------------------------------- |
| **None**            | No authentication                                    |
| **Basic Auth**      | HTTP basic authentication (username + password)      |
| **Bearer Token**    | Bearer token in the Authorization header             |
| **API Key**         | Custom API key header                                |
| **OAuth2**          | OAuth2 client credentials flow                       |
| **Royaltyport API** | Built-in authentication for the Royaltyport REST API |

### Royaltyport API

The **Royaltyport API** auth type lets you call the [Royaltyport REST API](/api-reference/introduction) directly from your automations without managing tokens or secrets. Authentication is handled automatically using your project's internal credentials — no setup required.

Select **Royaltyport API** from the auth dropdown and point the URL at any `https://api.royaltyport.com/v1/` endpoint. The step injects the correct authorization headers at runtime.

To get started quickly, use one of the built-in Royaltyport presets:

| Preset                       | Endpoint                      |
| ---------------------------- | ----------------------------- |
| Royaltyport — List Projects  | `GET /v1/projects`            |
| Royaltyport — Get Project    | `GET /v1/projects/:id`        |
| Royaltyport — Search Project | `GET /v1/projects/:id/search` |
| Royaltyport — List Contracts | `GET /v1/contracts`           |
| Royaltyport — Get Contract   | `GET /v1/contracts/:id`       |
| Royaltyport — List Entities  | `GET /v1/entities`            |
| Royaltyport — Get Entity     | `GET /v1/entities/:id`        |
| Royaltyport — List Artists   | `GET /v1/artists`             |
| Royaltyport — Get Artist     | `GET /v1/artists/:id`         |
| Royaltyport — List Writers   | `GET /v1/writers`             |
| Royaltyport — Get Writer     | `GET /v1/writers/:id`         |

<Tip>
  Presets fill in the URL, headers, and auth automatically. Combine them with trigger data like `{{trigger.contract_id}}` to make them dynamic.
</Tip>

See the full [API Reference](/api-reference/introduction) for all available endpoints and response schemas.

### Pagination

Enable **Paginate Results** to have the step automatically loop through all pages of a paginated API and collect the full result set before passing data downstream.

<Note>
  When pagination is enabled, do **not** add offset, page, or limit parameters manually in the Params tab — they are injected automatically by the step.
</Note>

| Field                   | Description                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Type**                | **Offset** — increments a numeric offset each page. **Page Number** — increments a page number starting from 1.                      |
| **Offset / Page Field** | Query parameter name the API expects for the offset or page number (e.g. `offset`, `page`)                                           |
| **Limit Field**         | Query parameter name the API expects for the page size (e.g. `limit`, `per_page`)                                                    |
| **Results Path**        | Dot-path to the array of items inside the response body (e.g. `data.items`). Leave blank if the response body is the array directly. |
| **Page Size**           | Number of items to request per page (default: 10)                                                                                    |
| **Max Results**         | Cap on total items collected across all pages. Leave blank for no limit.                                                             |

Pagination works inside [Loop](/automations/steps/loop) steps — each iteration of the loop can run an independent paginated request.

### Body Types

| Type     | Description                                                                   |
| -------- | ----------------------------------------------------------------------------- |
| **None** | No request body (typically for GET requests)                                  |
| **Text** | Raw text body with format selector (JSON, XML, or Raw)                        |
| **Form** | Form data with key-value pairs and optional multipart toggle for file uploads |

## Output

| Field             | Type    | Description                                                                       |
| ----------------- | ------- | --------------------------------------------------------------------------------- |
| `request`         | object  | Details of the outgoing request (see below)                                       |
| `request.method`  | string  | HTTP method used (e.g. `GET`, `POST`)                                             |
| `request.url`     | string  | Final resolved URL including any template variables                               |
| `request.headers` | object  | Request headers sent. The `Authorization` header is partially masked for security |
| `request.body`    | any     | Request body sent, or `null` for bodyless requests                                |
| `status`          | number  | HTTP status code                                                                  |
| `headers`         | object  | Response headers                                                                  |
| `body`            | any     | Response body                                                                     |
| `error`           | boolean | Whether an error occurred                                                         |
| `error_message`   | string  | Error description if failed                                                       |

<Note>
  The `Authorization` header in `request.headers` is partially masked (only the first 10 characters are shown). Use `{{steps.my_step.request.url}}` or `{{steps.my_step.request.body}}` in downstream steps to reference what was actually sent.
</Note>