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
`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 del agente, los mas antiguos primero.

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",
    "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

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.

Endpoints​

Esquema del Endpoint​

Los valores de cabecera son de solo escritura​

Parametros​

Listar Endpoints​

Respuesta​

Crear Endpoint​

Cuerpo de la Peticion​

Campos de la Peticion​

Respuesta​

Obtener Endpoint​

Respuesta​

Actualizar Endpoint​

Actualizar cabeceras​

Respuesta​

Eliminar Endpoint​

Respuesta​

Endpoints

Esquema del Endpoint

Los valores de cabecera son de solo escritura

Parametros

Listar Endpoints

Respuesta

Crear Endpoint

Cuerpo de la Peticion

Campos de la Peticion

Respuesta

Obtener Endpoint

Respuesta

Actualizar Endpoint

Actualizar cabeceras

Respuesta

Eliminar Endpoint

Respuesta