HTTP Tool

Overview

The HTTP tool enables your AI agent to make HTTP requests to external APIs, fetch data, and perform actions on third-party services. This is one of the most powerful tools for extending your agent's capabilities.

Configuration

Basic HTTP Tool

jsonCopy
{
  "name": "fetch_weather",
  "type": "http",
  "description": "Get current weather for a location",
  "config": {
    "method": "GET",
    "url": "https://api.weather.com/v1/current",
    "headers": {
      "X-API-Key": "{{credentials.weather_api_key}}"
    }
  },
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or coordinates"
      }
    },
    "required": ["location"]
  }
}

Configuration Options

Authentication Methods

API Key (Header)

jsonCopy
{
  "config": {
    "headers": {
      "X-API-Key": "{{credentials.api_key}}"
    }
  }
}

API Key (Query Parameter)

jsonCopy
{
  "config": {
    "query": {
      "api_key": "{{credentials.api_key}}"
    }
  }
}

Bearer Token

jsonCopy
{
  "config": {
    "headers": {
      "Authorization": "Bearer {{credentials.access_token}}"
    }
  }
}

Basic Authentication

jsonCopy
{
  "config": {
    "auth": {
      "type": "basic",
      "username": "{{credentials.username}}",
      "password": "{{credentials.password}}"
    }
  }
}

OAuth 2.0

jsonCopy
{
  "config": {
    "auth": {
      "type": "oauth2",
      "credential_id": "salesforce_oauth",
      "token_url": "https://login.salesforce.com/services/oauth2/token",
      "scopes": ["api", "refresh_token"]
    }
  }
}

Request Building

URL Parameters

Use double curly braces for dynamic values:

jsonCopy
{
  "config": {
    "url": "https://api.example.com/users/{{parameters.user_id}}/orders"
  },
  "parameters": {
    "properties": {
      "user_id": {
        "type": "string",
        "description": "The user's ID"
      }
    }
  }
}

Query Parameters

jsonCopy
{
  "config": {
    "url": "https://api.example.com/search",
    "query": {
      "q": "{{parameters.query}}",
      "limit": "{{parameters.limit}}",
      "page": "{{parameters.page}}"
    }
  },
  "parameters": {
    "properties": {
      "query": { "type": "string" },
      "limit": { "type": "integer", "default": 10 },
      "page": { "type": "integer", "default": 1 }
    }
  }
}

Request Body

JSON Body

jsonCopy
{
  "config": {
    "method": "POST",
    "url": "https://api.example.com/contacts",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "name": "{{parameters.name}}",
      "email": "{{parameters.email}}",
      "company": "{{parameters.company}}"
    }
  }
}

Form Data

jsonCopy
{
  "config": {
    "method": "POST",
    "headers": {
      "Content-Type": "application/x-www-form-urlencoded"
    },
    "body_type": "form",
    "body": {
      "field1": "{{parameters.field1}}",
      "field2": "{{parameters.field2}}"
    }
  }
}

Response Handling

Response Mapping

Extract specific fields from the response:

jsonCopy
{
  "response": {
    "mapping": {
      "id": "$.data.id",
      "name": "$.data.attributes.name",
      "items": "$.data.relationships.items[*].id"
    }
  }
}

Response Transformation

Transform the response before returning to the agent:

jsonCopy
{
  "response": {
    "transform": {
      "type": "jmespath",
      "expression": "data.users[*].{id: id, fullName: join(' ', [firstName, lastName])}"
    }
  }
}

Error Handling

jsonCopy
{
  "config": {
    "error_handling": {
      "retry_on": [429, 500, 502, 503, 504],
      "max_retries": 3,
      "retry_delay": 1000,
      "timeout_error_message": "The service is temporarily unavailable"
    }
  }
}

Examples

GET Request - Fetch User Data

jsonCopy
{
  "name": "get_user",
  "type": "http",
  "description": "Retrieve user information by ID",
  "config": {
    "method": "GET",
    "url": "https://api.example.com/users/{{parameters.user_id}}",
    "headers": {
      "Authorization": "Bearer {{credentials.api_token}}"
    }
  },
  "parameters": {
    "type": "object",
    "properties": {
      "user_id": {
        "type": "string",
        "description": "The unique identifier of the user"
      }
    },
    "required": ["user_id"]
  }
}

