Create Custom Function

curl --request POST \
  --url https://api.xpander.ai/v1/custom_functions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Add Document to KB",
  "source_code": "def xpander_run_action(knowledge_base_id: str, document_urls: list):\n    return {\"added\": len(document_urls)}\n"
}
'

import requests

url = "https://api.xpander.ai/v1/custom_functions"

payload = {
    "name": "Add Document to KB",
    "source_code": "def xpander_run_action(knowledge_base_id: str, document_urls: list):
    return {\"added\": len(document_urls)}
"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Add Document to KB',
    source_code: 'def xpander_run_action(knowledge_base_id: str, document_urls: list):\n    return {"added": len(document_urls)}\n'
  })
};

fetch('https://api.xpander.ai/v1/custom_functions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.xpander.ai/v1/custom_functions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Add Document to KB',
    'source_code' => 'def xpander_run_action(knowledge_base_id: str, document_urls: list):
    return {"added": len(document_urls)}
'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.xpander.ai/v1/custom_functions"

	payload := strings.NewReader("{\n  \"name\": \"Add Document to KB\",\n  \"source_code\": \"def xpander_run_action(knowledge_base_id: str, document_urls: list):\\n    return {\\\"added\\\": len(document_urls)}\\n\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.xpander.ai/v1/custom_functions")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Add Document to KB\",\n  \"source_code\": \"def xpander_run_action(knowledge_base_id: str, document_urls: list):\\n    return {\\\"added\\\": len(document_urls)}\\n\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.xpander.ai/v1/custom_functions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Add Document to KB\",\n  \"source_code\": \"def xpander_run_action(knowledge_base_id: str, document_urls: list):\\n    return {\\\"added\\\": len(document_urls)}\\n\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": "created",
  "id": "e5e5e5e5-f6f6-a7a7-b8b8-c9c9c9c9c9c9"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

POST

custom_functions

Create Custom Function

curl --request POST \
  --url https://api.xpander.ai/v1/custom_functions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Add Document to KB",
  "source_code": "def xpander_run_action(knowledge_base_id: str, document_urls: list):\n    return {\"added\": len(document_urls)}\n"
}
'

import requests

url = "https://api.xpander.ai/v1/custom_functions"

payload = {
    "name": "Add Document to KB",
    "source_code": "def xpander_run_action(knowledge_base_id: str, document_urls: list):
    return {\"added\": len(document_urls)}
"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Add Document to KB',
    source_code: 'def xpander_run_action(knowledge_base_id: str, document_urls: list):\n    return {"added": len(document_urls)}\n'
  })
};

fetch('https://api.xpander.ai/v1/custom_functions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.xpander.ai/v1/custom_functions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Add Document to KB',
    'source_code' => 'def xpander_run_action(knowledge_base_id: str, document_urls: list):
    return {"added": len(document_urls)}
'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.xpander.ai/v1/custom_functions"

	payload := strings.NewReader("{\n  \"name\": \"Add Document to KB\",\n  \"source_code\": \"def xpander_run_action(knowledge_base_id: str, document_urls: list):\\n    return {\\\"added\\\": len(document_urls)}\\n\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.xpander.ai/v1/custom_functions")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Add Document to KB\",\n  \"source_code\": \"def xpander_run_action(knowledge_base_id: str, document_urls: list):\\n    return {\\\"added\\\": len(document_urls)}\\n\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.xpander.ai/v1/custom_functions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Add Document to KB\",\n  \"source_code\": \"def xpander_run_action(knowledge_base_id: str, document_urls: list):\\n    return {\\\"added\\\": len(document_urls)}\\n\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": "created",
  "id": "e5e5e5e5-f6f6-a7a7-b8b8-c9c9c9c9c9c9"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

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

string

required

Display name for the custom function

string

required

Python source code. Must contain a xpander_run_action(...) function definition.

string

Internal function name (defaults to sanitized version of name)

string

Human-readable description of what the function does

object

Execution limits

Show Limits Object

integer

default:15

Maximum execution time in seconds. A run that takes longer is stopped.

Response

Returns {"status": "created", "id": "<function-id>"}. The function is then analyzed, and Get Custom Function shows status: "analysing" until it changes to ready, usually within a few seconds.

{
  "status": "created",
  "id": "<function-id>"
}

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 | null

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

Show child attributes

Response

Successful Response

Overview

REST API - Conversations

REST API - Agents

REST API - Tasks

Agent Workspace

REST API - Knowledge

REST API - Skills

REST API - Workflows

REST API - Custom Functions

REST API - Scheduled Tasks

REST API - Self-Schedules

REST API - Misc

Channels and webhooks

Create Custom Function

Request Body

Response

Example Request

Notes

Authorizations

Body

Response