Skip to main content
POST
Crear una conexión entre un agente y la tool indicada

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-workspace-id
string<uuid>

Identificador del workspace multi-tenant. Obligatorio al autenticar con Authorization: Bearer, donde su ausencia devuelve 400 Workspace context is required. Con x-api-key es opcional: la llave ya identifica a su workspace y lo que mandes aquí se ignora.

Idempotency-Key
string

Clave única por operación para asegurar idempotencia en requests mutativos. Es opcional —sin ella la petición se ejecuta igual, pero un reintento crea una ejecución nueva—. Si se envía, debe medir entre 16 y 128 caracteres; fuera de ese rango la petición responde 400.

Required string length: 16 - 128

Path Parameters

toolId
string
required

Identificador de la tool en el catálogo, no su UUID (por ejemplo voice.calls, custom.http o book_appointment_cal). Se obtiene de GET /v1/tools.

Body

application/json

Payload utilizado para crear una conexión entre un agente y una tool.

agentId
string<uuid>
required

Agente propietario de la conexión.

connectionKey
string

Identificador lógico opcional para distinguir múltiples conexiones a la misma tool.

metadata
object

Información contextual para el proveedor (displayName, región, tags, etc.).

descriptionUsage
string

Guía breve (en lenguaje natural) de cuándo debe usarse esta conexión.

Example:

"Usa esta conexión cuando el usuario pregunte por campañas existentes."

usageExample
string

Ejemplo de uso recomendado (puede ser multi-línea).

auth
object

Configuración de autenticación utilizada para la conexión.

Response

Conexión creada o registrada en estado pendiente

status
enum<string>
required

Estado actual de la conexión solicitada.

Available options:
connected,
pending,
error,
revoked
toolId
string
required
workspaceId
string<uuid>
required
agentId
string<uuid>
required
toolAgentConnectionId
string<uuid> | null

Identificador interno de la conexión creada cuando el estado es connected.

providerRef
string | null

Identificador de la entidad creada en el proveedor externo.

authorizationUrl
string<uri> | null

URL a la que debe dirigirse el usuario para completar el flujo cuando se requiere acción adicional.

message
string | null

Mensaje descriptivo sobre el estado de la conexión.

metadata
object

Información opcional suministrada por el adapter (p.ej. scopes otorgados).

descriptionUsage
string | null

Descripción breve de cuándo usar la conexión.

usageExample
string | null

Ejemplo multi-línea de uso recomendado.