> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magpipe.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Custom Function

> Create a new custom function for an agent

Create a custom webhook function that your AI agent can call during conversations.

## Request Body

<ParamField body="agent_id" type="string" required>
  UUID of the agent this function belongs to
</ParamField>

<ParamField body="name" type="string" required>
  Function name in snake\_case (e.g., `check_order_status`). Must be unique per agent.
</ParamField>

<ParamField body="description" type="string" required>
  Description of what the function does. The AI uses this to decide when to call it.
</ParamField>

<ParamField body="http_method" type="string" required>
  HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`
</ParamField>

<ParamField body="endpoint_url" type="string" required>
  The webhook URL to call (must be HTTPS in production)
</ParamField>

<ParamField body="headers" type="array">
  Custom headers to include with requests

  ```json theme={null}
  [
    {"name": "Authorization", "value": "Bearer token123"}
  ]
  ```
</ParamField>

<ParamField body="body_schema" type="array">
  Parameters the AI should collect before calling

  ```json theme={null}
  [
    {
      "name": "order_id",
      "type": "string",
      "description": "The customer's order ID",
      "required": true
    }
  ]
  ```
</ParamField>

<ParamField body="response_variables" type="array">
  Variables to extract from the response using JSON paths

  ```json theme={null}
  [
    {"name": "status", "json_path": "$.data.status"}
  ]
  ```
</ParamField>

<ParamField body="timeout_ms" type="integer" default="120000">
  Request timeout in milliseconds (max 300000)
</ParamField>

<ParamField body="max_retries" type="integer" default="2">
  Number of retry attempts on failure (max 5)
</ParamField>

<ParamField body="is_active" type="boolean" default="true">
  Whether the function is active and available to the agent
</ParamField>

## Response

<ResponseField name="id" type="string">
  UUID of the created function
</ResponseField>

<ResponseField name="agent_id" type="string">
  UUID of the agent
</ResponseField>

<ResponseField name="name" type="string">
  Function name
</ResponseField>

<ResponseField name="description" type="string">
  Function description
</ResponseField>

<ResponseField name="http_method" type="string">
  HTTP method
</ResponseField>

<ResponseField name="endpoint_url" type="string">
  Webhook URL
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Whether the function is active
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"}
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "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"
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Function name must be snake_case"
  }
  ```

  ```json 409 theme={null}
  {
    "error": "A function with this name already exists for this agent"
  }
  ```
</ResponseExample>