Skip to main content

​
API Request Tool

The API Request tool allows your agents to interact with any REST API endpoint. It provides complete control over HTTP methods, headers, request bodies, and response handling.
API Request Tool Configuration
This tool has Default status, meaning it’s production-ready and available on all subscription plans.

​
Overview

The API Request tool is one of the most versatile tools in PLai Framework, enabling agents to:

Connect to APIs

Integrate with any REST API service or endpoint

Custom Headers

Configure authentication, content types, and custom headers

Flexible Methods

Support for GET, POST, PUT, DELETE, and other HTTP methods

Template System

Dynamic URL and body templating with variable substitution

​
Configuration Parameters

​
url_template
input
required
The API endpoint URL with optional template variables
Example: https://api.example.com/users/{{user_id}}/profile
Variables: Use {{variable_name}} for dynamic substitution
​
method
input
required
HTTP method for the request
Common values: GET, POST, PUT, DELETE, PATCH
Default: GET
​
headers_template
json
required
HTTP headers as a JSON object
Example: {"Authorization": "Bearer {{api_token}}", "User-Agent": "PLai-Agent/1.0"}
Default: {}
​
content_type
select
required
Content type for request body
Options:
  • application/json - For JSON payloads
  • application/x-www-form-urlencoded - For form data
​
body_template
json
required
Request body as JSON template
Example: {"name": "{{user_name}}", "email": "{{user_email}}"}
Default: {}
Note: Only used for POST, PUT, PATCH methods

​
Setup Instructions

1

Navigate to Tools

Go to the Tools section in your project dashboard
2

Create API Request Tool

Click Create Tool and select API Request
3

Configure URL

Enter the API endpoint URL in the URL Template field
4

Set HTTP Method

Specify the HTTP method (GET, POST, etc.) in the Method field
5

Configure Headers

Add required headers including authentication in Headers Template
6

Set Content Type

Choose the appropriate content type for your API
7

Configure Body (if needed)

For POST/PUT requests, configure the Body Template
8

Test Configuration

Use the test button to verify your configuration works
9

Add to Agent

Assign this tool to your agents in agent settings

​
Usage Examples

​
Basic GET Request

{
  "url_template": "https://jsonplaceholder.typicode.com/posts/{{post_id}}",
  "method": "GET",
  "headers_template": {
    "Accept": "application/json",
    "User-Agent": "PLai-Agent/1.0"
  },
  "content_type": "application/json",
  "body_template": {}
}

​
Authenticated API Call

{
  "url_template": "https://api.github.com/user/repos",
  "method": "GET",
  "headers_template": {
    "Authorization": "Bearer {{github_token}}",
    "Accept": "application/vnd.github.v3+json"
  },
  "content_type": "application/json",
  "body_template": {}
}

​
POST Request with Data

{
  "url_template": "https://api.example.com/users",
  "method": "POST",
  "headers_template": {
    "Authorization": "Bearer {{api_token}}",
    "Content-Type": "application/json"
  },
  "content_type": "application/json",
  "body_template": {
    "name": "{{user_name}}",
    "email": "{{user_email}}",
    "role": "user"
  }
}

​
CRM Integration (Salesforce)

{
  "url_template": "https://{{instance}}.salesforce.com/services/data/v57.0/sobjects/Contact",
  "method": "POST",
  "headers_template": {
    "Authorization": "Bearer {{sf_access_token}}",
    "Content-Type": "application/json"
  },
  "content_type": "application/json",
  "body_template": {
    "FirstName": "{{first_name}}",
    "LastName": "{{last_name}}",
    "Email": "{{email}}",
    "Phone": "{{phone}}"
  }
}

​
Common Use Cases

​
Customer Relationship Management (CRM)

  • Create/update leads and contacts
  • Retrieve customer information
  • Update opportunity status
  • Sync customer data

​
Payment Processing

  • Process payments
  • Manage customer subscriptions
  • Handle refunds
  • Retrieve transaction history

​
Communication Services

  • Send messages to channels
  • Create private conversations
  • Post file attachments
  • Manage workspace users

