---
title: "Create Custom Function"
method: POST
path: "/v1/custom_functions"
tags: ["API v1", "Custom Functions", "Custom Functions CRUD"]
---

# Create Custom Function

`POST /v1/custom_functions`

## Request

- Base URL: `https://api.xpander.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xpander.ai/v1/custom_functions`
- Auth: API key in header `x-api-key`

Create a new custom function. Provide a name, optional description, and Python source code. The code must define a function called `xpander_run_action(...)` that will be executed when the function is invoked. After creation, the function is automatically analyzed for safety and input schema extraction. Status will transition from 'analysing' to 'ready' once analysis completes.

## Request body

- CreateCustomFunctionRequest: Request model for creating a new custom function. The source code must define a function called `xpander_run_action(...)`. This is the entry point that will be called when the function is invoked by an agent or via the execute endpoint. After creation, the function is automatically analyzed for: - Safety (no malicious patterns) - Input schema extraction (parameters are auto-detected) - Runnability (syntax validation) The function status starts as 'analysing' and transitions to 'ready' once analysis completes successfully.
  - `name` string, required: Human-readable name for the custom function. Used as the display name in the agent's tool list. Examples: 'Calculate Tax', 'Parse CSV Data'.
  - `function_name` string, nullable: Optional programmatic function name. If not provided, defaults to 'xpander_run_action'. The source_code must define a function with this name.
  - `description` string, nullable: Description of what the function does. This is shown to the LLM when the function is used as an agent tool, so make it clear and action-oriented.
  - `source_code` string, required: Python source code for the custom function. Must define a function called `xpander_run_action(...)` (or the name specified in function_name). The function receives keyword arguments matching its parameter signature. It should return a dict or string result. Example: ```python def xpander_run_action(text: str, max_words: int = 100) -> dict: words = text.split()[:max_words] return {"word_count": len(words), "truncated_text": " ".join(words)} ``` The function runs in a secure Python 3.12 sandbox with common libraries available (requests, json, re, datetime, etc.). Do NOT use: file system access, subprocess, os.system, eval/exec, or network access to internal services.
  - `limits` CustomFunctionLimitsModel: Resource limits for custom function execution.
    - `max_run_time` integer, nullable: Maximum execution time in seconds. The function will be terminated if it exceeds this limit. Default: 15 seconds.

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/xpander/apis/xpander-ai-api-service.md) - [All operations](https://skmtc.dev/xpander/apis/xpander-ai-api-service/llms.txt) - [OpenAPI document](https://skmtc.dev/xpander/apis/xpander-ai-api-service/revisions/725c0066d5df?raw)