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

Create a tool from a template

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.

List credentials GET

The credentials in the tenant's vault that tools can authenticate with, by name. Use a credential's id as a tool's credentialId. Credentials are created and changed in the Studio (Vault); the API returns their name and type only, never their settings or secret values.

POST
/v1/tenants/{tenantId}/tool-templates/{templateId}/instantiate

Copies a tool template into a new private tool of the tenant: the request with its static values, the variables, the response mapping, phases, channels and the credential type. The credential and the vault secrets are not copied: set credentialId, and secretId on each header that takes a secret, on the new tool with PUT /v1/tenants/{tenantId}/tools/{id}.

The copy is the tenant's own. Changing it never changes the template, and later changes to the template don't reach the copy.

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.

templateId*string

Template id (from the template list).

Formatuuid

Request Body

Names for the copy. Send {} to keep the template's.

  1. body
  1. body
  2. …

What to call the copy of a tool template. Send {} to keep the template's own names.

name?string

Function name of the new tool: lower-case letters, digits and _, 2 to 64 characters, unique in the tenant. Left out: the template's name.

displayName?string

The same name written for people, shown in the Studio; it has to give name, as when creating a tool. Left out: the template's when it fits the name, else the same as name.

description?string

Description for the AI model. Left out: the template's.

Response Body

Created. The Location header points to the new tool.

  1. response
  1. response
  2. …

A tool a tenant's agents can use: an HTTP request, the variables it needs and the credential it authenticates with.

id?string

Tool id. Use it to update, delete and test the tool, and in an agent's tool assignments.

Formatuuid
tenantId*string

Tenant the tool belongs to.

kind*string

Where the tool's definition comes from. custom: made by the tenant, from scratch or as a copy of a tool template; everything can be changed. More kinds may be added later (e.g. tools of a connected integration): treat a kind you don't know as read-only.

name*string

Function name the AI model calls: lower-case letters, digits and _, 2 to 64 characters, unique in the tenant (e.g. lookup_order).

displayName*string

Name shown in the Studio: the same name written for people (e.g. Lookup order).

description*string

Tells the AI model what the tool does and when to use it. Write it for the model.

preToolSpeech?string

Optional sentence the AI says while the tool runs, e.g. "One moment, let me look that up."

availability*array<>

Phases the tool can be given to an agent in: before (runs when the conversation starts), during (the AI model calls it), after (runs when the conversation has ended).

channels*array<>

Channels the tool is used on, in every phase (chat is text chat): in a conversation on another channel the tool is left out.

visibility*string

private: only this tenant uses it. shared: it is also offered as a tool template to this tenant and every tenant below it.

Value in"private""shared"
credentialType?string

Type of credential the tool authenticates with (the type of a vault credential, e.g. bearer or basic), or null for none.

credentialId?string

Vault credential that authenticates the tool's requests (GET /v1/tenants/{tenantId}/vault/credentials), or null.

Formatuuid
config?

The request the tool sends. A header that takes a vault secret holds the secret's id (secretId); a secret's value is never returned.

revision?integer

Changes with every update. Send back the value you read when updating.

Formatint32
createdAt?string

Creation time (UTC).

Formatdate-time
updatedAt?string

Last update time (UTC).

