Endpoints Personalizados

Los endpoints personalizados son las herramientas invocables del agente: una peticion HTTP saliente que el agente realiza durante la llamada, por ejemplo "crear un lead en el CRM" o "consultar el estado de un pedido". El agente decide cuando llamar a una a partir de su descripcion, VOCALS realiza la peticion y la respuesta se devuelve al mismo turno. Para el comportamiento y el editor del dashboard, consulta Endpoints Personalizados en la guia de usuario.

Los endpoints pertenecen a un unico agente y viven bajo /agents/{agent_id}/custom-endpoints. Todas las rutas aceptan la misma autenticacion que el resto de la API publica: envia tu clave en la cabecera X-API-Key (tambien funciona un JWT Bearer), de modo que las herramientas se pueden registrar y actualizar desde un script y no solo desde el dashboard. El espacio de trabajo de la clave es el unico al que puede llegar: un agente de otro espacio responde 404 Not Found. La URL base es https://api.usevocals.com/api/v1.

Endpoints

Metodo	Ruta	Proposito
GET	/agents/{agent_id}/custom-endpoints	Lista los endpoints del agente (mas antiguos primero)
POST	/agents/{agent_id}/custom-endpoints	Crea un endpoint
GET	/agents/{agent_id}/custom-endpoints/{endpoint_id}	Obtiene un endpoint
PATCH	/agents/{agent_id}/custom-endpoints/{endpoint_id}	Actualiza un endpoint
DELETE	/agents/{agent_id}/custom-endpoints/{endpoint_id}	Elimina un endpoint

Cada agente admite hasta 20 endpoints; crear uno mas por encima del limite devuelve 422 Unprocessable Entity.

Esquema del Endpoint

CustomEndpointResponse lo devuelven las rutas de listado, obtencion, creacion y actualizacion.

Campo	Tipo	Descripcion
id	uuid	ID del endpoint
agent_id	uuid	ID del agente propietario
subagent_id	uuid | null	El subagente al que esta acotada la herramienta, o null si es del agente completo
name	string	Nombre de la herramienta con el que la IA se refiere a este endpoint
description	string	Indica a la IA cuando y por que llamar a la herramienta
http_method	string	GET, POST, PUT, PATCH o DELETE
url_template	string	URL de destino, puede contener marcadores {{variable}}
headers	array	Cabeceras configuradas como { "name": ..., "has_value": true }. Los valores almacenados nunca se devuelven.
body_template	string | null	Cuerpo de la peticion, puede contener marcadores {{variable}}
parameters	array	Definiciones de parametros que la IA rellena a partir de la conversacion
timeout_seconds	integer	Tiempo de espera de la peticion, de 1 a 60
is_enabled	boolean	Si la herramienta se ofrece al agente
created_at	datetime	Marca de tiempo de creacion
updated_at	datetime	Marca de tiempo de la ultima actualizacion

Los valores de cabecera son de solo escritura

El valor de una cabecera es un secreto. Se cifra al guardarlo y nunca se devuelve en ninguna ruta: las lecturas solo muestran has_value, asi que no existe ninguna llamada de la API que recupere un valor almacenado. Para rotarlo, envia la cabecera de nuevo con un value nuevo.

Parametros

Cada entrada de parameters describe un valor que la IA recoge durante la conversacion y aporta al invocar la herramienta:

Campo	Tipo	Requerido	Descripcion
name	string	Si	Letras minusculas, digitos y guiones bajos, empezando por una letra. Debe ser unico dentro del endpoint y no puede coincidir con el nombre de una variable integrada.
description	string	Si	Que debe recoger la IA
type	string	Si	string, number, integer o boolean
required	boolean	No	Si la IA debe aportarlo (por defecto false)

Referencia un parametro como {{name}} en url_template, en el valor de cualquier cabecera o en body_template. Los mismos marcadores tambien resuelven variables integradas y variables personalizadas del agente: consulta Variables Dinámicas.

Listar Endpoints

GET /agents/{agent_id}/custom-endpoints

Devuelve los endpoints propios del agente, los mas antiguos primero. Anade ?subagent_id={subagent_id} para listar los de un subagente.

curl -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  https://api.usevocals.com/api/v1/agents/{agent_id}/custom-endpoints

Respuesta

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_id": "9f8b7c6d-1234-4a5b-9c8d-abcdef012345",
    "subagent_id": null,
    "name": "create_lead",
    "description": "Crea un lead en el CRM cuando la persona da su nombre.",
    "http_method": "POST",
    "url_template": "https://api.example.com/v1/leads",
    "headers": [{ "name": "Authorization", "has_value": true }],
    "body_template": "{\"name\": \"{{customer_name}}\", \"phone\": \"{{caller_number}}\"}",
    "parameters": [
      {
        "name": "customer_name",
        "description": "Nombre completo de quien llama",
        "type": "string",
        "required": true
      }
    ],
    "timeout_seconds": 8,
    "is_enabled": true,
    "created_at": "2026-06-01T10:30:00Z",
    "updated_at": "2026-06-01T10:30:00Z"
  }
]

Crear Endpoint

POST /agents/{agent_id}/custom-endpoints

Cuerpo de la Peticion