​
Template Variables

​
Variable Substitution

The API Request tool supports dynamic variable substitution in URLs and request bodies: 
{
  "url_template": "https://api.example.com/users/{{user_id}}/orders/{{order_id}}",
  "body_template": {
    "status": "{{new_status}}",
    "updated_by": "{{agent_name}}",
    "timestamp": "{{current_time}}"
  }
}

​
Available Variables

Variables are provided by the agent during execution:
  • User-provided: Variables from chat context or form inputs
  • System variables: Current time, agent name, user ID, etc.
  • Previous responses: Data from earlier tool calls in the conversation
  • Context variables: Information from the current conversation

​
Conditional Logic

Use conditional templating for dynamic behavior: 
{
  "body_template": {
    "action": "{{action_type}}",
    "data": "{{#if user_premium}}{{premium_data}}{{else}}{{basic_data}}{{/if}}"
  }
}

​
Response Handling

​
Response Processing

The API Request tool automatically processes responses:
  1. Status Code Validation: Checks for successful HTTP status codes
  2. Content Parsing: Automatically parses JSON, XML, or text responses
  3. Error Handling: Provides meaningful error messages for failures
  4. Data Extraction: Makes response data available to the agent

​
Response Format

Successful responses are returned in this format: 
{
  "status": 200,
  "headers": {
    "content-type": "application/json",
    "x-rate-limit-remaining": "99"
  },
  "data": {
    "id": 123,
    "name": "John Doe",
    "email": "[email protected]"
  },
  "success": true
}

​
Error Handling

​
Common Error Scenarios

Cause: Invalid or expired API keys, insufficient permissionsSolutions:
  • Verify API key is correct and active
  • Check permission scopes for the API key
  • Ensure proper header format for authentication
  • Confirm the API endpoint supports your authentication method
Cause: Exceeded API rate limitsSolutions:
  • Implement retry logic with exponential backoff
  • Reduce request frequency
  • Upgrade API plan if available
  • Use caching to reduce redundant requests
Cause: Invalid request format or missing required fieldsSolutions:
  • Validate request body against API documentation
  • Check required fields are included
  • Verify data types match API expectations
  • Test with API documentation examples
Cause: Slow API responses or network issuesSolutions:
  • Increase timeout values
  • Implement retry logic
  • Check API status and performance
  • Use alternative endpoints if available

​
Security Best Practices

API Key Security: Never hardcode API keys in templates. Use secure variable substitution instead.

​
Secure Configuration

{
  "headers_template": {
    "Authorization": "Bearer {{secure_api_token}}",
    "X-API-Key": "{{api_key}}"
  }
}

​
Security Checklist

  • Use HTTPS: Always use secure HTTPS endpoints
  • Validate Certificates: Ensure SSL certificate validation
  • Rotate Keys: Regular API key rotation
  • Minimal Permissions: Use API keys with minimal required permissions
  • Monitor Usage: Track API usage for unusual activity
  • Rate Limiting: Implement client-side rate limiting

​
Performance Optimization

​
Caching Strategies

{
  "cache_policy": {
    "enable": true,
    "ttl": 300,
    "key_template": "api_{{endpoint}}_{{user_id}}"
  }
}

​
Optimization Tips

  • Batch Requests: Combine multiple operations when possible
  • Conditional Requests: Use ETags and If-Modified-Since headers
  • Compression: Enable gzip compression for large responses
  • Connection Pooling: Reuse connections for better performance

​
Troubleshooting

​
Debug Mode

Enable detailed logging to troubleshoot issues: 
{
  "debug": true,
  "log_requests": true,
  "log_responses": true
}

​
Testing Tools

Use these approaches to test your configuration:
  1. API Testing Tools: Postman, Insomnia, or curl
  2. Mock Servers: Test with mock API responses
  3. Staging Environments: Test against non-production APIs
  4. Request Logs: Review detailed request/response logs

​
Next Steps

Create Your First API Tool

Follow the step-by-step guide

Advanced Configurations

Learn advanced API tool patterns

Other Tools

Explore other available tools

API Reference

View the tools API documentation