DocumentationAPI ReferenceChangelog

Envocal API

API Reference Tools guide MCP server API Changelog

Endpoints

Tools guide

Create, test, share and assign Agent tools from your own systems with the Envocal API - the calls in order, the request config explained, and four complete examples you can send as they are.

Everything in Creating a Custom Tool can also be done from your own systems, or by an AI coding agent, with the Envocal API: create a tool, test it, share it and give it to an Agent. This page shows the calls in order and four complete tools you can send as they are.

In the API, a tool is one object with one id. You use that id to change, test and delete the tool, and to give it to an Agent.

A tool made with the API can be opened, tested and saved in the Studio's tool editor, and a tool made in the Studio can be read and changed with the API. For that to work, a tool's request holds only what the editor can show. The request has the rules, and a tool that breaks one is refused with a message that says what to write.

What you need

  • An API key with Write on Tools. Add Read on Vault to look up credentials and secrets, and Write on Agents to give tools to Agents.
  • The credential or secret the other system asks for, added in the Vault in the Studio. The API lists their names and ids so you can use them in a tool. It never returns a value, and it can't add or change them.

Give Tools write only to systems you trust

A tool sends a request to an address its author chooses, and carries the credential and secrets attached to it. A key with Write on Tools can use the credentials and secrets that the tenant's tools already use, and with Read on Vault also every other one in the Vault, and could make a tool that sends them to any address.

The examples use current for the key's own tenant. Put a sub-tenant's id there to work in a customer's tenant.

The calls in order

Find the credential or secret

If the other system needs authentication, look up what the tool will use:

curl https://api.envocal.ai/v1/tenants/current/vault/credentials \
  -H "Authorization: Bearer evk_eu_..."
[
  { "id": "5b0c5f6e-…", "name": "Order system", "type": "bearer" }
]

GET /v1/tenants/current/vault/secrets lists secrets the same way, with id and name. Use a credential when the other system takes a standard login such as a bearer token or basic auth: its header is added to the request for you. Use a secret for any other value that must stay hidden, such as an API key in a header of its own.

Create the tool

POST /v1/tenants/current/tools with the tool. Only name, description and config are needed:

curl -X POST https://api.envocal.ai/v1/tenants/current/tools \
  -H "Authorization: Bearer evk_eu_..." \
  -H "Content-Type: application/json" \
  -d @lookup_order.json

The answer is 201 Created with the tool, including its id and revision. The examples below are complete request bodies.

Test it

POST /v1/tenants/current/tools/{id}/test sends the tool's real request once, with the values you give for its variables, and returns what the other system answered:

curl -X POST https://api.envocal.ai/v1/tenants/current/tools/TOOL_ID/test \
  -H "Authorization: Bearer evk_eu_..." \
  -H "Content-Type: application/json" \
  -d '{ "agentVariables": { "order_id": "12345" } }'
{
  "statusCode": 200,
  "responseHeaders": { "Content-Type": "application/json" },
  "bodyText": "{\"id\":\"12345\",\"status\":\"shipped\"}",
  "bodyJson": { "id": "12345", "status": "shipped" },
  "outputVariables": {}
}

statusCode is the other system's answer. A 200 from the API with statusCode 401 inside means the request was sent and the other system refused it: check the credential. Send {} for a tool without variables.

  • Give each value under the variable's name, as above.
  • dynamicVariables and systemVariables take values the same way, for example { "systemVariables": { "system_caller_number": "+46701234567" } }.
  • outputVariables holds what the tool's response mapping read from the answer, under the dynamic variables' names.

Give it to an Agent

An Agent's tools are three lists of tool ids, one per phase. PUT replaces all three, so read them first and send them back with the new id added:

curl https://api.envocal.ai/v1/tenants/current/agents/AGENT_ID/tools \
  -H "Authorization: Bearer evk_eu_..."
curl -X PUT https://api.envocal.ai/v1/tenants/current/agents/AGENT_ID/tools \
  -H "Authorization: Bearer evk_eu_..." \
  -H "Content-Type: application/json" \
  -d '{ "before": [], "during": ["TOOL_ID"], "after": [] }'
