Agentes y configuración de la API v2

Usa estos endpoints para administrar agentes y su configuración. Todos los endpoints de esta página requieren Authorization: Bearer YOUR_API_KEY. Las rutas limitadas a un agente devuelven 404 AGENT_NOT_FOUND cuando el agente no existe o no pertenece a la cuenta de la clave de API.

Las respuestas de listado exitosas usan un envoltorio data y pagination. Las respuestas de detalle del agente y de configuración son objetos simples, sin envoltorio data. Consulta el catálogo de errores para conocer los errores de autenticación y validación compartidos.

Objeto de agente

{
  "id": "955f28f1-8515-40bb-802c-f3f730bf0343",
  "name": "Support Agent",
  "url": "https://example.com",
  "createdAt": 1784332800,
  "settings": {
    "ai": {
      "model": "openai/gpt-5.6-luna",
      "instructionsPreset": "ai-chatbot",
      "instructionsPrompt": "Be helpful, accurate, and conversational."
    },
    "title": "AI Assistant",
    "branding": {
      "appearance": "Light",
      "bubbleColor": "#e9e9e7",
      "primaryColor": "#0a0a0a",
      "primaryColorHeader": false
    },
    "position": "bottom-right",
    "conversation": {
      "defaultPrompts": {
        "enabled": false,
        "prompts": [],
        "keepShowing": false
      },
      "initialMessages": ["Hey! What can I help with?"],
      "messagePlaceholder": "Ask our chatbot a question...",
      "showInitialMessageBubble": true
    },
    "features": {
      "attachments": true
    },
    "notification": {
      "dailyConversations": true,
      "dailyEmails": true,
      "quotaAlerts": true
    }
  }
}

Listar agentes

Ruta: /api/v2/agents

GET /api/v2/agents

Autenticación: Clave de API bearer.

Éxito: 200 OK

curl 'https://your-domain.com/api/v2/agents?limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": "955f28f1-8515-40bb-802c-f3f730bf0343",
      "name": "Support Agent",
      "url": "https://example.com/",
      "createdAt": 1784332800,
      "settings": {}
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Los límites o cursores inválidos devuelven 400 VALIDATION_INVALID_BODY.

Crear un agente

POST /api/v2/agents

Autenticación: Clave de API bearer.

curl -X POST 'https://your-domain.com/api/v2/agents' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Support Agent","url":"https://example.com"}'

Éxito: 201 Created, con un objeto de agente simple.

Un cuerpo inválido devuelve 400 VALIDATION_INVALID_BODY. Superar el límite de agentes del espacio de trabajo devuelve 403 QUOTA_CHATBOT_LIMIT.

Obtener un agente

Ruta: /api/v2/agents/{agentId}

GET /api/v2/agents/{agentId}

Autenticación: Clave de API bearer con acceso a {agentId}.

Éxito: 200 OK, con un objeto de agente simple.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Actualizar un agente

PATCH /api/v2/agents/{agentId}

Autenticación: Clave de API bearer con acceso a {agentId}.

Se requiere al menos un campo.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Customer Support"}'

Éxito: 200 OK, con el objeto de agente simple actualizado. Los cuerpos inválidos o vacíos devuelven 400 VALIDATION_INVALID_BODY.

Eliminar un agente

DELETE /api/v2/agents/{agentId}

Autenticación: Clave de API bearer con acceso a {agentId}.

curl -X DELETE 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Éxito: 200 OK

{
  "deleted": true
}

Esquema de la configuración de IA

Ruta: /api/v2/agents/{agentId}/settings/ai

Las actualizaciones de la configuración de IA requieren al menos un campo.

Por compatibilidad con versiones anteriores, model también acepta los slugs retirados openai/gpt-5.5, openai/gpt-5.4, openai/gpt-5.4-mini, openai/gpt-5.4-nano, anthropic/claude-opus-4.7, anthropic/claude-opus-4-6, anthropic/claude-sonnet-4-6, google/gemini-3-flash-preview y google/gemini-3.6-flash. Los agentes existentes pueden seguir almacenando (y GET puede seguir devolviendo) estos valores, de modo que un ciclo GET→PATCH siempre se valida correctamente, pero ya no se ofrecen en el selector de modelos del panel, y las integraciones nuevas deben usar el catálogo actual anterior.

Obtener la configuración de IA

GET /api/v2/agents/{agentId}/settings/ai

Autenticación: Clave de API bearer con acceso a {agentId}.

Éxito: 200 OK. El objeto de configuración de IA se devuelve simple; si no hay configuración de IA definida, se devuelve {}.

{
  "model": "openai/gpt-5.6-luna",
  "instructionsPreset": "customer-support",
  "instructionsPrompt": "Answer using the support documentation."
}

Actualizar la configuración de IA

PATCH /api/v2/agents/{agentId}/settings/ai

