Articles on: Tools

API Tool Configuration

What is an API Tool Action?

An API Tool Action lets your custom tool make HTTP requests to external web services. You can call REST APIs, fetch data from websites, send data to other systems, and integrate with third-party services.

Common use cases:

  • Fetching data from your company's internal APIs
  • Sending data to external services (CRM, analytics, etc.)
  • Querying databases through REST endpoints
  • Integrating with SaaS platforms
  • Retrieving information from web services

What you can do:

  • Make GET requests to fetch data
  • Make POST requests to create records
  • Make PUT/PATCH requests to update data
  • Make DELETE requests to remove records
  • Add custom headers (authentication, content types, etc.)
  • Include URL parameters for filtering and pagination
  • Send request bodies with data


Adding an API Action to Your Tool

  1. In your Custom Tool, click "Add Action"
  2. Select "API" as the action type
  3. Enter a descriptive action name (e.g., fetchCustomer, createOrder)
  4. Configure the API request settings (see below)
  5. Click "Add" or "Save"


Configuring Your API Request

When you add an API action, you'll see several configuration options:


1. HTTP Method

Choose the type of HTTP request to make:

  • GET - Retrieve data from a service
    • Best for: Fetching records, searching, reading data
    • Example: Get customer details, list orders, search products
  • POST - Create new data or trigger actions
    • Best for: Creating records, submitting forms, triggering webhooks
    • Example: Create a new customer, submit an order, send a notification
  • PUT - Replace or update entire records
    • Best for: Updating all fields of a record
    • Example: Update a customer profile completely
  • PATCH - Update specific fields of a record
    • Best for: Modifying only some fields
    • Example: Update just the email address of a customer
  • DELETE - Remove data
    • Best for: Deleting records, canceling items
    • Example: Delete a draft, remove an item from a list


Which method should you use?

  • If you're reading data → GET
  • If you're creating something new → POST
  • If you're changing existing data → PUT or PATCH
  • If you're removing something → DELETE

2. URL

Enter the complete web address (URL) for the API endpoint you want to call.

Requirements:

  • Must be a valid URL starting with <http://> or <https://>
  • Must include the full domain and path
  • Can include handlebar variables for dynamic values

Examples:

https://api.example.com/customers/{{customerId}}

https://myapp.com/api/v1/orders

https://api.service.com/data?type={{dataType}}


Using dynamic values in URLs:

Use handlebar syntax to insert inputs or previous action outputs:

https://api.example.com/users/{{userId}}/orders/{{orderId}}

This allows your tool to call different URLs based on inputs or earlier results.

3. URL Parameters (Optional)

URL parameters (also called query parameters) are added to the end of your URL as ?key=value pairs.

When to use URL parameters:

  • Filtering results: ?status=active
  • Pagination: ?page=1&limit=10
  • Sorting: ?sort=date&order=desc
  • Search queries: ?search=keyword
  • API keys or tokens: ?apiKey=abc123

How to add URL parameters:

  1. In the URL Parameters section, click "Add Parameter"
  2. Enter the Key (parameter name)
  3. Enter the Value (can use handlebars)
  4. Repeat for additional parameters


Example:

If you add these URL parameters:

  • Key: status, Value: active
  • Key: limit, Value: 10

And your URL is: <https://api.example.com/orders>

The actual request will go to:

https://api.example.com/orders?status=active&limit=10

Using dynamic parameter values:

Key: userId
Value: {{currentUser}}

4. Headers (Optional)

Headers provide additional information about your request. They're commonly used for authentication, content types, and custom API requirements.

Common headers you might need:

  • Authentication