PhaseWhen the tool runs
beforeWhen the conversation starts, before the Agent speaks, in list order
duringWhen the Agent decides to call it during the conversation
afterWhen the conversation has ended, in list order

A tool can only be placed in a phase that its availability includes.

The fields of a tool

FieldWhat it isIf you leave it out
nameThe function name the Agent calls: lower-case letters, digits and _, 2 to 64 characters, unique in the tenantRequired
descriptionTells the Agent what the tool does and when to use it. Write it for the AgentRequired
configThe request the tool sends, see The requestRequired
displayNameThe same name written for people, shown in the Studio: Lookup order for lookup_order. See The two namesSame as name
preToolSpeechA sentence the Agent says while the tool runsNone
availabilityThe phases the tool can be given to an Agent in: before, during, afterduring
channelsWhere the tool is offered: chat, voice_chat, phoneAll three
visibilityprivate, or shared to offer it as a template to this tenant and every tenant below itprivate
credentialIdThe Vault credential that authenticates the requestNone
credentialTypeThe type of credential the tool expects, such as bearer or basicThe type of credentialId

A Vault secret is not a field of the tool: the header that sends it holds the secret's id, see Where a value comes from.

A tool you read back also has id, tenantId, revision, createdAt, updatedAt and kind. kind is custom for the tools a tenant makes itself. More kinds may be added later: treat a kind you don't know as read-only.

The two names

A tool has one name, written two ways: name for the Agent (lookup_order) and displayName for people (Lookup order). In the API, name is the one you choose, and displayName can be left out.

The Studio makes the function name from the display name every time it saves a tool: lower case, with _ for spaces and other characters. So a displayName you send has to give your name by that rule:

namedisplayName
lookup_orderleft outTaken. The display name is lookup_order
lookup_orderLookup order or Lookup OrderTaken
lookup_orderOrder lookupRefused: it gives order_lookup. The message says so

A tool renamed in the Studio gets both names changed together, so read a tool before you update it.

The request

config.http is the request: method, url, timeoutSeconds, and lists of headers, query and path parameters, plus a body for POST, PUT and PATCH. config.variables declares the variables the request uses, and config.responseMapping says what to keep from the answer.

It holds what the Studio's tool editor can show, which is what lets a tool be edited from both sides. The Create a tool page has the complete schema.

Variables

A variable is declared once, in config.variables, and the request refers to it by its name.

Agent variable (config.variables.agent)Dynamic variable (config.variables.dynamic)
What it isA value the Agent fills in when it calls the toolA value kept during the conversation, for example from another tool's answer
nameThe parameter name the Agent sees: order_idThe variable's name, shared between tools and prompts: customer_id
jsonTypestring, number, integer, boolean, object or arrayThe same
Alsodescription (written for the Agent), required, enums (the allowed values), example (the value Run test in the Studio starts with)description (a note for people), placeholder (the value Run test in the Studio starts with)
  • A name has no spaces and no { or }, doesn't start with system_, and is used once among the tool's variables, agent and dynamic together. So a name alone always says which variable is meant.
  • To rename a variable, change its name and every place in the request that uses it, in the same update. A dynamic variable is shared between tools and prompts by its name, so under a new name it is another variable to them.
  • Agent variables can be used only in a tool whose availability is during alone, since it is the Agent that fills them in.

Where a value comes from

Every value in the request says where it comes from with inputType:

inputTypeThe value comes fromSet
staticA fixed valuevalue, always written as text: "items", "true", "5"
agentThe Agent, which fills it in when it calls the toolvarName: the name of an agent variable, such as order_id
dynamicEarlier in the conversation, for example another tool's responsevarName: the name of a dynamic variable, such as customer_id
systemThe conversation itselfvarName: the name of a system variable, such as system_caller_number
secretA Vault secretsecretId: the secret's id, from GET /v1/tenants/current/vault/secrets
templateText with placeholderstemplate: for example Phone {{system_caller_number}}

What each part of the request takes:

