Docs

REST API

REST API

Manage custom tools programmatically with a Platform-plan MCP API key. Agents invoke tools via MCP, not REST.

Authentication

Public API routes under /api/v1/… require a Platform plan and a Bearer MCP key. Generate keys in workspace Settings or the Connect IDE wizard.

Authorization: Bearer mcp_live_YOUR_KEY

The key must belong to the workspace in the URL path. Prefer MCP for agent invocations — REST is for listing and managing tools from scripts or CI.

Endpoints

MethodPathDescription
GET/api/v1/workspaces/[id]/toolsList tools in the workspace
POST/api/v1/workspaces/[id]/toolsCreate a custom HTTP tool
DELETE/api/v1/workspaces/[id]/toolsDelete a tool (toolId in JSON body)

Create a custom tool

POST /api/v1/workspaces/{workspaceId}/tools
Authorization: Bearer mcp_live_...
Content-Type: application/json

{
  "name": "notify_slack",
  "description": "Send a notification to our webhook",
  "method": "POST",
  "urlTemplate": "https://hooks.example.com/...",
  "bodyTemplate": "{\"text\": \"{{message}}\"}",
  "inputSchema": {
    "type": "object",
    "properties": {
      "message": { "type": "string", "description": "Alert text" }
    },
    "required": ["message"]
  }
}

Required fields: name, description, method, urlTemplate, inputSchema. Optional: headers, bodyTemplate, secrets, integrationName.

Field semantics match the dashboard custom-tool form — see Custom tools.

Delete a tool

DELETE /api/v1/workspaces/{workspaceId}/tools
Authorization: Bearer mcp_live_...
Content-Type: application/json

{ "toolId": "TOOL_ID" }

Inbound webhooks

External systems POST events to your Herald webhook URL (shown when you create a webhook in the dashboard). Format and signing: Herald webhooks.

POST /api/hooks/{workspaceId}/{hookId}

MCP Gateway

Agents call tools over MCP Streamable HTTP, not REST. Copy the URL and key from Connect IDE.

POST {MCP_GATEWAY_URL}/v1/{workspace-slug}/mcp
Authorization: Bearer mcp_live_...