HTTP API (Generic)

The HTTP API (Generic) tool lets an assistant call external HTTP APIs directly.

It is intended for controlled API integrations when no dedicated connector exists.

Methods

The tool exposes three methods with different risk levels:

• generic_http_request_read (read)
• generic_http_request_write (write)
• generic_http_request_dangerous (dangerous)

This classification drives method permissions in assistant and admin settings.

Assistant Configuration

Connection

• baseUrl: API base URL (for example https://api.example.com)
• authMode: none | bearer | apiKey | basic
• authHeaderName: auth header name (default: Authorization)
• authSecret: secret used for auth (stored encrypted)

Scope & Security

• allowedMethods: allowed HTTP methods (for example only GET, POST)
• allowedHostPatterns: allowed hosts (for example api.example.com, *.example.com)
• allowedPathPrefixes: allowed path prefixes (for example /v1, /api)
• blockedPathPrefixes: explicitly blocked path prefixes (for example /admin)

Request Control

• defaultHeaders (JSON): static headers always sent
• requestTemplates (JSON): predefined request templates
• timeoutMs: request timeout
• maxResponseBytes: hard response size limit
• maxResponseChars: max response characters returned to the model

Request Templates

Templates are useful for clean, reusable, and safer request definitions.

Example:

[
  {
    "name": "listUsers",
    "method": "GET",
    "path": "/v1/users"
  },
  {
    "name": "createTicket",
    "method": "POST",
    "path": "/v1/tickets",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "title": "Example"
    }
  }
]

A tool call can set templateName and optionally override values (query, headers, bodyJson).

Security Behavior

The tool enforces these guardrails:

• Only http/https URLs
• Blocks private/internal hosts (for example localhost, private IP ranges)
• Enforces host allowlist and path policies from settings
• Enforces allowed methods from allowedMethods
• Enforces response size and response length limits

Typical Setup

1. Configure API access with baseUrl + auth
2. Define host/path scopes
3. Add important endpoints as requestTemplates
4. Restrict method permissions to read/write/dangerous

Notes

• For production setups, always define allowedHostPatterns and allowedPathPrefixes.
• Use templates for critical endpoints instead of fully free-form requests.
• There is currently no dedicated connection-test button for this tool.