API v2 Agentes e Configurações

Use estes endpoints para gerenciar agentes e suas configurações. Todos os endpoints desta página exigem Authorization: Bearer YOUR_API_KEY. Rotas com escopo de agente retornam 404 AGENT_NOT_FOUND quando o agente não existe ou não pertence à conta da chave de API.

Respostas de listagem bem-sucedidas usam um envelope data e pagination. As respostas de detalhes e configurações do agente são objetos simples, sem envelope data. Consulte o catálogo de erros para erros de autenticação e validação compartilhados.

Objeto 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

Caminho: /api/v2/agents

GET /api/v2/agents

Autenticação: Chave de API Bearer.

Sucesso: 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
  }
}

Limites ou cursores inválidos retornam 400 VALIDATION_INVALID_BODY.

Criar um Agente

POST /api/v2/agents

Autenticação: Chave 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"}'

Sucesso: 201 Created, com um objeto agente simples.

Um corpo inválido retorna 400 VALIDATION_INVALID_BODY. Exceder a cota de agentes do workspace retorna 403 QUOTA_CHATBOT_LIMIT.

Obter um Agente

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

GET /api/v2/agents/{agentId}

Autenticação: Chave de API Bearer com acesso a {agentId}.

Sucesso: 200 OK, com um objeto agente simples.

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

Atualizar um Agente

PATCH /api/v2/agents/{agentId}

Autenticação: Chave de API Bearer com acesso a {agentId}.

Pelo menos um campo é obrigatório.

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"}'

Sucesso: 200 OK, com o objeto agente simples atualizado. Corpos inválidos ou vazios retornam 400 VALIDATION_INVALID_BODY.

Excluir um Agente

DELETE /api/v2/agents/{agentId}

Autenticação: Chave de API Bearer com acesso a {agentId}.

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

Sucesso: 200 OK

{
  "deleted": true
}

Esquema de Configurações de IA

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

Atualizações de configurações de IA exigem pelo menos um campo.

Para compatibilidade retroativa, model também aceita os slugs descontinuados 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 e google/gemini-3.6-flash. Agentes existentes ainda podem armazenar (e o GET ainda pode retornar) esses valores, então um ciclo GET→PATCH sempre valida — mas eles não são mais oferecidos no seletor de modelos do painel, e novas integrações devem usar o catálogo atual acima.

Obter Configurações de IA

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

Autenticação: Chave de API Bearer com acesso a {agentId}.

Sucesso: 200 OK. O objeto de configurações de IA é retornado simples; configurações de IA não definidas produzem {}.

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

Atualizar Configurações de IA

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

Autenticação: Chave de API Bearer com acesso 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"}'

Sucesso: 200 OK, com o objeto de configurações de IA atualizado retornado simples. Um modelo não disponível retorna 403 CHAT_MODEL_NOT_ALLOWED; corpos inválidos ou vazios retornam 400 VALIDATION_INVALID_BODY.

Esquema de Configurações de Design

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

Atualizações de configurações de design exigem pelo menos um campo.

Obter Configurações de Design

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

Autenticação: Chave de API Bearer com acesso a {agentId}.

Sucesso: 200 OK. A resposta é um objeto simples contendo os grupos atuais title, language, position, branding, e conversation. Chaves opcionais não definidas são omitidas.

{
  "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
  }
}

Atualizar Configurações de Design

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

Autenticação: Chave de API Bearer com acesso 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"]}'

Sucesso: 200 OK. Diferentemente da resposta GET de design, o PATCH retorna o objeto completo de configurações simples. Ele pode conter estes campos e grupos de nível superior quando definidos: title, language, position, branding, ai, conversation, security, guardrails, notification, training, channels, e identityVerification. Aliases de localidade são retornados e armazenados em formato canônico. Corpos inválidos ou vazios retornam 400 VALIDATION_INVALID_BODY.

Esquema de Configurações de Segurança

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

Atualizações de configurações de segurança exigem pelo menos um campo de nível superior.

Obter Configurações de Segurança

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

Autenticação: Chave de API Bearer com acesso a {agentId}.

Sucesso: 200 OK. O objeto de segurança é retornado simples; configurações de segurança não definidas produzem {}.

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

Atualizar Configurações de Segurança

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

Autenticação: Chave de API Bearer com acesso 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"]}}'

Sucesso: 200 OK, com o objeto de configurações de segurança atualizado retornado simples. Corpos inválidos ou vazios retornam 400 VALIDATION_INVALID_BODY.

Esquema de Configurações de Notificação

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

Pelo menos um campo é obrigatório.

dailyConversations comporta-se como false (desativado) quando omitido; dailyEmails e quotaAlerts comportam-se como true (ativado) quando omitidos. A resposta GET retorna apenas os campos definidos explicitamente.

Obter Configurações de Notificação

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

Autenticação: Chave de API Bearer com acesso a {agentId}.

Sucesso: 200 OK. O objeto de notificação é retornado simples; configurações de notificação não definidas produzem {}.

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

Atualizar Configurações de Notificação

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

Autenticação: Chave de API Bearer com acesso 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}'

Sucesso: 200 OK, com o objeto de configurações de notificação atualizado retornado simples. Corpos inválidos ou vazios retornam 400 VALIDATION_INVALID_BODY.

Esquema de Configurações de Treinamento

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

Obter Configurações de Treinamento

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

Autenticação: Chave de API Bearer com acesso a {agentId}.

Sucesso: 200 OK. O objeto de configurações de treinamento é retornado simples; configurações de treinamento não definidas produzem {}.

{
  "autoRetrainEnabled": true
}

Atualizar Configurações de Treinamento

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

Autenticação: Chave de API Bearer com acesso 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}'

Sucesso: 200 OK, com o objeto de configurações de treinamento atualizado retornado simples. Habilitar o retreinamento automático sem acesso ao plano retorna 403 SUBSCRIPTION_API_RESTRICTED_PLAN; corpos inválidos retornam 400 VALIDATION_INVALID_BODY.

Referência Relacionada

• Visão geral da API v2
• Catálogo de erros da API v2
• Fontes e treinamento