> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/api-reference/core-api-reference/character-crafting-apis/external-api.md). # External API Create, list, link, and delete External API functions so your characters can call custom Python code during conversations. {% hint style="danger" %} This API is available only on the Professional Plan and above. {% endhint %} External API functions are small Python handlers your character can call as tools during a conversation. Create a function once, link it to one or more characters, and the model decides when to run it based on the function name and description. Typical flow: 1. Create a function with `/functions/create/` 2. Link it to a character with `/character/update` (`status: "active"`) 3. List functions (optionally filtered by character) with `/functions/list/` 4. Unlink it from a character with `/character/update` (`status: "inactive"`), or delete it entirely with `/functions/delete/` For the Playground UI walkthrough and example handlers (weather, sports scores, Jira), see [External API](/api-docs/convai-playground/character-customization/external-api.md). Hard limits (supported models, Python runtime, libraries, schema, caps) are documented once on [External API limitations](/api-docs/convai-playground/character-customization/external-api/external-api-limitations.md). ## Writing functions Functions run in a sandboxed **Python 3.11** runtime. Write plain Python, keep the surface area small, and return JSON-serializable data the model can read back into the conversation. For the full limit list (allowed libraries, line cap, model support, character caps), see [External API limitations](/api-docs/convai-playground/character-customization/external-api/external-api-limitations.md). ### Entry point: `handle_event` Every function **must** define a top-level function named `handle_event` that takes one argument. That argument is a dict of the values the model filled in from your `input_description`. ```python def handle_event(inputs): # `inputs` is a dict of the parameters defined in input_description. # Call your external API here and return a JSON-serializable dict. return {"result": "ok"} ``` Requirements: * The name must be exactly `handle_event` * It must accept a single parameter (commonly named `inputs` or `data`) * Return a **JSON-serializable** value, almost always a `dict` * Do not rely on global mutable state across calls — each invocation is independent Minimal example that reads one parameter and hits an external API: ```python import requests API_KEY = "" def handle_event(inputs): city = inputs.get("city") url = f"https://api.openweathermap.org/data/2.5/weather?q={city}&appid={API_KEY}" response = requests.get(url, timeout=10) response.raise_for_status() weather = response.json() return { "city": city, "description": weather["weather"][0]["description"], "temp_k": weather["main"]["temp"], } ``` ### Input description schema `input_description` tells the model which arguments it can (and must) pass into `handle_event`. On create/update it is sent as a **JSON string**, not a nested object. The decoded JSON must match this schema: ```json { "type": "object", "properties": { "parameters": { "type": "object", "patternProperties": { "^[a-zA-Z_][a-zA-Z0-9_]*$": { "type": "object", "properties": { "type": { "type": "string", "enum": ["string", "integer", "boolean", "object", "array"] }, "description": { "type": "string" } }, "required": ["type", "description"] } }, "additionalProperties": false }, "required": { "type": "array", "items": { "type": "string" } } }, "required": ["parameters", "required"] } ``` What that means in practice: | Field | Rules | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `parameters` | Object whose keys are parameter names. Extra keys outside this map are rejected (`additionalProperties: false`). | | Parameter name | Must match `^[a-zA-Z_][a-zA-Z0-9_]*$` (letter or `_` first, then letters, digits, or `_`). | | `parameters..type` | One of: `string`, `integer`, `boolean`, `object`, `array`. | | `parameters..description` | Non-empty string the model uses to decide what value to pass. | | `required` | Array of parameter names that must be present. Names listed here should also exist under `parameters`. | The same rules are summarized on [External API limitations](/api-docs/convai-playground/character-customization/external-api/external-api-limitations.md#input-description). Example `input_description` (as an object — stringify it before sending in the request body): ```json { "parameters": { "city": { "type": "string", "description": "Name of the city to get weather for (e.g. 'London', 'Tokyo')" }, "units": { "type": "string", "description": "Optional unit system, such as 'metric' or 'imperial'" } }, "required": ["city"] } ``` In Python when calling create: ```python input_description = json.dumps({ "parameters": { "city": { "type": "string", "description": "Name of the city to get weather for" } }, "required": ["city"] }) ``` {% hint style="info" %} Keep parameter descriptions concrete. The model picks arguments from those descriptions, so vague text like `"a value"` leads to bad calls. Prefer examples and units in the description string. {% endhint %} *** ## Create a function `POST` `https://api.convai.com/functions/create/` Creates a new External API function on your account. The function is not attached to any character until you link it. #### Headers | Name | Type | Description | | ------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------- | | CONVAI-API-KEY\* | String | The unique api-key provided for every user. Found under the Key icon when logged into your Convai account. | | Content-Type\* | String | Must be `application/json` | #### Request body | Name | Type | Description | | ---------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name\* | String | Display name of the function. Prefer a clear verb phrase the model can match (for example `Get Weather`). | | description\* | String | When the character should call this function. Used by the model for tool selection. | | language\* | String | Implementation language. Only `python` is supported. | | source\_code\* | String | Full Python 3.11 source, including `handle_event`. Max 400 lines. Stdlib + `requests` only. See [Writing functions](#writing-functions) and [limitations](/api-docs/convai-playground/character-customization/external-api/external-api-limitations.md#runtime). | | input\_description\* | String | JSON **string** describing parameters. See [Input description schema](#input-description-schema) and [limitations](/api-docs/convai-playground/character-customization/external-api/external-api-limitations.md#input-description). | #### Example payload ```json { "name": "Get Weather", "description": "Fetches current weather for a given city", "language": "python", "input_description": "{\"parameters\":{\"city\":{\"type\":\"string\",\"description\":\"Name of the city to get weather for\"}},\"required\":[\"city\"]}", "source_code": "import requests\n\nAPI_KEY = \"\"\n\ndef handle_event(data):\n city = data.get(\"city\")\n url = f\"https://api.openweathermap.org/data/2.5/weather?q={city}&appid={API_KEY}\"\n response = requests.get(url)\n weather_data = response.json()\n return {\"weather\": weather_data[\"weather\"][0][\"description\"]}\n" } ``` {% tabs %} {% tab title="201: Created" %} ```json { "transactionID": "", "function": { "function_id": "", "name": "Get Weather", "description": "Fetches current weather for a given city", "language": "python", "source_code": "import requests\n...", "base64_source_code": "", "input_description": "{\"parameters\":{...},\"required\":[\"city\"]}", "created_at": "2026-03-18T12:34:56" } } ``` {% endtab %} {% tab title="400: Bad Request" %} ```json { "ERROR": "Missing required field: name", "Reference ID": "" } ``` Other common 400 messages: * `Field input_description must be a valid json string` * `Language pythonx not supported` * Schema errors from an invalid `input_description` * Source code validation failures (empty, over 400 lines, or blocked as malicious) {% endtab %} {% tab title="401 Unauthorized" %} ```json { "ERROR": "Invalid API key provided." } ``` {% endtab %} {% endtabs %} Here are some sample codes to demonstrate the request format for the endpoint --> {% tabs %} {% tab title="Python" %} {% code overflow="wrap" %} ```python import json import requests url = "https://api.convai.com/functions/create/" input_description = { "parameters": { "city": { "type": "string", "description": "Name of the city to get weather for" } }, "required": ["city"] } source_code = """ import requests API_KEY = "" def handle_event(data): city = data.get("city") url = f"https://api.openweathermap.org/data/2.5/weather?q={city}&appid={API_KEY}" response = requests.get(url) weather_data = response.json() return {"weather": weather_data["weather"][0]["description"]} """.strip() payload = json.dumps({ "name": "Get Weather", "description": "Fetches current weather for a given city", "language": "python", "input_description": json.dumps(input_description), "source_code": source_code }) headers = { "CONVAI-API-KEY": "", "Content-Type": "application/json" } response = requests.post(url, headers=headers, data=payload) print(response.text) ``` {% endcode %} {% endtab %} {% tab title="cURL" %} {% code overflow="wrap" %} ```shell curl --location --request POST 'https://api.convai.com/functions/create/' \ --header 'CONVAI-API-KEY: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Get Weather", "description": "Fetches current weather for a given city", "language": "python", "input_description": "{\"parameters\":{\"city\":{\"type\":\"string\",\"description\":\"Name of the city to get weather for\"}},\"required\":[\"city\"]}", "source_code": "import requests\n\nAPI_KEY = \"\"\n\ndef handle_event(data):\n city = data.get(\"city\")\n url = f\"https://api.openweathermap.org/data/2.5/weather?q={city}&appid={API_KEY}\"\n response = requests.get(url)\n weather_data = response.json()\n return {\"weather\": weather_data[\"weather\"][0][\"description\"]}\n" }' ``` {% endcode %} {% endtab %} {% endtabs %} *** ## List functions `POST` `https://api.convai.com/functions/list/` Returns the External API functions on your account. Pass `character_id` to include each function's link status for that character (`active` or `inactive`). #### Headers | Name | Type | Description | | ------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------- | | CONVAI-API-KEY\* | String | The unique api-key provided for every user. Found under the Key icon when logged into your Convai account. | #### Request body All fields are optional. An empty body lists every function on the account. | Name | Type | Description | | ------------- | ------- | ---------------------------------------------------------------------------------------------------- | | character\_id | String | If set, each function includes `status` relative to this character (`active` / `inactive`). | | per\_page | Integer | Page size. Defaults to `-1` (return all). When set to a positive value, pagination fields are added. | | page | Integer | Page number, starting at `1`. Used only when `per_page` is not `-1`. Default `1`. | #### Example payload ```json { "character_id": "", "per_page": 20, "page": 1 } ``` {% tabs %} {% tab title="200: OK" %} ```json { "transactionID": "", "functions": [ { "function_id": "", "name": "Get Weather", "description": "Fetches current weather for a given city", "language": "python", "created_at": "2026-03-18T12:34:56", "status": "active" } ], "total_pages": 1, "per_page": 20, "page": 1, "total": 1 } ``` `total_pages`, `per_page`, `page`, and `total` are only present when `per_page` is a positive integer. {% endtab %} {% tab title="400: Bad Request" %} ```json { "ERROR": "Failed to get functions with response: ...", "Reference ID": "" } ``` {% endtab %} {% tab title="401 Unauthorized" %} ```json { "ERROR": "Invalid API key provided." } ``` {% endtab %} {% endtabs %} Here are some sample codes to demonstrate the request format for the endpoint --> {% tabs %} {% tab title="Python" %} {% code overflow="wrap" %} ```python import json import requests url = "https://api.convai.com/functions/list/" payload = json.dumps({ "character_id": "", "per_page": 20, "page": 1 }) headers = { "CONVAI-API-KEY": "", "Content-Type": "application/json" } response = requests.post(url, headers=headers, data=payload) print(response.text) ``` {% endcode %} {% endtab %} {% tab title="cURL" %} {% code overflow="wrap" %} ```shell curl --location --request POST 'https://api.convai.com/functions/list/' \ --header 'CONVAI-API-KEY: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "character_id": "", "per_page": 20, "page": 1 }' ``` {% endcode %} {% endtab %} {% endtabs %} *** ## Link functions to a character `POST` `https://api.convai.com/character/update` Attach one or more External API functions to a character through the existing [Character Base API](/api-docs/api-reference/core-api-reference/character-crafting-apis/character-api.md) update endpoint. Once linked (`status: "active"`), the model can call those functions during conversation. A character can have at most **128** active functions. You can link several functions in one request, and you can mix link and [unlink](#unlink-functions-from-a-character) entries together. #### Headers | Name | Type | Description | | ------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------- | | CONVAI-API-KEY\* | String | The unique api-key provided for every user. Found under the Key icon when logged into your Convai account. | | Content-Type | String | `application/json` | #### Request body | Name | Type | Description | | ---------------------------------------- | ------ | ---------------------------------------------------------------------------------------------- | | charID\* | String | Character to update. | | functions | Array | List of function configs. Each item needs `id` (function UUID) and `status` set to `"active"`. | #### Example payload ```json { "charID": "", "functions": [ { "id": "", "status": "active" } ] } ``` {% tabs %} {% tab title="200: OK" %} ```json { "STATUS": "SUCCESS" } ``` {% endtab %} {% tab title="400: Bad Request" %} ```json { "ERROR": "Function limit exceeded. A maximum of 128 functions can be connected to a character.", "Reference ID": "" } ``` Also returned for invalid configs, for example: * `Functions must be a list of configurations` * `Missing required fields in function configuration: id` * `Function status must be one of: active, inactive` * `Duplicate function ID found: ` {% endtab %} {% tab title="401 Unauthorized" %} ```json { "ERROR": "Invalid API key provided." } ``` {% endtab %} {% endtabs %} Here are some sample codes to demonstrate the request format for the endpoint --> {% tabs %} {% tab title="Python" %} {% code overflow="wrap" %} ```python import json import requests url = "https://api.convai.com/character/update" payload = json.dumps({ "charID": "", "functions": [ {"id": "", "status": "active"} ] }) headers = { "CONVAI-API-KEY": "", "Content-Type": "application/json" } response = requests.post(url, headers=headers, data=payload) print(response.text) ``` {% endcode %} {% endtab %} {% tab title="cURL" %} {% code overflow="wrap" %} ```shell curl --location --request POST 'https://api.convai.com/character/update' \ --header 'CONVAI-API-KEY: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "charID": "", "functions": [ {"id": "", "status": "active"} ] }' ``` {% endcode %} {% endtab %} {% endtabs %} After linking, confirm with `/functions/list/` and `character_id` set — linked functions show `"status": "active"`. *** ## Unlink functions from a character `POST` `https://api.convai.com/character/update` Disconnect a function from a character without deleting it from your account. Same endpoint as linking; set `status` to `"inactive"`. After unlinking, the character can no longer call that function. The function stays available to re-link later, or to attach to other characters. #### Headers | Name | Type | Description | | ------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------- | | CONVAI-API-KEY\* | String | The unique api-key provided for every user. Found under the Key icon when logged into your Convai account. | | Content-Type | String | `application/json` | #### Request body | Name | Type | Description | | ---------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | charID\* | String | Character to update. | | functions | Array | List of function configs. Each item needs `id` (function UUID) and `status` set to `"inactive"`. | #### Example payload ```json { "charID": "", "functions": [ { "id": "", "status": "inactive" } ] } ``` {% tabs %} {% tab title="200: OK" %} ```json { "STATUS": "SUCCESS" } ``` {% endtab %} {% tab title="400: Bad Request" %} ```json { "ERROR": "Missing required fields in function configuration: status", "Reference ID": "" } ``` {% endtab %} {% tab title="401 Unauthorized" %} ```json { "ERROR": "Invalid API key provided." } ``` {% endtab %} {% endtabs %} Here are some sample codes to demonstrate the request format for the endpoint --> {% tabs %} {% tab title="Python" %} {% code overflow="wrap" %} ```python import json import requests url = "https://api.convai.com/character/update" payload = json.dumps({ "charID": "", "functions": [ {"id": "", "status": "inactive"} ] }) headers = { "CONVAI-API-KEY": "", "Content-Type": "application/json" } response = requests.post(url, headers=headers, data=payload) print(response.text) ``` {% endcode %} {% endtab %} {% tab title="cURL" %} {% code overflow="wrap" %} ```shell curl --location --request POST 'https://api.convai.com/character/update' \ --header 'CONVAI-API-KEY: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "charID": "", "functions": [ {"id": "", "status": "inactive"} ] }' ``` {% endcode %} {% endtab %} {% endtabs %} Confirm with `/functions/list/` and `character_id` set — unlinked functions show `"status": "inactive"`. {% hint style="info" %} Unlinking only removes the character association. To remove the function from your account entirely (and every character it is linked to), use [Delete a function](#delete-a-function). {% endhint %} *** ## Delete a function `POST` `https://api.convai.com/functions/delete/` Deletes a function you own and removes every character association for it. This cannot be undone. #### Headers | Name | Type | Description | | ------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------- | | CONVAI-API-KEY\* | String | The unique api-key provided for every user. Found under the Key icon when logged into your Convai account. | | Content-Type\* | String | Must be `application/json` | #### Request body | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------------------ | | function\_id\* | String | UUID of the function to delete | #### Example payload ```json { "function_id": "" } ``` {% tabs %} {% tab title="200: OK" %} ```json { "transactionID": "", "status": "success" } ``` {% endtab %} {% tab title="403 Forbidden" %} ```json { "ERROR": "You don't have permission to delete this function", "Reference ID": "" } ``` {% endtab %} {% tab title="404 Not Found" %} ```json { "ERROR": "Function with id not found", "Reference ID": "" } ``` {% endtab %} {% tab title="401 Unauthorized" %} ```json { "ERROR": "Invalid API key provided." } ``` {% endtab %} {% endtabs %} Here are some sample codes to demonstrate the request format for the endpoint --> {% tabs %} {% tab title="Python" %} {% code overflow="wrap" %} ```python import json import requests url = "https://api.convai.com/functions/delete/" payload = json.dumps({ "function_id": "" }) headers = { "CONVAI-API-KEY": "", "Content-Type": "application/json" } response = requests.post(url, headers=headers, data=payload) print(response.text) ``` {% endcode %} {% endtab %} {% tab title="cURL" %} {% code overflow="wrap" %} ```shell curl --location --request POST 'https://api.convai.com/functions/delete/' \ --header 'CONVAI-API-KEY: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "function_id": "" }' ``` {% endcode %} {% endtab %} {% endtabs %} {% hint style="info" %} To disconnect a function from a character without deleting it, use [Unlink functions from a character](#unlink-functions-from-a-character). {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.convai.com/api-docs/api-reference/core-api-reference/character-crafting-apis/external-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.