Using fetch-url and api-call steps

Make HTTP requests to external APIs and services using fetch-url (for straightforward requests) or api-call (for full HTTP control with response mapping).

Fetch URL step

Use for HTTP requests to external URLs. Supports GET, POST, PUT, DELETE, and PATCH methods.

Add a fetch-url step

1. In the Flow editor, click Add Step
2. Select Fetch URL
3. Configure:
   • Name: Descriptive label (e.g., “Get Product data”)
   • URL: The endpoint to call
   • Method: The HTTP method to use — GET, POST, PUT, DELETE, or PATCH. Defaults to GET.
   • Body: The request payload. This field appears only when the method is POST, PUT, or PATCH, and accepts {{variable}} mentions like the URL field.
4. Click Save Step

Example:

https://api.example.com/Products/{{productId}}

The step returns the response body.

Switching the method back to GET or DELETE hides the body field without clearing its stored value, so you can toggle methods without losing your payload. See Request body for the canonical body format.

API Call step

Use for full HTTP control: POST, PUT, DELETE, custom headers, authentication.

Add an api-call step

1. Click Add Step
2. Select API Call
3. Configure:
   • Name: Descriptive label
   • Method: GET, POST, PUT, DELETE, etc.
   • URL: Endpoint URL
   • Headers: HTTP headers (optional)
   • Body: Request body (for POST/PUT)
4. Click Save Step

Setting headers

Add headers as key-value pairs:

Content-Type: application/json
Authorization: Bearer {{secret:API_KEY}}
X-Custom-Header: {{customValue}}

Request body

For POST/PUT requests, provide the body as JSON:

1
{
2
  "customer": "{{customerName}}",
3
  "order": {
4
    "items": "{{order_items}}",
5
    "total": "{{calculate_total}}"
6
  }
7
}

Authentication

Bearer token

Authorization: Bearer YOUR_API_KEY

Basic auth

Encode username:password in base64:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

API key in header

X-API-Key: YOUR_API_KEY

Do not hardcode API keys in Flows. Use Runtype’s secrets management to store credentials securely and reference them with {{secret:SECRET_NAME}} syntax.

Handling responses

Access response data in later steps using the step’s outputVariable name:

{{api_response}}                // Full response body
{{api_response.data}}           // Nested property

Error handling

API calls can fail. Configure error handling on the step itself (continue on error, stop on error, or use fallbacks), or use a conditional step to check the result before proceeding.

Dynamic URLs

Build URLs from variables:

https://api.example.com/{{resource}}/{{itemId}}?filter={{searchTerm}}

Common patterns

REST API integration

Method: POST
URL: https://api.service.com/v1/items
Headers:
  Content-Type: application/json
  Authorization: Bearer {{apiKey}}
Body:
{
  "name": "{{itemName}}",
  "value": "{{itemValue}}"
}

Webhook notification

Method: POST
URL: https://hooks.example.com/notify
Body:
{
  "event": "flow_completed",
  "data": "{{final_output}}"
}

External data lookup

Method: GET
URL: https://api.database.com/lookup?id={{customerId}}
Headers:
  X-API-Key: {{secret:DB_API_KEY}}

Rate limiting

Some APIs rate-limit requests. Add Wait Until steps between API calls if needed:

1. API call step
2. Wait Until step with delayMs (e.g., 1000 for a 1-second pause)
3. Next API call

Testing API calls

Use the step tester to verify requests without running the full Flow:

1. Click Test on the API step
2. Provide sample variables
3. Review the actual HTTP request sent
4. Check the response

Best practices

• Validate responses: Check status codes before using response data
• Handle errors gracefully: Use conditionals for retry logic or fallbacks
• Keep secrets secret: Never log or expose API keys
• Set timeouts: Configure step timeouts to avoid hanging on slow APIs

Next steps

• Using transform-data steps to process API responses
• Using conditional steps for error handling
• Flow variables and templates for building dynamic requests