One tool with everything it is made of: the request, its variables, and the ids of the credential and secrets it uses.
Required permission: tools:read
BearerAuthorizationBearer <token>Tenant API key (evk_…), created in Studio → Vault → API keys.
tenantId*stringTenant id, or current for the key's own tenant. Must be the key's tenant or one of its sub-tenants.
id*stringTool id.
uuidThe tool.
A tool a tenant's agents can use: an HTTP request, the variables it needs and the credential it authenticates with.
id?stringTool id. Use it to update, delete and test the tool, and in an agent's tool assignments.
uuidtenantId*stringTenant the tool belongs to.
kind*stringWhere 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*stringFunction name the AI model calls: lower-case letters, digits and _, 2 to 64 characters, unique in the tenant (e.g. lookup_order).
displayName*stringName shown in the Studio: the same name written for people (e.g. Lookup order).
description*stringTells the AI model what the tool does and when to use it. Write it for the model.
preToolSpeech?stringOptional 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*stringprivate: only this tenant uses it. shared: it is also offered as a tool template to this tenant and every tenant below it.
"private""shared"credentialType?stringType of credential the tool authenticates with (the type of a vault credential, e.g. bearer or basic), or null for none.
credentialId?stringVault credential that authenticates the tool's requests (GET /v1/tenants/{tenantId}/vault/credentials), or null.
uuidconfig?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?integerChanges with every update. Send back the value you read when updating.
int32createdAt?stringCreation time (UTC).
date-timeupdatedAt?stringLast update time (UTC).
date-timecurl -X GET 'https://api.envocal.ai/v1/tenants/string/tools/497f6eca-6276-4993-bfeb-53cbbbba6f08'{ "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 GET 'https://api.envocal.ai/v1/tenants/string/tools/497f6eca-6276-4993-bfeb-53cbbbba6f08'{
"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"
}