PartIts name is inTypesinputType
Headerkeystringstatic, dynamic, secret
Query parameternamestring, number, integer, boolean, object, arraystatic, agent, dynamic, system, and template for a string
Path parameternamestring, number, integer, booleanstatic, agent, dynamic, system
Body valuenamestring, number, integer, boolean, nullstatic, agent, dynamic, system, and template for a string
Body object or arraynameobject, arraystatic (it holds children), agent, dynamic
  • A variable and the value that takes it have the same type: a string query parameter takes a string variable.
  • A path parameter fills a {name} in the URL, as in https://api.example.com/orders/{order_id}. Every {name} in the URL has an item in path, and the other way round.
  • A secret can be used in a header only, and two headers with the same name can't both take one. Never put a password or key in the config as a static value: a shared tool's config is copied with every static value in it.
  • config.responseMapping reads values from a JSON response into dynamic variables, for later tools and for the Agent: { "dynamicVar": "customer_id", "jsonPath": "$.data.customer.id" }.

Examples

Each is a complete body for POST /v1/tenants/current/tools. The same four are in the OpenAPI document, as the examples of Create a tool, so a coding agent that is given the document has them too. The addresses and the ids are placeholders: replace the URLs, and the ids with ones from your own Vault.

Look up an order

A GET with a path parameter the Agent fills in, a fixed query parameter, and a bearer credential. The credential's Authorization header is added automatically.

{
  "name": "lookup_order",
  "description": "Looks up an order by its order number. Use it when the customer asks about an order.",
  "preToolSpeech": "One moment, let me look that up.",
  "credentialId": "8a6e0c5e-2f43-4c1b-9d7a-5b3f1e2a4c61",
  "config": {
    "schemaVersion": 1,
    "http": {
      "method": "GET",
      "url": "https://api.example.com/orders/{order_id}",
      "timeoutSeconds": 10,
      "headers": [],
      "query": [
        { "name": "expand", "type": "string", "inputType": "static", "value": "items" }
      ],
      "path": [
        { "name": "order_id", "type": "string", "inputType": "agent", "varName": "order_id" }
      ],
      "body": null
    },
    "variables": {
      "agent": [
        {
          "name": "order_id",
          "description": "The customer's order number, digits only.",
          "jsonType": "string",
          "required": true
        }
      ],
      "dynamic": []
    },
    "responseMapping": []
  }
}

Test it with { "agentVariables": { "order_id": "12345" } }.

Create a ticket

A POST with a JSON body built from two values the Agent provides, a fixed value and a template, and a Vault secret in a header of its own.

{
  "name": "create_ticket",
  "displayName": "Create ticket",
  "description": "Creates a support ticket. Use it when the customer wants a problem followed up.",
  "channels": ["phone", "chat"],
  "config": {
    "schemaVersion": 1,
    "http": {
      "method": "POST",
      "url": "https://helpdesk.example.com/api/tickets",
      "timeoutSeconds": 15,
      "headers": [
        {
          "key": "X-Api-Key",
          "type": "string",
          "inputType": "secret",
          "secretId": "c41d7f0a-9b6e-4d52-8e13-7a2f5c9b0d34"
        }
      ],
      "query": [],
      "path": [],
      "body": {
        "rootKind": "object",
        "nodes": [
          { "name": "subject", "type": "string", "inputType": "agent", "varName": "subject" },
          { "name": "priority", "type": "string", "inputType": "agent", "varName": "priority" },
          { "name": "source", "type": "string", "inputType": "static", "value": "voice-agent" },
          {
            "name": "caller",
            "type": "string",
            "inputType": "template",
            "template": "Phone {{system_caller_number}}"
          }
        ]
      }
    },
    "variables": {
      "agent": [
        {
          "name": "subject",
          "description": "One sentence describing the problem.",
          "jsonType": "string",
          "required": true
        },
        {
          "name": "priority",
          "description": "How urgent it is.",
          "jsonType": "string",
          "enums": ["low", "normal", "high"],
          "required": false
        }
      ],
      "dynamic": []
    },
    "responseMapping": []
  }
}