Key: Authorization
Value: Bearer {{apiToken}}
  • Content Type (tells the API what format you're sending)
Key: Content-Type
Value: application/json
  • Accept (tells the API what format you want back)
Key: Accept
Value: application/json
  • API Keys
Key: X-API-Key
Value: {{apiKey}}
  • Custom Headers (specific to the API you're calling)
Key: X-Custom-Header
Value: some-value

How to add headers:

  1. In the Headers section, click "Add Header"
  2. Enter the Key (header name)
  3. Enter the Value (can use handlebars)
  4. Repeat for additional headers


Tips:

  • Check the API documentation for required headers
  • Use handlebars for sensitive values like tokens: {{apiKey}}
  • Don't hardcode secrets - use tool inputs instead
  • Content-Type is often required for POST/PUT/PATCH requests

5. Request Body (POST, PUT, PATCH, DELETE)

The request body contains the data you want to send to the API. This field is available for POST, PUT, PATCH, and DELETE methods (not GET).

Note: While the body field is available for DELETE requests, not all APIs support request bodies with DELETE. Check your API's documentation before including a body with DELETE requests.

When to use the request body:

  • Creating new records with initial data
  • Updating existing records with new values
  • Sending structured data to an API
  • Submitting form data as JSON

Common format: JSON

Most modern APIs expect JSON format:

{
  "firstName": "{{firstName}}",
  "lastName": "{{lastName}}",
  "email": "{{email}}",
  "age": {{age}},
  "active": {{isActive}}
}


Important formatting rules:

  • Strings must be in quotes: "{{textValue}}"
  • Numbers should NOT have quotes: {{numberValue}}
  • Booleans should NOT have quotes: {{booleanValue}}
  • Use valid JSON syntax (commas, braces, brackets)

Example: Creating a customer

{
  "customer": {
    "name": "{{customerName}}",
    "email": "{{customerEmail}}",
    "phone": "{{phoneNumber}}",
    "metadata": {
      "source": "agent",
      "priority": "{{priority}}"
    }
  }
}

Using outputs from previous actions:

{
  "userId": "{{getUserAction.userId}}",
  "orderId": "{{createOrderAction.orderId}}",
  "total": {{calculateTotalAction.amount}}
}

Tips:

  • Test your JSON syntax in the Action Tester
  • Reference the API documentation for expected structure
  • Use handlebars for all dynamic values
  • Remember that {{value}} outputs exactly what the value is (string, number, object, etc.)

6. Timeout

Controls how long to wait for the API to respond before giving up.

  • Range: 10 to 300 seconds (5 minutes)
  • Default: 30 seconds
  • Recommendation: Start with 30 seconds, increase only if needed


When to adjust:

  • Increase timeout if the API is slow and requests fail with timeout errors
  • Decrease timeout if you want faster failures for unresponsive APIs
  • Keep default for most standard API calls

Common scenarios:

  • Fast APIs (user lookups, searches): 10-30 seconds
  • Standard APIs (CRUD operations): 30-60 seconds
  • Slow APIs (report generation, batch processing): 60-300 seconds

What You Get Back

When your API action executes, it returns a result object with two properties:

{
  "responseBody": {...},    // The data returned by the API
  "responseStatus": 200     // HTTP status code
}

Understanding response status codes:

  • 200-299 - Success
    • 200: OK - Request succeeded
    • 201: Created - New resource was created
    • 204: No Content - Success but no data returned
  • 400-499 - Client errors (something wrong with your request)
    • 400: Bad Request - Invalid data or format
    • 401: Unauthorized - Authentication failed
    • 403: Forbidden - Not allowed to access this resource
    • 404: Not Found - Resource doesn't exist
    • 429: Too Many Requests - Rate limit exceeded
  • 500-599 - Server errors (something wrong with the API)
    • 500: Internal Server Error - API had an error
    • 502: Bad Gateway - API is down or unreachable
    • 503: Service Unavailable - API is temporarily offline

Accessing the response in later actions:

If your API action is named fetchUser, you can access its response:

  • {{fetchUser.responseBody}} - The entire response data
  • {{fetchUser.responseBody.userId}} - A specific field from the response
  • {{fetchUser.responseStatus}} - The HTTP status code

Testing Your API Action

Before using your API action in production, test it to make sure it works correctly.

To test an individual action:

  1. Click the "Test" button at the bottom of the action editor
  2. Provide sample values for any handlebar variables
    • Tool inputs (e.g., {{customerId}})
    • Previous action outputs (e.g., {{previousAction.field}})
  1. Click "Run Test"
  2. Review the response

To test the entire tool:

  1. Click the "Test Tool" button at the top right of the page
  2. Provide values for all tool inputs
  3. Review the complete execution flow and results


What to check:

  • Response status is 200-299 (success)
  • Response body contains the expected data
  • All required fields are present
  • Data types are correct (strings, numbers, etc.)
  • No error messages in the response

Troubleshooting API Actions

Problem: "Invalid URL" error when saving

  • Cause: URL doesn't start with <http://> or <https://> or has invalid format
  • Solution: Ensure your URL is complete and properly formatted. Example: <https://api.example.com/data>

Problem: API call returns 401 Unauthorized

  • Cause: Authentication failed - missing or invalid credentials
  • Solution:
    • Check that you've added the correct Authorization header
    • Verify your API key/token is valid
    • Make sure you're using the right authentication method (Bearer token, API key, etc.)

Problem: API call returns 404 Not Found

  • Cause: The endpoint URL doesn't exist or is incorrect
  • Solution:
    • Double-check the URL in the API documentation
    • Verify any URL parameters or path variables are correct
    • Test the URL directly in a tool like Postman or your browser

Problem: API call returns 400 Bad Request

  • Cause: The request body or parameters have incorrect format or missing required fields
  • Solution:
    • Review the API documentation for required fields and format
    • Check your JSON syntax in the request body
    • Verify all required parameters are included
    • Ensure data types are correct (strings in quotes, numbers without quotes)

Problem: Timeout errors

  • Cause: The API is taking longer than your timeout setting allows
  • Solution:
    • Increase the timeout setting
    • Check if the API is experiencing performance issues
    • Consider if the request could be optimized (fewer records, better filters)

Problem: Handlebars not replaced (showing {{variableName}} in response)

  • Cause: Variable name doesn't match an input or previous action name
  • Solution:
    • Verify the spelling of your variable names
    • Check that the input or action name exists
    • Ensure the action you're referencing comes before the current action

Problem: Getting unexpected data types

  • Cause: Handlebars are quoted when they shouldn't be (or vice versa)
  • Solution:
    • For strings: Use quotes → "{{stringValue}}"
    • For numbers: Don't use quotes → {{numberValue}}
    • For booleans: Don't use quotes → {{booleanValue}}
    • For objects/arrays: Don't use quotes → {{objectValue}}

Problem: CORS errors

  • Cause: The API doesn't allow requests from web applications (browser security)
  • Solution: This is a limitation of the API. Contact the API provider or consider using a proxy service


API Action Security Tips


1. Never hardcode sensitive credentials

❌ Bad:
Authorization: Bearer abc123secrettoken456

✅ Good:
Authorization: Bearer {{apiToken}}

Then pass apiToken as a tool input.

2. Use HTTPS, not HTTP

  • Always use <https://> URLs when available
  • HTTP sends data unencrypted and is less secure

3. Store secrets securely

  • Don't share tools containing hardcoded API keys
  • Use tool inputs for sensitive values
  • Rotate API keys regularly

4. Validate before sending sensitive data

  • Test with non-sensitive data first
  • Verify the API endpoint is correct
  • Check that you trust the service you're calling

5. Handle errors to avoid exposing sensitive information

  • Use Catch Actions to provide generic error messages
  • Avoid logging full request/response bodies containing secrets

Updated on: 03/11/2025

Was this article helpful?

Share your feedback

Cancel

Thank you!