DocumentationAPI ReferenceChangelog

Envocal API

API Reference Tools guide MCP server API Changelog

Endpoints

List tools GETCreate a tool POSTGet a tool GETDelete a tool DELETEUpdate a tool PUTTest a tool POSTList tool templates GETCreate a tool from a template POST
Tools

Test a tool

Update a tool PUT

Replaces the tool: read it, change what you need and send all of it back, with the revision you read. A field you leave out gets its default, as when creating: no credential, for example. In config, a variable that keeps its name is the same variable as before, and one with a new name is a new variable. Fields you can't set (id, kind, the timestamps) are ignored if you send them.

List tool templates GET

Tools the tenant can copy: the ones the tenant itself and the tenants above it have set to shared. Make a copy with POST /v1/tenants/{tenantId}/tool-templates/{templateId}/instantiate.

POST
/v1/tenants/{tenantId}/tools/{id}/test

Sends the tool's real request once, with the variable values you give, and returns what the other system answered: as an agent would call it in a conversation. This reaches the other system for real, so a tool that changes something there changes it.

Give every agent variable the tool needs in agentVariables, under the variable's name. The answer's statusCode is the other system's: a 200 here with statusCode 401 means the request was sent and refused there. outputVariables holds what the tool's responseMapping read from the answer, under the dynamic variables' names.

Required permission: tools:write

Authorization

Bearer
headerAuthorizationBearer <token>

Tenant API key (evk_…), created in Studio → Vault → API keys.

Path Parameters

tenantId*string

Tenant id, or current for the key's own tenant. Must be the key's tenant or one of its sub-tenants.

id*string

Tool id.

Formatuuid

Request Body

Variable values to run with. Send {} for a tool without variables.

  1. body
  1. body
  2. …

Variable values to test a tool with.

agentVariables?

Arguments as the AI model would pass them, by agent variable name, e.g. {"order_id": "12345"}.

dynamicVariables?

Dynamic (conversation) variables by name, e.g. {"customer_id": "C-42"}.

systemVariables?

System variables by name, e.g. {"system_caller_number": "+46701234567"}.

Response Body

The other system's response, and the dynamic variables read from it.

  1. response
  1. response
  2. …

The response of the external system.

statusCode?integer

HTTP status code returned by the external system.

Formatint32
responseHeaders?

Response headers.

bodyText?string

Response body as text.

bodyJson?unknown

Response body parsed as JSON, when it is JSON.

outputVariables?

Dynamic variables read from the response by the tool's responseMapping. The public API gives them under the variables' names.

curl -X POST 'https://api.envocal.ai/v1/tenants/string/tools/497f6eca-6276-4993-bfeb-53cbbbba6f08/test' \  -H 'Content-Type: application/json' \  -d '{  "agentVariables": {    "order_id": "12345"  }}'
Example Response

statusCode is the other system's status. outputVariables holds what the tool's responseMapping read from the answer, under the dynamic variables' names.

{  "statusCode": 200,  "responseHeaders": {    "Content-Type": "application/json"  },  "bodyText": "{\"data\":{\"customer\":{\"id\":\"C-42\",\"name\":\"Ada\"}}}",  "bodyJson": {    "data": {      "customer": {        "id": "C-42",        "name": "Ada"      }    }  },  "outputVariables": {    "customer_id": "C-42"  }}
curl -X POST 'https://api.envocal.ai/v1/tenants/string/tools/497f6eca-6276-4993-bfeb-53cbbbba6f08/test' \
  -H 'Content-Type: application/json' \
  -d '{
  "agentVariables": {
    "order_id": "12345"
  }
}'
{
  "statusCode": 200,
  "responseHeaders": {
    "Content-Type": "application/json"
  },
  "bodyText": "{\"data\":{\"customer\":{\"id\":\"C-42\",\"name\":\"Ada\"}}}",
  "bodyJson": {
    "data": {
      "customer": {
        "id": "C-42",
        "name": "Ada"
      }
    }
  },
  "outputVariables": {
    "customer_id": "C-42"
  }
}
POST
/v1/tenants/{tenantId}/tools/{id}/test