Test it with { "agentVariables": { "subject": "Router is offline", "priority": "high" }, "systemVariables": { "system_caller_number": "+46701234567" } }. The other system receives:

{ "subject": "Router is offline", "priority": "high", "source": "voice-agent", "caller": "Phone +46701234567" }

Look up the caller before the call starts

A tool for the before phase: it runs when the conversation starts, finds the customer by the number they call from, and keeps the customer's id as a dynamic variable for the Agent and for later tools.

{
  "name": "lookup_caller",
  "description": "Finds the customer by the number they call from, before the conversation starts.",
  "availability": ["before"],
  "channels": ["phone"],
  "config": {
    "schemaVersion": 1,
    "http": {
      "method": "GET",
      "url": "https://crm.example.com/customers/search",
      "timeoutSeconds": 5,
      "headers": [],
      "query": [
        { "name": "phone", "type": "string", "inputType": "system", "varName": "system_caller_number" }
      ],
      "path": [],
      "body": null
    },
    "variables": {
      "agent": [],
      "dynamic": [
        { "name": "customer_id", "jsonType": "string" }
      ]
    },
    "responseMapping": [
      { "dynamicVar": "customer_id", "jsonPath": "$.data.customer.id" }
    ]
  }
}

Test it with { "systemVariables": { "system_caller_number": "+46701234567" } }. With a response like { "data": { "customer": { "id": "C-42" } } }, the test's outputVariables shows { "customer_id": "C-42" }.

Book an appointment

A POST with an object and a list in the body, the customer id that the previous example stored, and numbers and booleans. A fixed number or boolean is written as text ("30", "true"). A number or a boolean from the Agent is a variable of that type.

{
  "name": "book_appointment",
  "displayName": "Book appointment",
  "description": "Books an appointment for the customer. Use it once the customer has chosen a day and a time.",
  "channels": ["phone", "voice_chat"],
  "credentialId": "8a6e0c5e-2f43-4c1b-9d7a-5b3f1e2a4c61",
  "config": {
    "schemaVersion": 1,
    "http": {
      "method": "POST",
      "url": "https://booking.example.com/api/appointments",
      "timeoutSeconds": 20,
      "headers": [
        { "key": "X-Source", "type": "string", "inputType": "static", "value": "envocal" }
      ],
      "query": [
        { "name": "notify", "type": "boolean", "inputType": "static", "value": "true" }
      ],
      "path": [],
      "body": {
        "rootKind": "object",
        "nodes": [
          {
            "name": "customer",
            "type": "object",
            "inputType": "static",
            "children": [
              { "name": "id", "type": "string", "inputType": "dynamic", "varName": "customer_id" },
              { "name": "phone", "type": "string", "inputType": "system", "varName": "system_caller_number" }
            ]
          },
          { "name": "start", "type": "string", "inputType": "agent", "varName": "start_time" },
          { "name": "durationMinutes", "type": "integer", "inputType": "static", "value": "30" },
          { "name": "people", "type": "integer", "inputType": "agent", "varName": "people" },
          { "name": "firstVisit", "type": "boolean", "inputType": "agent", "varName": "first_visit" },
          {
            "name": "tags",
            "type": "array",
            "inputType": "static",
            "children": [
              { "type": "string", "inputType": "static", "value": "voice-agent" },
              { "type": "string", "inputType": "agent", "varName": "reason" }
            ]
          },
          {
            "name": "note",
            "type": "string",
            "inputType": "template",
            "template": "Booked by phone for customer {{customer_id}}: {{reason}}"
          }
        ]
      }
    },
    "variables": {
      "agent": [
        {
          "name": "start_time",
          "description": "Start of the appointment as an ISO 8601 date and time, for example 2026-03-14T09:30:00.",
          "jsonType": "string",
          "required": true
        },
        {
          "name": "people",
          "description": "How many people are coming.",
          "jsonType": "integer",
          "required": true
        },
        {
          "name": "first_visit",
          "description": "True if the customer has not been here before.",
          "jsonType": "boolean",
          "required": true
        },
        {
          "name": "reason",
          "description": "In a few words, what the appointment is for.",
          "jsonType": "string",
          "required": true
        }
      ],
      "dynamic": [
        { "name": "customer_id", "jsonType": "string" },
        { "name": "booking_id", "jsonType": "string" }
      ]
    },
    "responseMapping": [
      { "dynamicVar": "booking_id", "jsonPath": "$.id" }
    ]
  }
}

