Using fetch-url and api-call steps

Make HTTP requests to external APIs and services using fetch-url (for simple GET requests) or api-call (for full HTTP control).

Fetch URL step

Use for simple GET requests to public URLs.

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
4. Click Save Step

Example:

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

The step returns the response body.

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 {{secrets.apiKey}}
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: {{secrets.dbApiKey}}

Rate limiting

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

1. API call step
2. Delay step (e.g., 1 second)
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