Skip to content
Chatvia Docs
On this page

API reference

Functions

Get in touch: Ahmad Mayahi, creator of Chatvia, Spectra and Shakomako

These endpoints manage functions and decide which agents may use them. A function lets an agent call one of your own systems during a chat, through a webhook: an address on your server that Chatvia sends a request to. Functions (webhooks) explains how the agent uses them.

For example, if you keep your order system's API described in an OpenAPI file, a script can turn each lookup into a function and attach it to your support agent. Then the agent can answer "where is my order?" with live data.

Functions belong to the workspace. You write a function once, then attach it to each agent that needs it.

Read the overview first for the base URL, keys, errors and paging.

The function object

json
{
  "id": "0199f3d0-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
  "internal_name": "lookup_order",
  "display_name": "Order lookup",
  "description": "Retrieve order details (status, items, shipping address) for a given order ID.",
  "parameters_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "description": "The order number, such as ORD-12345" }
    },
    "required": ["order_id"]
  },
  "webhook": {
    "url": "https://api.example.com/orders/lookup",
    "method": "POST",
    "has_headers": false
  },
  "auth_type": "bearer",
  "has_auth_value": true,
  "timeout_ms": 8000,
  "is_enabled": true,
  "last_invoked_at": "2026-10-24T17:02:55+00:00",
  "invocation_count": 318,
  "created_at": "2026-09-30T10:00:00+00:00"
}
Field Type Meaning
id string The function's id.
internal_name string The name the AI model calls the function by.
display_name string or null A friendly name shown to people in chat. Falls back to internal_name.
description string Tells the model what the function does and when to call it.
parameters_schema object A JSON Schema that describes the arguments the model must send.
webhook.url string Where Chatvia sends the call.
webhook.method string POST, GET, PATCH or DELETE.
webhook.has_headers boolean Whether extra headers are set. Their values are never returned.
auth_type string none, bearer, header or hmac.
has_auth_value boolean Whether a secret is stored. The secret itself is never returned.
timeout_ms integer How long Chatvia waits for your webhook, in milliseconds.
is_enabled boolean Whether agents may call the function.
last_invoked_at string or null When an agent last called it.
invocation_count integer How many times agents called it.
created_at string When it was created.

List functions

Returns your workspace's functions, newest first.

text
GET /api/v1/functions

Who can call it: the owner, or a teammate with Functions.

bash
curl https://chat.example.com/api/v1/functions \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": [function, …], "next_cursor": … }. See Pagination.

Create a function

text
POST /api/v1/functions

Who can call it: the owner, or a teammate with Functions.

Body field Type Required Default Notes
internal_name string yes Letters, digits and underscores, starting with a letter, up to 64 characters. Must be unique in your workspace.
display_name string no none Up to 255 characters.
description string yes Up to 1,024 characters. Write it for the model. Writing a good description has tips.
parameters_schema object yes A JSON Schema of "type": "object".
webhook_url string yes A public address, up to 2,048 characters.
webhook_method string no POST POST, GET, PATCH or DELETE. GET sends the arguments as a query string, the others as a JSON body.
webhook_headers object no none Extra headers sent with every call, as { "name": "value" }.
auth_type string no none none, bearer, header or hmac.
auth_value string with bearer, header or hmac The token, header value or signing key. Stored encrypted. Up to 8,192 characters.
auth_header_name string with header The name of the header the secret goes in.
timeout_ms integer no 10000 From 1,000 to 30,000.
is_enabled boolean no true
bash
curl https://chat.example.com/api/v1/functions \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "internal_name": "lookup_order",
    "display_name": "Order lookup",
    "description": "Retrieve order details (status, items, shipping address) for a given order ID.",
    "parameters_schema": {
      "type": "object",
      "properties": { "order_id": { "type": "string" } },
      "required": ["order_id"]
    },
    "webhook_url": "https://api.example.com/orders/lookup",
    "auth_type": "bearer",
    "auth_value": "your-webhook-token",
    "timeout_ms": 8000
  }'

The answer is 201 Created with { "data": function }.

Good to know:

  • A new function is not attached to any agent yet. See Attach a function to an agent.
  • At creation, whether a person must approve each call follows the method. GET functions run freely. POST, PATCH and DELETE functions ask for approval first. The API can't change this. Switch Require approval on the function in the dashboard. Approval flow explains it.
  • A function that needs approval is only offered to the agent in the Hosted Chat, where someone can click Approve. It is left out of API conversations.
  • hmac signs each call so your server can check it came from Chatvia. Verifying HMAC signatures has the code.

Get a function

text
GET /api/v1/functions/{function}

Who can call it: the owner, or a teammate with Functions.

bash
curl https://chat.example.com/api/v1/functions/0199f3d0-3c4d-7e5f-8a6b-7c8d9e0f1a2b \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": function }.

Update a function

Changes the fields you send. A field you leave out keeps its value. The fields are the same as for Create a function.

text
PATCH /api/v1/functions/{function}

Who can call it: the owner, or a teammate with Functions.

bash
curl -X PATCH https://chat.example.com/api/v1/functions/0199f3d0-3c4d-7e5f-8a6b-7c8d9e0f1a2b \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_enabled": false }'

The answer is { "data": function }.

When you send auth_type, send the matching auth_value with it, or the request is a 422.

Delete a function

Deletes the function and detaches it from every agent.

text
DELETE /api/v1/functions/{function}

Who can call it: the owner, or a teammate with Functions.

bash
curl -X DELETE https://chat.example.com/api/v1/functions/0199f3d0-3c4d-7e5f-8a6b-7c8d9e0f1a2b \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is 204 No Content. To stop a function for a while without losing it, send "is_enabled": false instead.

List an agent's functions

Returns the functions attached to one agent, newest first.

text
GET /api/v1/agents/{agent}/functions

Who can call it: anyone with access to the agent.

bash
curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/functions \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": [function, …], "next_cursor": … }.

Attach a function to an agent

Lets the agent call one of your functions.

text
POST /api/v1/agents/{agent}/functions

Who can call it: the owner, or a teammate with Manage Functions.

Body field Type Required Notes
function_id string yes The id of one of your functions. Any other id is a 422.
bash
curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/functions \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "function_id": "0199f3d0-3c4d-7e5f-8a6b-7c8d9e0f1a2b" }'

The answer is 200 OK with { "data": function }.

Detach a function from an agent

Stops the agent from calling the function. The function itself stays in your workspace.

text
DELETE /api/v1/agents/{agent}/functions/{function}

Who can call it: the owner, or a teammate with Manage Functions.

bash
curl -X DELETE https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/functions/0199f3d0-3c4d-7e5f-8a6b-7c8d9e0f1a2b \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is 204 No Content.

Search guides, settings and commands.