Skip to main content
POST
/
custom-functions
curl -X POST "https://api.magpipe.ai/functions/v1/custom-functions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "check_order_status",
    "description": "Look up customer order status by order ID",
    "http_method": "POST",
    "endpoint_url": "https://api.yourstore.com/orders/status",
    "body_schema": [
      {
        "name": "order_id",
        "type": "string",
        "description": "The customer order ID or confirmation number",
        "required": true
      }
    ],
    "response_variables": [
      {"name": "status", "json_path": "$.data.status"},
      {"name": "eta", "json_path": "$.data.estimated_delivery"}
    ]
  }'

{
  "id": "789e0123-e89b-12d3-a456-426614174000",
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_id": "456e7890-e89b-12d3-a456-426614174000",
  "name": "check_order_status",
  "description": "Look up customer order status by order ID",
  "http_method": "POST",
  "endpoint_url": "https://api.yourstore.com/orders/status",
  "headers": [],
  "body_schema": [
    {
      "name": "order_id",
      "type": "string",
      "description": "The customer order ID or confirmation number",
      "required": true
    }
  ],
  "response_variables": [
    {"name": "status", "json_path": "$.data.status"},
    {"name": "eta", "json_path": "$.data.estimated_delivery"}
  ],
  "timeout_ms": 120000,
  "max_retries": 2,
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
Create a custom webhook function that your AI agent can call during conversations.

​
Request Body

​
agent_id
string
required
UUID of the agent this function belongs to
​
name
string
required
Function name in snake_case (e.g., check_order_status). Must be unique per agent.
​
description
string
required
Description of what the function does. The AI uses this to decide when to call it.
​
http_method
string
required
HTTP method: GET, POST, PUT, PATCH, or DELETE
​
endpoint_url
string
required
The webhook URL to call (must be HTTPS in production)
​
headers
array
Custom headers to include with requests
[
  {"name": "Authorization", "value": "Bearer token123"}
]
​
body_schema
array
Parameters the AI should collect before calling
[
  {
    "name": "order_id",
    "type": "string",
    "description": "The customer's order ID",
    "required": true
  }
]
​
response_variables
array
Variables to extract from the response using JSON paths
[
  {"name": "status", "json_path": "$.data.status"}
]
​
timeout_ms
integer
default:"120000"
Request timeout in milliseconds (max 300000)
​
max_retries
integer
default:"2"
Number of retry attempts on failure (max 5)
​
is_active
boolean
default:"true"
Whether the function is active and available to the agent

​
Response

​
id
string
UUID of the created function
​
agent_id
string
UUID of the agent
​
name
string
Function name
​
description
string
Function description
​
http_method
string
HTTP method
​
endpoint_url
string
Webhook URL
​
is_active
boolean
Whether the function is active
​
created_at
string
ISO 8601 timestamp
curl -X POST "https://api.magpipe.ai/functions/v1/custom-functions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "check_order_status",
    "description": "Look up customer order status by order ID",
    "http_method": "POST",
    "endpoint_url": "https://api.yourstore.com/orders/status",
    "body_schema": [
      {
        "name": "order_id",
        "type": "string",
        "description": "The customer order ID or confirmation number",
        "required": true
      }
    ],
    "response_variables": [
      {"name": "status", "json_path": "$.data.status"},
      {"name": "eta", "json_path": "$.data.estimated_delivery"}
    ]
  }'

{
  "id": "789e0123-e89b-12d3-a456-426614174000",
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_id": "456e7890-e89b-12d3-a456-426614174000",
  "name": "check_order_status",
  "description": "Look up customer order status by order ID",
  "http_method": "POST",
  "endpoint_url": "https://api.yourstore.com/orders/status",
  "headers": [],
  "body_schema": [
    {
      "name": "order_id",
      "type": "string",
      "description": "The customer order ID or confirmation number",
      "required": true
    }
  ],
  "response_variables": [
    {"name": "status", "json_path": "$.data.status"},
    {"name": "eta", "json_path": "$.data.estimated_delivery"}
  ],
  "timeout_ms": 120000,
  "max_retries": 2,
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}