POST Request - Create Record

jsonCopy
{
  "name": "create_ticket",
  "type": "http",
  "description": "Create a support ticket",
  "config": {
    "method": "POST",
    "url": "https://api.helpdesk.com/tickets",
    "headers": {
      "Authorization": "Bearer {{credentials.helpdesk_token}}",
      "Content-Type": "application/json"
    },
    "body": {
      "subject": "{{parameters.subject}}",
      "description": "{{parameters.description}}",
      "priority": "{{parameters.priority}}",
      "requester_email": "{{parameters.email}}"
    }
  },
  "parameters": {
    "type": "object",
    "properties": {
      "subject": {
        "type": "string",
        "description": "Ticket subject line"
      },
      "description": {
        "type": "string",
        "description": "Detailed description of the issue"
      },
      "priority": {
        "type": "string",
        "enum": ["low", "normal", "high", "urgent"],
        "default": "normal"
      },
      "email": {
        "type": "string",
        "description": "Email of the person requesting support"
      }
    },
    "required": ["subject", "description", "email"]
  }
}

Search API

jsonCopy
{
  "name": "search_products",
  "type": "http",
  "description": "Search product catalog",
  "config": {
    "method": "GET",
    "url": "https://api.store.com/products/search",
    "headers": {
      "X-API-Key": "{{credentials.store_api_key}}"
    },
    "query": {
      "q": "{{parameters.query}}",
      "category": "{{parameters.category}}",
      "min_price": "{{parameters.min_price}}",
      "max_price": "{{parameters.max_price}}",
      "sort": "{{parameters.sort}}",
      "limit": "{{parameters.limit}}"
    }
  },
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search keywords"
      },
      "category": {
        "type": "string",
        "description": "Product category filter"
      },
      "min_price": {
        "type": "number",
        "description": "Minimum price filter"
      },
      "max_price": {
        "type": "number",
        "description": "Maximum price filter"
      },
      "sort": {
        "type": "string",
        "enum": ["relevance", "price_asc", "price_desc", "newest"],
        "default": "relevance"
      },
      "limit": {
        "type": "integer",
        "default": 10,
        "maximum": 50
      }
    },
    "required": ["query"]
  },
  "response": {
    "mapping": {
      "products": "$.results",
      "total": "$.total_count"
    }
  }
}

Security Best Practices

1. Use Credentials Vault

Never hardcode API keys:

jsonCopy
{
  "headers": {
    "Authorization": "Bearer {{credentials.my_api_key}}"
  }
}

2. Validate Parameters

Define strict schemas:

jsonCopy
{
  "parameters": {
    "properties": {
      "email": {
        "type": "string",
        "format": "email",
        "description": "Valid email address"
      },
      "amount": {
        "type": "number",
        "minimum": 0,
        "maximum": 10000
      }
    }
  }
}

3. Allowlist URLs

Restrict to known endpoints:

jsonCopy
{
  "security": {
    "allowed_hosts": [
      "api.example.com",
      "api.trusted-service.com"
    ]
  }
}

4. Rate Limiting

Prevent abuse:

jsonCopy
{
  "rate_limit": {
    "requests_per_minute": 60,
    "requests_per_hour": 1000
  }
}

Testing HTTP Tools

Via UI

1. Go to Agents → Select agent → Tools
2. Click on the HTTP tool
3. Click Test Tool
4. Enter test parameters
5. View request/response details

Via API

bashCopy
curl -X POST "https://api.arcanflows.com/api/v1/agents/{agent_id}/tools/{tool_id}/test" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "user_id": "test123"
    }
  }'

Troubleshooting

401 Unauthorized

• Check credential configuration
• Verify API key is valid
• Check token expiration

404 Not Found

• Verify URL is correct
• Check URL parameter substitution
• Confirm endpoint exists

Timeout Errors

• Increase timeout value
• Check if service is available
• Consider async execution

CORS Errors

• Use server-side requests (not browser)
• Verify allowed origins
• Check CORS headers