Skip to main content
POST
/
v1
/
custom_functions
Create Custom Function
curl --request POST \
  --url https://api.example.com/v1/custom_functions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "source_code": "<string>",
  "function_name": "<string>",
  "description": "",
  "limits": {
    "max_run_time": 15
  }
}
'
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}
Create a new custom function. 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.

​
Request Body

​
name
string
required
Display name for the custom function
​
source_code
string
required
Python source code. Must contain a xpander_run_action(...) function definition.
​
function_name
string
Internal function name (defaults to sanitized version of name)
​
description
string
Human-readable description of what the function does
​
limits
object
Execution limits

​
Response

Returns the created CustomFunctionItem with status analysing. The function transitions to ready once analysis completes.

​
Example Request

curl -X POST "https://api.xpander.ai/v1/custom_functions" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "name": "Weather Lookup",
    "description": "Fetches current weather for a given city",
    "source_code": "import requests\n\ndef xpander_run_action(city: str) -> str:\n    \"\"\"Get current weather for a city.\"\"\"\n    resp = requests.get(f\"https://wttr.in/{city}?format=3\")\n    return resp.text"
  }'

​
Notes

  • The xpander_run_action function is the entry point — it must be defined in the source code
  • After creation, the function is automatically analyzed for safety and input schema extraction
  • Status transitions: analysing → ready (success) or analysing → error (analysis failed)
  • Check analysis_error_details if the function moves to error status

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Body

application/json

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'.

​
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:

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.

​
function_name
string | null

Optional programmatic function name. If not provided, defaults to 'xpander_run_action'. The source_code must define a function with this name.

​
description
string | null
default:""

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.

​
limits
CustomFunctionLimitsModel · object

Resource limits for the function execution. Currently only max_run_time (seconds) is supported.

Response

Successful Response