Create a custom tool

Wire up any HTTP endpoint as a tool agents can call.

POST /api/v1/custom_tools

Wire up any HTTP endpoint as a tool agents can call. The tool's name is auto-generated from label (slugified, prefixed custom_, deduped within the org).

Scope: custom_tools:write

Request body

Field	Type	Required	Notes
`label`	string	yes	Human-readable name. Include connector + resource ("List Postmark Templates", not "List Templates").
`description`	string	yes	LLM-facing description. Decides when the tool gets called.
`method`	enum	yes	`GET` \| `POST` \| `PUT` \| `PATCH` \| `DELETE`.
`url`	string	yes	Endpoint URL. May contain `{{param}}` placeholders.
`type`	enum	no	`"read"` or `"write"`. Defaults to `read`.
`headers`	object	no	Static headers map.
`body_template`	string	no	JSON template for POST/PUT/PATCH bodies. Supports `{{param}}`.
`parameters`	array	no	See below.
`response_mapping`	string	no	Dot path to extract from the response, e.g. `data.items`.
`auth`	object	no	Auth type + credentials. Omitted = no auth.
`group`	object	no	UI grouping `{ name, icon, color }`.

Auth shape

{
  "type": "bearer" | "api_key" | "basic" | "none",
  "credentials": {
    "token":       "...",   // bearer
    "apiKey":      "...",   // api_key
    "header_name": "...",   // api_key (default "X-API-Key")
    "username":    "...",   // basic
    "password":    "..."    // basic
  }
}

Example request

curl -X POST https://dashboard.getmacha.com/api/v1/custom_tools \
  -H "Authorization: Bearer $MACHA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "label": "List Postmark Templates",
    "description": "Returns email templates from Postmark.",
    "method": "GET",
    "url": "https://api.postmarkapp.com/templates",
    "type": "read",
    "parameters": [
      { "name": "count", "type": "integer", "description": "How many templates to return.", "in": "query" }
    ],
    "auth": {
      "type": "api_key",
      "credentials": { "apiKey": "your-postmark-token", "header_name": "X-Postmark-Server-Token" }
    },
    "group": { "name": "Postmark" }
  }'

Errors

Status	Code	When
`409`	`custom_tool_name_taken`	A tool with the same generated name already exists.
`422`	`validation_failed`	Missing required field, bad method, etc.