Formatdate-time
Example Request
curl -X POST 'https://api.envocal.ai/v1/tenants/string/tool-templates/497f6eca-6276-4993-bfeb-53cbbbba6f08/instantiate' \  -H 'Content-Type: application/json' \  -d '{  "name": "orders_lookup",  "displayName": "Orders lookup"}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "tenantId": "string",  "kind": "string",  "name": "string",  "displayName": "string",  "description": "string",  "preToolSpeech": "string",  "availability": [    "before"  ],  "channels": [    "chat"  ],  "visibility": "private",  "credentialType": "string",  "credentialId": "f568fec0-10b6-4b94-9daf-e62c50c9bf3e",  "config": {    "schemaVersion": 0,    "http": {      "method": "GET",      "url": "string",      "timeoutSeconds": 0,      "headers": [        {          "key": "string",          "name": "string",          "type": "string",          "inputType": "static",          "value": "string",          "varName": "string",          "secretId": "c39edb4b-1d7b-4287-b1be-9dcaba334a25",          "template": "string"        }      ],      "query": [        {          "key": "string",          "name": "string",          "type": "string",          "inputType": "static",          "value": "string",          "varName": "string",          "secretId": "c39edb4b-1d7b-4287-b1be-9dcaba334a25",          "template": "string"        }      ],      "path": [        {          "key": "string",          "name": "string",          "type": "string",          "inputType": "static",          "value": "string",          "varName": "string",          "secretId": "c39edb4b-1d7b-4287-b1be-9dcaba334a25",          "template": "string"        }      ],      "body": {        "rootKind": "object",        "nodes": [          {            "id": "string",            "name": "string",            "type": "string",            "inputType": "static",            "value": "string",            "varName": "string",            "template": "string",            "children": [              {}            ]          }        ]      },      "bodyTransform": {        "type": "mimeEmail",        "encoding": "base64",        "output": {          "mode": "jsonPath",          "path": "string"        }      }    },    "variables": {      "agent": [        {          "name": "string",          "description": "string",          "jsonType": "string",          "enums": [            null          ],          "example": "string",          "required": true        }      ],      "dynamic": [        {          "name": "string",          "jsonType": "string",          "description": "string",          "placeholder": "string"        }      ]    },    "responseMapping": [      {        "dynamicVar": "string",        "jsonPath": "string"      }    ]  },  "revision": 0,  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}
POST
/v1/tenants/{tenantId}/tool-templates/{templateId}/instantiate
Example Request
curl -X POST 'https://api.envocal.ai/v1/tenants/string/tool-templates/497f6eca-6276-4993-bfeb-53cbbbba6f08/instantiate' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "orders_lookup",
  "displayName": "Orders lookup"
}'
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "tenantId": "string",
  "kind": "string",
  "name": "string",
  "displayName": "string",
  "description": "string",
  "preToolSpeech": "string",
  "availability": [
    "before"
  ],
  "channels": [
    "chat"
  ],
  "visibility": "private",
  "credentialType": "string",
  "credentialId": "f568fec0-10b6-4b94-9daf-e62c50c9bf3e",
  "config": {
    "schemaVersion": 0,
    "http": {
      "method": "GET",
      "url": "string",
      "timeoutSeconds": 0,
      "headers": [
        {
          "key": "string",
          "name": "string",
          "type": "string",
          "inputType": "static",
          "value": "string",
          "varName": "string",
          "secretId": "c39edb4b-1d7b-4287-b1be-9dcaba334a25",
          "template": "string"
        }
      ],
      "query": [
        {
          "key": "string",
          "name": "string",
          "type": "string",
          "inputType": "static",
          "value": "string",
          "varName": "string",
          "secretId": "c39edb4b-1d7b-4287-b1be-9dcaba334a25",
          "template": "string"
        }
      ],
      "path": [
        {
          "key": "string",
          "name": "string",
          "type": "string",
          "inputType": "static",
          "value": "string",
          "varName": "string",
          "secretId": "c39edb4b-1d7b-4287-b1be-9dcaba334a25",
          "template": "string"
        }
      ],
      "body": {
        "rootKind": "object",
        "nodes": [
          {
            "id": "string",
            "name": "string",
            "type": "string",
            "inputType": "static",
            "value": "string",
            "varName": "string",
            "template": "string",
            "children": [
              {}
            ]
          }
        ]
      },
      "bodyTransform": {
        "type": "mimeEmail",
        "encoding": "base64",
        "output": {
          "mode": "jsonPath",
          "path": "string"
        }
      }
    },
    "variables": {
      "agent": [
        {
          "name": "string",
          "description": "string",
          "jsonType": "string",
          "enums": [
            null
          ],
          "example": "string",
          "required": true
        }
      ],
      "dynamic": [
        {
          "name": "string",
          "jsonType": "string",
          "description": "string",
          "placeholder": "string"
        }
      ]
    },
    "responseMapping": [
      {
        "dynamicVar": "string",
        "jsonPath": "string"
      }
    ]
  },
  "revision": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}