Custom HTTP Tools

Custom HTTP tools let your agents call any REST API — n8n / Make webhooks, CRMs, internal services, Slack bots, etc. You configure the endpoint once at the organization level and then connect the tool to the agents that need it.

Where to create

Custom HTTP tools are created in the admin panel under Tools → Active, in the Custom Tools section, via the New Tool button.

Once created, the tool appears under Other Tools when you click + Add Tool in any agent in the organization.

The form

Clicking New Tool opens a type picker with two options: HTTP / API Tool and MCP Server. For a REST API, choose HTTP / API Tool.

That opens the Create HTTP tool modal.

Identification

Fields marked with * are required. If you try to save without filling them in, the form shows the warning right on the field.

Field	What to fill in
Tool name *	Friendly name only for you, shown in the panel. The AI doesn’t see this. Ex.: Assign Human CRM.
Technical name (used by AI)	Identifier the AI uses to call the tool. Auto-generated from the Tool name and shown as a read-only chip (e.g., assign_human_crm). You don’t need to fill it in. If you want a different identifier, click Customize next to the chip — only lowercase letters, numbers, and underscores.
Description	The most important field. Explain what the tool does and when to use it. The AI decides to call the tool based on this text. Ex.: Use when human attendance is needed for issues the AI cannot clarify.

Method and URL

Method and URL sit on the same line: a selector with the HTTP verb on the left and the URL field next to it.

• HTTP method: GET, POST, PUT, PATCH, or DELETE.
• Endpoint URL *: full URL. You can use :key to mark path parameters (e.g., https://api.example.com/users/:id) — these are configured in the Path parameters section, inside Advanced.

The JSON Body (request body, only for methods other than GET) lives inside the Advanced group — see Advanced settings.

Authentication

How SquadOS authenticates with the API. The secret is stored encrypted on the server and the AI never has access to it.

Type	How it works
None	Public endpoint, no authentication.
Bearer Token	Sends Authorization: Bearer YOUR_TOKEN.
API Key (Header)	Sends a custom header (e.g., X-API-Key: YOUR_TOKEN).
Custom Header	Like API Key, but lets you add a prefix to the value (e.g., Authorization: Token YOUR_TOKEN).

When editing an existing tool, the secret field appears empty with •••••••• (keep current) placeholder. Leave blank to preserve the current value — only fill in if you want to replace it.

Key concept: Parameters vs. JSON Body

Field	Role
Parameters	Defines what the AI can send when calling the tool. Becomes the “contract” the model sees.
JSON Body	Defines how those values are packed into the HTTP request body.

Practical example

Tool that notifies a human attendant via webhook.

Parameters (what the AI sends):

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "Summary of the customer's problem"
    }
  },
  "required": ["text"]
}

JSON Body (sent to the endpoint):

{"message": "{{text}}", "channel": "web", "priority": "high"}

When the agent calls with text: "Customer cannot access", SquadOS sends:

{"message": "Customer cannot access", "channel": "web", "priority": "high"}

channel and priority are fixed; {{text}} was replaced with the AI value.

Tip

If you leave JSON Body blank, SquadOS sends the parameters as flat JSON (no renaming or fixed fields). Use JSON Body when you need nesting, renaming, or fixed values.

Parameters

The contract describing for the AI which arguments it can/must send. By default you use the visual builder: one row per parameter with name / type / description and an Add button. It’s enough for most cases.

For complex types (enums, nested objects, typed arrays), click Edit as JSON Schema (advanced) — the discreet link next to Add — and paste a complete JSON Schema. A Back to visual editor link undoes the switch.

Each parameter:

1. Becomes a {{placeholder}} available in the JSON Body.
2. Is described to the AI — clear descriptions improve precision.
3. Can be marked required to force the AI to provide it.

Caution

Without parameters, the AI has nothing to pass to the tool. If the JSON Body has {{text}} but the parameter text wasn’t defined, the placeholder stays literal in the sent payload.

Advanced settings (optional)

Everything most tools don’t need is tucked into a single collapsible Advanced group at the bottom of the form. Click to expand. Defaults work for most cases.

JSON Body

Only for methods other than GET. Defines how parameters are packed into the request body (see Parameters vs. JSON Body). If you leave it blank, SquadOS sends the parameters as flat JSON — that’s why the JSON Body lives here under Advanced: most tools don’t need to touch it.

Custom headers

HTTP headers sent on every request, in addition to auth ones. Use for Content-Type, Accept, X-Source, etc.

Path parameters

Replace URL chunks marked with :key. Example: URL https://api.example.com/users/:id with path param id. Each path param has:

• Key: name of the placeholder in the URL (no :).
• Default value: fixed value to use if the AI doesn’t provide one.
• AI provides: if checked, the AI fills it at runtime. If unchecked, the default value is always used.

Query parameters

Added to the URL as ?key=value. Same logic as path params.

Advanced settings

• Timeout: max time (ms) SquadOS waits for response. Default: 30000ms (30s).
• Send conversation metadata: when checked, adds to the request body fields like conversation_id, conversation_title, external_contact, agent_id, model_used, and external_user_id. Useful for webhooks needing to correlate with the conversation.
• Provide lead identity to context: when on, the lead’s external identifier and name enter the model’s context for this turn, so the AI can use them when calling the tool. Enable only for tools that need to identify the lead — for example, a CDP lookup that fetches the lead’s history by identifier. Off by default.

Note

“Send conversation metadata” and “Provide lead identity to context” are different things. The first sends data in the request body to your endpoint — the model sees none of it. The second puts the lead identity in the model’s context, so the AI itself decides to call the tool with the right identifier.

Testing the tool

The Test tool panel is always visible at the bottom of the form — there’s no longer a “Test” button to open it. Before saving, use it to check that the endpoint responds:

1. Fill in the test values for the parameters you defined.
2. Click Run test to fire the real request against the endpoint.
3. See the full response (HTTP status + body).

The tool only gets a green indicator (configured) after a successful test.

Connecting to the agent

Once saved, the tool appears under Other Tools when you click + Add Tool in any agent:

1. Open the agent under Agents → [your agent] → Tools.
2. Click + Add Tool.
3. Under OTHER TOOLS, pick the HTTP tool you just created.
4. (Optional) Configure per-agent overrides if you want fixed values without changing the base tool.

The AI gets the tool available immediately in the next conversations.

Best practices

• Descriptions matter: the quality of tool and parameter descriptions is what most affects call accuracy. Be specific about when to use.
• Use required for parameters that are truly required. This forces the AI to ask the user if info is missing.
• Test before connecting: a misconfigured endpoint in production generates errors in every conversation using the tool.
• Edit carefully: changing an organization tool affects immediately all agents using it.
• One purpose per tool: instead of a “super tool” with 20 parameters, prefer several specific ones. The AI picks better between specialized tools.