{
  "name": "create_lead",
  "description": "Crea un lead en el CRM cuando la persona da su nombre.",
  "http_method": "POST",
  "url_template": "https://api.example.com/v1/leads",
  "headers": [{ "name": "Authorization", "value": "Bearer crm-token" }],
  "body_template": "{\"name\": \"{{customer_name}}\"}",
  "parameters": [
    {
      "name": "customer_name",
      "description": "Nombre completo de quien llama",
      "type": "string",
      "required": true
    }
  ],
  "timeout_seconds": 8,
  "is_enabled": true
}

Campos de la Peticion

Campo	Tipo	Requerido	Por defecto	Descripcion
name	string	Si	--	Nombre de la herramienta. Letras minusculas, digitos y guiones bajos, empezando por una letra, hasta 64 caracteres. Debe ser unico en el agente y no puede empezar por hubspot_, calendar_, shopify_ ni custom_.
description	string	Si	--	Cuando y por que debe llamar la IA a la herramienta
http_method	string	Si	--	GET, POST, PUT, PATCH o DELETE
url_template	string	Si	--	URL de destino. Debe usar http o https y resolver a una direccion publica.
headers	array	No	[]	Cabeceras de la peticion, cada una { "name": ..., "value": ... }. Al crear, value es obligatorio.
body_template	string	No	null	Cuerpo de la peticion. Se envia como application/json salvo que configures tu propia cabecera Content-Type.
parameters	array	No	[]	Definiciones de parametros (ver arriba)
timeout_seconds	integer	No	10	Tiempo de espera de la peticion, de 1 a 60
is_enabled	boolean	No	true	Si la herramienta se ofrece al agente
subagent_id	uuid	No	null	Acota la herramienta a un subagente en lugar de a todo el agente. Solo existe mientras ese subagente esta activo y sigue contando para el limite de 20 del agente.

curl -X POST https://api.usevocals.com/api/v1/agents/{agent_id}/custom-endpoints \
  -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "create_lead",
    "description": "Crea un lead en el CRM cuando la persona da su nombre.",
    "http_method": "POST",
    "url_template": "https://api.example.com/v1/leads",
    "headers": [{ "name": "Authorization", "value": "Bearer crm-token" }],
    "body_template": "{\"name\": \"{{customer_name}}\"}",
    "parameters": [
      { "name": "customer_name", "description": "Nombre completo de quien llama", "type": "string", "required": true }
    ],
    "timeout_seconds": 8
  }'

Respuesta

201 Created - Devuelve el CustomEndpointResponse. El valor de cabecera que enviaste no se devuelve; aparece como has_value: true.

La API devuelve 422 Unprocessable Entity cuando el nombre es invalido, ya existe en el agente o empieza por un prefijo reservado; cuando el metodo no esta soportado; cuando la URL no es una direccion publica http/https; cuando un parametro es invalido, esta duplicado o coincide con el nombre de una variable integrada; cuando timeout_seconds esta fuera del rango de 1 a 60; o cuando el agente ya alcanzo el limite de 20 endpoints. Devuelve 404 Not Found cuando el agente no existe en tu espacio de trabajo.

Obtener Endpoint

GET /agents/{agent_id}/custom-endpoints/{endpoint_id}

curl -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  https://api.usevocals.com/api/v1/agents/{agent_id}/custom-endpoints/{endpoint_id}

Respuesta

200 OK - Devuelve el CustomEndpointResponse, o 404 Not Found.

Actualizar Endpoint

PATCH /agents/{agent_id}/custom-endpoints/{endpoint_id}

Actualizacion parcial: envia solo los campos que quieras cambiar. Desactivar una herramienta, por ejemplo, es una llamada de un solo campo.

curl -X PATCH https://api.usevocals.com/api/v1/agents/{agent_id}/custom-endpoints/{endpoint_id} \
  -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"is_enabled": false}'

Actualizar cabeceras

headers se reemplaza por completo, no se fusiona: la lista que envias pasa a ser el conjunto completo de cabeceras del endpoint, y cualquier cabecera que omitas se elimina. Dentro de esa lista, cada entrada lleva un value nuevo (que reemplaza el secreto almacenado) u omite value (lo que conserva el secreto almacenado). Omitir value en una cabecera que no tiene ninguno almacenado devuelve 422.

{
  "headers": [
    { "name": "Authorization" },
    { "name": "X-Account", "value": "acct_42" }
  ]
}

Esa peticion conserva intacto el secreto de Authorization y establece un nuevo valor para X-Account.

Respuesta

200 OK - Devuelve el CustomEndpointResponse actualizado. Se aplican las mismas reglas de validacion 422 que en la creacion.

Eliminar Endpoint

DELETE /agents/{agent_id}/custom-endpoints/{endpoint_id}

Elimina un endpoint. La herramienta deja de ofrecerse al agente a partir de la siguiente llamada; las llamadas en curso no se ven afectadas.

curl -X DELETE https://api.usevocals.com/api/v1/agents/{agent_id}/custom-endpoints/{endpoint_id} \
  -H "X-API-Key: voc_a1b2c3d4e5f6..."

Respuesta

204 No Content - Sin cuerpo de respuesta.