Skip to main content
Load REST API tools directly from Postman collections, enabling your AI Voice Agent to call external APIs.

​
What are REST API Tools?

REST API tools let your agent:
  • Call external APIs - Integrate with any REST API
  • Load from Postman - Use existing Postman collections
  • Automatic conversion - Each API endpoint becomes a tool
  • No code needed - Just provide the Postman collection

​
Loading from Postman Collections

​
Basic Usage

from kuralit.tools.api import RESTAPIToolkit

# Load tools from Postman collection
api_tools = RESTAPIToolkit.from_postman_collection(
    collection_path="postman_collection.json",
    base_url="https://api.example.com",
    headers={
        "Authorization": "Bearer your-token",
        "Content-Type": "application/json"
    }
)

# Use with agent
from kuralit.server.agent_session import AgentSession

agent = AgentSession(
    tools=[api_tools],
    # ...
)

​
Postman Collection Format

Your Postman collection should follow the standard format: 
{
  "info": {
    "name": "My API Collection"
  },
  "item": [
    {
      "name": "Get User",
      "request": {
        "method": "GET",
        "url": {
          "raw": "{{base_url}}/users/{{user_id}}"
        }
      }
    },
    {
      "name": "Create Note",
      "request": {
        "method": "POST",
        "url": {
          "raw": "{{base_url}}/notes"
        },
        "body": {
          "mode": "raw",
          "raw": "{\"title\": \"{{title}}\", \"content\": \"{{content}}\"}"
        }
      }
    }
  ]
}

​
Configuration

​
Base URL

Set the base URL for all API requests: 
api_tools = RESTAPIToolkit.from_postman_collection(
    collection_path="api.json",
    base_url="https://api.example.com",  # Base URL
)

​
Headers

Add authentication and custom headers: 
api_tools = RESTAPIToolkit.from_postman_collection(
    collection_path="api.json",
    base_url="https://api.example.com",
    headers={
        "Authorization": "Bearer your-token",
        "X-API-Key": "your-api-key",
        "Content-Type": "application/json"
    }
)

​
How It Works

  1. Load Collection - Reads Postman collection JSON
  2. Convert Endpoints - Each API endpoint becomes a tool
  3. Agent Uses Tools - Agent can call APIs based on user requests
  4. Return Results - API responses included in agent responses

​
Example Use Cases

​
Customer Data API

# Load customer API tools
customer_api = RESTAPIToolkit.from_postman_collection(
    collection_path="customer_api.json",
    base_url="https://api.example.com",
    headers={"Authorization": "Bearer token"}
)

agent = AgentSession(
    tools=[customer_api],
    instructions="You have access to customer data APIs. Use them to help users."
)

​
E-commerce API

# Load e-commerce API tools
ecommerce_api = RESTAPIToolkit.from_postman_collection(
    collection_path="ecommerce_api.json",
    base_url="https://api.shop.com",
    headers={"Authorization": "Bearer token"}
)

agent = AgentSession(
    tools=[ecommerce_api],
    instructions="You can help users with products, orders, and shipping."
)

​
Best Practices

​
Collection Organization

  • Group related endpoints - Organize by functionality
  • Clear endpoint names - Descriptive names help the agent
  • Document parameters - Include parameter descriptions in Postman

​
Security

  • Use environment variables - Don’t hardcode API keys
  • Secure headers - Pass authentication via headers
  • Validate responses - Handle API errors gracefully

​
Next Steps