Skip to main content
Connect to any REST API that returns JSON data, enabling integration with internal systems, custom services, or APIs without dedicated connectors.

​
Tools

Tools for the Custom REST API connector are user-configured per deployment. Unlike other connectors with predefined tools, you define the API endpoints Humm can access based on your specific needs. Each tool you configure maps to an API endpoint and includes:
  • Tool name and description (used by the AI to understand when to use it)
  • HTTP method and endpoint path
  • Parameters (query, path, or body)
  • Response parsing configuration
See Configuring Custom Tools below for details.

​
Authentication

API Key

Pass API key via header or query parameter.

Bearer Token

Authorization header with bearer token.

Basic Auth

Username and password authentication.

Token Exchange

OAuth2-style token exchange for APIs requiring credential-based token refresh.

​
Token Exchange Authentication

Token Exchange authentication supports APIs that require exchanging credentials for a short-lived access token. This is common in OAuth2-style APIs where you authenticate with a username/password or client credentials to receive a bearer token. Configuration fields:
FieldDescription
token_exchange_usernameUsername for token exchange (stored securely)
token_exchange_passwordPassword for token exchange (stored securely)
token_exchange_endpointAPI endpoint for exchanging credentials (e.g., /api/authentication)
token_exchange_methodHTTP method for token exchange (POST or GET)
token_exchange_bodyJSON body template with variable substitution
token_response_pathJSONPath to extract token from response (e.g., accessToken, data.token)
token_expiry_pathOptional JSONPath to extract expiry timestamp (Unix timestamp)
token_expiry_bufferSeconds before expiry to refresh token (default: 300)
Variable substitution: The request body supports ${variable} syntax for injecting sensitive values:
  • ${username} - Injects the configured username
  • ${password} - Injects the configured password
Example configuration: 
{
  "token_exchange_endpoint": "/api/authentication",
  "token_exchange_method": "POST",
  "token_exchange_body": "{\"strategy\": \"local\", \"login\": \"${username}\", \"password\": \"${password}\"}",
  "token_response_path": "accessToken",
  "token_expiry_path": "authentication.payload.exp",
  "token_expiry_buffer": 300
}

​
Endpoint Configuration

​
Test Endpoint

Configure a specific endpoint for testing connectivity. If not specified, the first custom tool is used.
FieldDescription
test_endpointEndpoint path for connection testing (e.g., /api/health)
test_paramsJSON object of query parameters to include in test request

​
Introspection Endpoint

Configure automatic schema discovery to help Humm understand your API’s data structures.
FieldDescription
introspection_endpointEndpoint for schema discovery (e.g., /api/data)
introspection_paramsJSON query parameters for schema discovery (e.g., {"limit": 1})
introspection_cache_ttlHow long to cache introspection results in seconds (default: 3600)
introspection_max_depthMaximum nesting depth for nested objects (1-10, default: 3)
introspection_data_keyField name containing the data array (e.g., data, results, items)

​
Configuring Custom Tools

Custom tools define the API endpoints Humm can access. Each tool maps to a specific API operation.

​
Tool Definition Schema

{
  "name": "GET_CUSTOMERS",
  "description": "Retrieve a list of customers with optional filtering",
  "endpoint": "/api/v1/customers",
  "method": "GET",
  "parameters": [
    {
      "name": "limit",
      "type": "integer",
      "required": false,
      "description": "Maximum number of results to return",
      "default": 100
    },
    {
      "name": "status",
      "type": "string",
      "required": false,
      "description": "Filter by customer status (active, inactive)"
    }
  ],
  "query_parameters": ["limit", "status"],
  "response_data_path": "data.customers"
}

​
Tool Fields

FieldDescription
nameUnique tool name (convention: VERB_RESOURCE, e.g., GET_ORDERS)
descriptionDescription for the AI explaining what this tool does
endpointAPI endpoint path, supports path parameters like /users/{user_id}
methodHTTP method: GET, POST, PUT, PATCH, or DELETE
parametersArray of parameter definitions
path_parametersParameter names that appear in the endpoint URL
query_parametersParameter names sent as query string
body_parametersParameter names sent in request body
body_templateTemplate for complex request bodies (supports {param} substitution)
response_data_pathJSONPath to extract data from response (e.g., data.records)
enabled_by_defaultWhether tool is enabled when integration is configured

​
Parameter Definition

{
  "name": "user_id",
  "type": "string",
  "required": true,
  "description": "The unique identifier for the user",
  "default": null
}

​
Example: Complete Tool Configuration

{
  "name": "SEARCH_ORDERS",
  "description": "Search orders by date range and status. Returns order details including line items.",
  "endpoint": "/api/v2/orders/search",
  "method": "POST",
  "parameters": [
    {
      "name": "start_date",
      "type": "string",
      "required": true,
      "description": "Start date in ISO 8601 format (e.g., 2024-01-01)"
    },
    {
      "name": "end_date",
      "type": "string",
      "required": true,
      "description": "End date in ISO 8601 format"
    },
    {
      "name": "status",
      "type": "string",
      "required": false,
      "description": "Order status filter (pending, shipped, delivered)"
    },
    {
      "name": "limit",
      "type": "integer",
      "required": false,
      "description": "Maximum results per page",
      "default": 50
    }
  ],
  "body_parameters": ["start_date", "end_date", "status"],
  "query_parameters": ["limit"],
  "response_data_path": "data.orders"
}

​
Path Parameters Example

For endpoints with dynamic segments: 
{
  "name": "GET_ORDER_DETAILS",
  "description": "Get detailed information about a specific order",
  "endpoint": "/api/v2/orders/{order_id}",
  "method": "GET",
  "parameters": [
    {
      "name": "order_id",
      "type": "string",
      "required": true,
      "description": "The order ID to retrieve"
    }
  ],
  "path_parameters": ["order_id"]
}