Test it with:

{
  "agentVariables": { "start_time": "2026-03-14T09:30:00", "people": 2, "first_visit": true, "reason": "check-up" },
  "dynamicVariables": { "customer_id": "C-42" },
  "systemVariables": { "system_caller_number": "+46701234567" }
}

The other system receives:

{
  "customer": { "id": "C-42", "phone": "+46701234567" },
  "start": "2026-03-14T09:30:00",
  "durationMinutes": 30,
  "people": 2,
  "firstVisit": true,
  "tags": ["voice-agent", "check-up"],
  "note": "Booked by phone for customer C-42: check-up"
}

Change or delete a tool

To change a tool, read it, change what you need and send all of it back with PUT /v1/tenants/current/tools/{id}, including the revision you read:

  • The whole tool is replaced. A field you leave out gets its default, as when creating: no credential, for example.
  • id, kind and the timestamps are ignored if you send them, so you can send back what you read.
  • A variable is the same variable for as long as it keeps its name.
  • If someone changed the tool after you read it, you get 409. Read it again and retry.

DELETE /v1/tenants/current/tools/{id} removes a tool. While an Agent uses it you get 409: take it out of the Agents' tool lists first.

Copy a shared tool

A tool set to shared is offered as a template to its own tenant and every tenant below it, as with Use Existing Tool in the Studio.

curl https://api.envocal.ai/v1/tenants/current/tool-templates \
  -H "Authorization: Bearer evk_eu_..."

Each template shows who shares it, its description, the credentialType a copy needs and its config. A header that takes a secret is shown without a secretId. Make a copy with:

curl -X POST https://api.envocal.ai/v1/tenants/current/tool-templates/TEMPLATE_ID/instantiate \
  -H "Authorization: Bearer evk_eu_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "orders_lookup", "displayName": "Orders lookup" }'

Send {} to keep the template's names, or a name alone to use it as the display name too. The copy is a private tool of your own: the request, the variables, the response mapping, phases and channels are copied, the credential and the secrets are not. Set credentialId, and a secretId of your own on each header that takes a secret, with a PUT on the copy, then test it. Changing the copy never changes the template, and later changes to the template don't reach the copy.

When a call is refused

StatusWhyWhat to do
400 on create or updateSomething in the tool can't be savederrors lists every problem at once, each with the field it is about and what to write, for example config.http.path[0].varName 'order' is not the name of a variable in config.variables.agent.
400 on testThe request could not be madeerror says why: a variable is missing, the credential or a secret isn't set up, the address can't be reached, or the other system didn't answer within timeoutSeconds
403The key lacks the permission, or the tenant is outside its reachThe message names the missing permission
404No such tool or template in this tenantCheck the id and the tenant in the URL
409The name is taken, the revision is stale, or an Agent still uses the toolChoose another name, read the tool again, or remove it from the Agents first
429Too many callsWait the number of seconds in the Retry-After header. Testing has its own limit of 30 tests a minute per key

Related topics

  • Creating a Custom Tool
  • Complete Examples
  • Vault
  • Agents: Tools

API Reference

Provision tenants, agents and their tools, knowledge bases and phone numbers, and read conversations and usage, from your own systems.

MCP server

Connect an AI assistant to Envocal with the Model Context Protocol, and let it build and manage Agents, tools and knowledge bases while you talk to it. Add Envocal to Claude or ChatGPT as a custom connector and sign in, or connect Claude Code, Cursor or VS Code with an API key.

On this page

What you needThe calls in orderFind the credential or secretCreate the toolTest itGive it to an AgentThe fields of a toolThe two namesThe requestVariablesWhere a value comes fromExamplesLook up an orderCreate a ticketLook up the caller before the call startsBook an appointmentChange or delete a toolCopy a shared toolWhen a call is refused