Autenticación: Clave de API bearer con acceso a {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/ai' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model":"openai/gpt-5.6-luna","instructionsPreset":"customer-support"}'

Éxito: 200 OK, con el objeto de configuración de IA actualizado devuelto simple. Un modelo no disponible devuelve 403 CHAT_MODEL_NOT_ALLOWED; los cuerpos inválidos o vacíos devuelven 400 VALIDATION_INVALID_BODY.

Esquema de la configuración de diseño

Ruta: /api/v2/agents/{agentId}/settings/design

Las actualizaciones de la configuración de diseño requieren al menos un campo.

Obtener la configuración de diseño

GET /api/v2/agents/{agentId}/settings/design

Autenticación: Clave de API bearer con acceso a {agentId}.

Éxito: 200 OK. La respuesta es un objeto simple que contiene los grupos actuales title, language, position, branding y conversation. Las claves opcionales no definidas se omiten.

{
  "title": "AI Assistant",
  "language": "en",
  "position": "bottom-right",
  "branding": {
    "appearance": "Light",
    "bubbleColor": "#e9e9e7",
    "primaryColor": "#0a0a0a",
    "primaryColorHeader": false
  },
  "conversation": {
    "defaultPrompts": {
      "enabled": false,
      "prompts": [],
      "keepShowing": false
    },
    "initialMessages": ["Hey! What can I help with?"],
    "messagePlaceholder": "Ask our chatbot a question...",
    "showInitialMessageBubble": true
  }
}

Actualizar la configuración de diseño

PATCH /api/v2/agents/{agentId}/settings/design

Autenticación: Clave de API bearer con acceso a {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/design' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Support","language":"en-US","appearance":"Dark","prompts":["Track my order"]}'

Éxito: 200 OK. A diferencia de la respuesta GET de diseño, PATCH devuelve el objeto de configuración completo, simple. Puede contener estos campos y grupos de nivel superior cuando están definidos: title, language, position, branding, ai, conversation, security, guardrails, notification, training, channels e identityVerification. Los alias de configuración regional se devuelven y se almacenan en forma canónica. Los cuerpos inválidos o vacíos devuelven 400 VALIDATION_INVALID_BODY.

Esquema de la configuración de seguridad

Ruta: /api/v2/agents/{agentId}/settings/security

Las actualizaciones de la configuración de seguridad requieren al menos un campo de nivel superior.

Obtener la configuración de seguridad

GET /api/v2/agents/{agentId}/settings/security

Autenticación: Clave de API bearer con acceso a {agentId}.

Éxito: 200 OK. El objeto de seguridad se devuelve simple; si no hay configuración de seguridad definida, se devuelve {}.

{
  "isPrivate": false,
  "rateLimit": {
    "maxMessages": 20,
    "windowSeconds": 240,
    "limitMessage": "Too many messages in a row"
  },
  "allowedDomains": {
    "enabled": true,
    "domains": ["https://example.com"]
  }
}

Actualizar la configuración de seguridad

PATCH /api/v2/agents/{agentId}/settings/security

Autenticación: Clave de API bearer con acceso a {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/security' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"allowedDomains":{"enabled":true,"domains":["https://example.com"]}}'

Éxito: 200 OK, con el objeto de configuración de seguridad actualizado devuelto simple. Los cuerpos inválidos o vacíos devuelven 400 VALIDATION_INVALID_BODY.

Esquema de la configuración de notificaciones

Ruta: /api/v2/agents/{agentId}/settings/notifications

Se requiere al menos un campo.

dailyConversations se comporta como false (desactivado) cuando se omite; dailyEmails y quotaAlerts se comportan como true (activado) cuando se omiten. La respuesta GET solo devuelve los campos establecidos explícitamente.

Obtener la configuración de notificaciones

GET /api/v2/agents/{agentId}/settings/notifications

Autenticación: Clave de API bearer con acceso a {agentId}.

Éxito: 200 OK. El objeto de notificaciones se devuelve simple; si no hay configuración de notificaciones definida, se devuelve {}.

{
  "dailyConversations": true,
  "dailyEmails": true,
  "quotaAlerts": true
}

Actualizar la configuración de notificaciones

PATCH /api/v2/agents/{agentId}/settings/notifications

Autenticación: Clave de API bearer con acceso a {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/notifications' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"dailyConversations":false}'

Éxito: 200 OK, con el objeto de configuración de notificaciones actualizado devuelto simple. Los cuerpos inválidos o vacíos devuelven 400 VALIDATION_INVALID_BODY.

Esquema de la configuración de entrenamiento

Ruta: /api/v2/agents/{agentId}/settings/training

Obtener la configuración de entrenamiento

GET /api/v2/agents/{agentId}/settings/training

Autenticación: Clave de API bearer con acceso a {agentId}.

Éxito: 200 OK. El objeto de configuración de entrenamiento se devuelve simple; si no hay configuración de entrenamiento definida, se devuelve {}.

{
  "autoRetrainEnabled": true
}

Actualizar la configuración de entrenamiento

PATCH /api/v2/agents/{agentId}/settings/training

Autenticación: Clave de API bearer con acceso a {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/training' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"autoRetrainEnabled":true}'

Éxito: 200 OK, con el objeto de configuración de entrenamiento actualizado devuelto simple. Habilitar el reentrenamiento automático sin acceso de plan devuelve 403 SUBSCRIPTION_API_RESTRICTED_PLAN; los cuerpos inválidos devuelven 400 VALIDATION_INVALID_BODY.

Referencia relacionada

• Descripción general de la API v2
• Catálogo de errores de la API v2
• Fuentes y entrenamiento