REST API Tools

Sinaptic® DROID+ agents can call external HTTP endpoints as tools. This lets agents interact with any REST API — internal services, third-party APIs, webhooks — without writing custom code.

Configuration

Add REST API tools directly in your agent's YAML config:

# configs/agents/my-agent.yaml
name: "my-agent"

tools:
  - name: "get-weather"
    type: "rest_api"
    description: "Get current weather for a city"
    url: "https://api.weather.example.com/current?city=${city}"
    method: "GET"
    headers:
      Authorization: "Bearer ${WEATHER_API_KEY}"
    timeout: "10s"

  - name: "create-ticket"
    type: "rest_api"
    description: "Create a support ticket"
    url: "https://api.example.com/tickets"
    method: "POST"
    headers:
      Content-Type: "application/json"
      Authorization: "Bearer ${INTERNAL_API_KEY}"
    timeout: "15s"

Fields

Field	Type	Required	Description
name	string	yes	Tool identifier (used by the LLM)
type	string	yes	Must be rest_api
description	string	recommended	Description shown to the LLM to help it decide when to use this tool
url	string	yes	Endpoint URL (supports ${VAR} for env vars)
method	string	yes	HTTP method: GET, POST, PUT, DELETE
headers	map	no	HTTP headers to include in the request
timeout	string	no	Request timeout (default: 30s)

How It Works

1. The LLM decides to call a REST API tool based on the tool's name and description
2. Sinaptic® DROID+ makes the HTTP request with the configured method, URL, headers, and any body provided by the LLM
3. The response is returned to the LLM as the tool result
4. The LLM incorporates the result into its response to the user

Security

• REST API tools respect the agent's SinapticAI settings — tool inputs and outputs are scanned for PII and injection attempts
• Use environment variables (${VAR}) for API keys and secrets in headers — never hardcode them
• The timeout field prevents tools from hanging indefinitely on slow endpoints

Examples

Calling an internal microservice

tools:
  - name: "lookup-order"
    type: "rest_api"
    description: "Look up order status by order ID"
    url: "https://internal-api.example.com/orders/${order_id}"
    method: "GET"
    headers:
      X-Service-Token: "${INTERNAL_TOKEN}"
    timeout: "5s"

Sending a webhook

tools:
  - name: "notify-slack"
    type: "rest_api"
    description: "Send a notification to a Slack channel"
    url: "${SLACK_WEBHOOK_URL}"
    method: "POST"
    headers:
      Content-Type: "application/json"
    timeout: "10s"