HTTP tools

An HTTP tool calls one address of a web API. Use it when you need a single action from a system and there is no API description to connect, for example “get the weather for a city” or “create a lead in the CRM”. If the system does have an API description, connect the API instead: every action becomes a tool at once.

Create one

1. Open Tools and click Create tool.
2. Under Execution method, pick HTTP REST API.
3. Give it a Tool name and a Description. The description is what assistants read to decide when to use the tool, so say plainly what it does.
4. Under HTTP request:
   • Link to API (optional): pick an API you already connected, and the address becomes a Path on that API (it also uses that API’s sign-in). Or leave it on None - use full URL and type the full URL.
   • Method: GET reads, POST creates, PUT and PATCH change, DELETE removes. The API’s own documentation says which one to use.
   • Put an input into the address with curly braces: https://api.example.com/users/{id} fills in the tool’s id input.
   • Add Custom headers and a Body template if the API needs them.
5. Under Authentication, say how the tool signs in: No authentication, API key, Bearer token or Basic auth, and pick the key from Credentials (or create one right there). The tool itself never holds the key.
6. Under Parameters, list the inputs the tool takes, such as id or city.
7. Click Create tool, then open it and use Test tool to try it with real inputs.

Response mapping and Pagination are optional. Response mapping picks the useful part out of a long answer; pagination follows “next page” links so the tool returns every result, not just the first page.

For developers

How inputs are filled in

{name} placeholders are replaced with the tool’s input of that name in the URL or path (values are URL-encoded), in query parameters, in header values and in the body template. For GET and DELETE, inputs not used in the path are sent as query parameters. For POST, PUT and PATCH with no body template, inputs not used in the path are sent as the JSON body. A body template is parsed first and values are placed into it, so an input cannot add fields of its own.

The tool definition

The HTTP request is the tool’s httpConfig:

{
  "name": "fetch_weather",
  "description": "Fetch current weather for a city",
  "type": "query",
  "executionMethod": "http",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "City name" },
      "units": { "type": "string", "enum": ["metric", "imperial"], "default": "metric" }
    },
    "required": ["city"]
  },
  "httpConfig": {
    "method": "GET",
    "path": "https://api.weather.example.com/v1/current",
    "queryParams": { "q": "{city}", "units": "{units}" }
  },
  "authConfig": { "type": "apiKey", "config": { "credentialId": "<credential id>", "headerName": "X-API-Key" } }
}

Authentication

authConfig says how the tool signs its calls (type and, for an API key, headerName) and which credential it uses (config.credentialId). A secret sent inline is refused with TOOL_SECRET_INLINE. A tool linked to an API uses that API’s key instead.

Errors

A 2xx answer is returned as the result. Any other status, a timeout or a failed connection returns a failed result with the error message. Calls to private or internal addresses are blocked unless the organization allows that host.

For logic a template can’t express, write a JavaScript tool instead: fetch() and npm packages such as axios are available there.