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

List tools GET

The tools the tenant has made for its agents, newest first. Give a tool to an agent with PUT /v1/tenants/{tenantId}/agents/{id}/tools, using the tool's id.

Get a tool GET

One tool with everything it is made of: the request, its variables, and the ids of the credential and secrets it uses.

POST
/v1/tenants/{tenantId}/tools

Creates an HTTP tool the tenant's agents can use. Only name, description and config are needed.

config describes the request (the ToolHttpConfig schema). A tool made here can be opened, tested and saved in the Studio's tool editor, and the other way round, so the config takes what the editor can show. Anything else is refused with a message that says what to write.

Arguments the AI model should provide go in config.variables.agent, each with a name (for example order_id). A part of the request takes one with inputType: "agent" and that name as its varName; a text takes one as {{order_id}}.

To authenticate, set credentialId to a vault credential: its header is added to the request. For any other secret value (an API key in a header of its own), give the header inputType: "secret" and the vault secret's id as its secretId. A secret can be used in a header only. Never put a secret in the config as a static value.

Next: try it with POST /v1/tenants/{tenantId}/tools/{id}/test, then give it to an agent with PUT /v1/tenants/{tenantId}/agents/{id}/tools.

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.

Request Body

The tool.

  1. body
  1. body
  2. …

A new tool.

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

The same name written for people, shown in the Studio (e.g. Lookup order for lookup_order). The Studio makes the function name from it, in lower case with _ for spaces and other characters, and that has to give name. Left out: the same as name.

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.

availability?array<>

Phases the tool can be given to an agent in. Left out: during. Agent variables can be used only in a tool that is during alone.

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. Left out: all three.

visibility?string

private (the default) or shared.

Value in"private""shared"
credentialType?string

Type of credential the tool authenticates with. Left out: the type of credentialId, or none.

credentialId?string

Vault credential that authenticates the tool's requests. Its header is added to the request automatically.

Formatuuid
config*

The request the tool sends. Required.

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
curl -X POST 'https://api.envocal.ai/v1/tenants/string/tools' \  -H 'Content-Type: application/json' \  -d '{  "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": []  }}'
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"}
curl -X POST 'https://api.envocal.ai/v1/tenants/string/tools' \
  -H 'Content-Type: application/json' \
  -d '{
  "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": []
  }
}'
{
  "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}/tools