REST API Tools

A REST API tool wraps an HTTP endpoint as an agent tool. The agent provides the parameters, Synapse makes the HTTP call, and the response is returned to the agent as the tool result.

Registering a REST API tool

Go to Settings → Custom Tools → Add Tool → REST API.

Fields

Field	Description
Name	Tool identifier (no spaces, e.g. get_weather)
Display name	Human-friendly name
Description	What the tool does — the agent reads this to decide when to call it
Method	HTTP method: GET, POST, PUT, DELETE, PATCH
URL	Endpoint URL (can include {param} placeholders)
Headers	Key-value pairs (supports {param} references)
Body template	JSON body template (supports {param} references)
Parameters	Input schema — what the agent needs to provide
Auth	Bearer token, API key header, or none

Parameter schema

Define the parameters the agent must provide to call the tool:

[
  {
    "name": "city",
    "type": "string",
    "description": "City name to get weather for",
    "required": true
  },
  {
    "name": "units",
    "type": "string",
    "description": "Temperature units: celsius or fahrenheit",
    "required": false,
    "default": "celsius"
  }
]

Example: Weather API

{
  "name": "get_weather",
  "generalName": "Get Weather",
  "description": "Get current weather for a city",
  "tool_type": "http",
  "method": "GET",
  "url": "https://api.openweathermap.org/data/2.5/weather?q={city}&units={units}&appid=YOUR_KEY",
  "headers": {},
  "parameters": [
    { "name": "city", "type": "string", "description": "City name", "required": true },
    { "name": "units", "type": "string", "description": "metric or imperial", "required": false, "default": "metric" }
  ]
}

Example: Internal API

{
  "name": "get_customer",
  "generalName": "Get Customer",
  "description": "Fetch customer record by ID from our CRM",
  "tool_type": "http",
  "method": "GET",
  "url": "https://api.internal.company.com/customers/{customer_id}",
  "headers": {
    "Authorization": "Bearer YOUR_INTERNAL_TOKEN",
    "X-App-Version": "2.0"
  },
  "parameters": [
    { "name": "customer_id", "type": "string", "description": "Customer UUID", "required": true }
  ]
}

Example: Webhook trigger

{
  "name": "send_slack_alert",
  "generalName": "Send Slack Alert",
  "description": "Send an alert message to the #alerts Slack channel",
  "tool_type": "http",
  "method": "POST",
  "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
  "headers": { "Content-Type": "application/json" },
  "body": "{ \"text\": \"{message}\" }",
  "parameters": [
    { "name": "message", "type": "string", "description": "Alert message text", "required": true }
  ]
}

URL and body templating

Use {param_name} in URLs, headers, and body templates. Synapse substitutes the agent-provided values before making the request.

URL: https://api.example.com/users/{user_id}/posts?page={page}
Body: { "title": "{title}", "content": "{content}" }

Authentication

Method	Config
Bearer token	Set in the Authorization header: Bearer YOUR_TOKEN
API key header	Add as a custom header: X-API-Key: YOUR_KEY
Query parameter	Include in the URL: ?api_key={api_key} and add api_key as a parameter
No auth	Leave headers empty

Testing

After registering a tool, use the Test button in Settings → Custom Tools to run it with sample input values and see the response.