API de Agentes de IA #

Um Agente de IA é o cérebro por trás do seu bot: suas instruções, personalidade, idioma, conhecimento e ferramentas. Você cria um Agente uma vez e, em seguida, direciona o tráfego para ele. Este guia cobre tudo o que você pode fazer com um Agente via API — criá-lo, configurá-lo, fornecer conhecimento e ferramentas, revisar seus rascunhos e rotear conversas para ele.

• URL Base — https://api.youraiconnector.com/v1
• Autenticação — sua chave de API (veja Autenticação)
• Erros e paginação — veja Erros e Paginação

Todos os exemplos abaixo mostram a forma de consulta ?apiKey= em cURL e o cabeçalho X-API-Key em JavaScript e Python — ambos funcionam em todos os endpoints.

Se você é novo no conceito de Agentes, leia Agentes de IA primeiro.

Como um Agente é estruturado #

Quatro coisas são gerenciadas separadamente, e é útil saber o que é cada uma antes de começar:

Um novo Agente não responde a ninguém até que você roteie para ele. Criar um Agente não o coloca em um canal. Esse é o passo que a maioria das integrações perde — veja Roteando conversas para um Agente no final desta página.

O objeto Agente #

Um documento completo de Agente é grande — várias centenas de kilobytes, principalmente sua lista de FAQs, suas fontes de conhecimento e qualquer conteúdo de página lido do seu site. Por causa disso, a listagem retorna uma linha de resumo curta por Agente quando você a solicita:

{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

O documento completo adiciona todo o resto: instructions, rules, personality, availability, follow_up_config, as listas vinculadas de FAQ e fontes de conhecimento, os blocos de texto gerados e qualquer estado de execução (tag_generation, optimize_run).

Algumas respostas também contêm substrate_campaign_id. É um registro interno mantido em contas mais antigas; você nunca precisa agir sobre ele, e em contas mais novas ele é null ou ausente.

Listar Agentes #

GET /agents — todos os Agentes na conta, do mais novo para o mais antigo.

Este endpoint não é paginado. Por padrão, cada Agente retorna com sua configuração completa, o que é pesado: um único Agente pode chegar a 580 KB e uma conta com 64 Agentes a mais de 3 MB. Passe view=summary para obter uma linha curta por Agente, e então leia aquele que você deseja com Obter um Agente.

Parâmetros de consulta

cURL

curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]

Resposta (200)

{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}

Criar um Agente #

POST /agents — apenas name é realmente necessário; envie qualquer configuração que você já conheça junto com ele. Um novo Agente está ativo por padrão.

Campos da requisição (todos opcionais, exceto name)

Construindo um Agente a partir do seu site. Inclua scrape_urls e a plataforma lerá essas páginas e escreverá as instruções para você. A resposta informa se essa geração foi iniciada, para que você saiba se deve verificar o progresso do Agente.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])

Resposta (201)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}

agent_generation_queued é true quando a plataforma começou a escrever as instruções a partir das páginas que você forneceu.

Um 400 significa que o corpo não era um objeto JSON, um campo foi rejeitado ou o Agente excede o tamanho de configuração permitido pelo seu plano. Um 403 significa que a conta não tem permissão para usar uma das configurações que você enviou — por exemplo, um nível de IA que o provedor da conta não concedeu.

Obter um Agente #

GET /agents/{agentId}

Passe fields com uma lista separada por vírgulas para obter de volta apenas o que você precisa, por exemplo fields=name,active,goal. O id é sempre incluído, e nomes que não existem no Agente são ignorados em vez de rejeitados. Omita-o para obter o documento completo.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]

Um Agente que não existe na sua conta retorna 404.

Atualizar um Agente #

PUT /agents/{agentId} — envie apenas os campos que você deseja alterar; todo o resto permanece inalterado.

Configurações aninhadas podem ser endereçadas folha por folha com uma chave pontuada, portanto "availability.monday" altera apenas a segunda-feira e deixa o restante da semana inalterado.

Notas

• Para alterar para qual tipo de evento agendável o Agente faz reservas, envie event_id (o id do evento, ou null para limpá-lo). Envie event_ids com uma matriz para vincular vários de uma vez — o primeiro se torna o principal e [] desvincula tudo. event_id e event_ids são mutuamente exclusivos, e o campo event em si não pode ser gravado diretamente.
• enable_bookings deve ser um booleano real, e booking_provider deve ser um entre default, zenchef, formitable.
• Campos de propriedade e identidade são ignorados, assim como o estado de execução interno (progresso de geração e otimização).
• O roteamento não é definido aqui. Use PUT /entry-points/channel-defaults para tornar o Agente o respondente de um canal, POST /agents/{agentId}/entry-points para regras de palavras-chave e comentários, e PATCH /agents/{agentId}/active para pausá-lo ou retomá-lo.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});

Python

requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)

Resposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Um corpo vazio retorna 400 com "No fields to update".

Atualizar configurações do bot #

PUT /agents/{agentId}/bot-config — a maneira restrita de alterar apenas as configurações de conversação.

Um Agente não possui uma seção de bot separada: suas configurações ficam diretamente no Agente, portanto, os nomes dos campos aqui são os mesmos que você enviaria para PUT /agents/{agentId}. Este endpoint existe como a maneira segura e focada de alterar alguns deles. Pelo menos um campo é obrigatório.

Os nomes dos campos devem ser nomes simples aqui — letras, números, sublinhados e hifens. Caminhos pontuados não são aceitos neste endpoint (ao contrário de PUT /agents/{agentId}), portanto bot.goal é rejeitado com um 400.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'

Textos longos contam contra o tamanho de configuração permitido pelo seu plano, portanto, um conjunto de instruções muito grande pode ser recusado com um 400.

Definir horário de funcionamento #

PUT /agents/{agentId}/active-hours — as horas durante as quais o Agente responde automaticamente. Fora dessas janelas, ele permanece inativo.

Envie um objeto availability com chaves por dia da semana (monday a sunday). Cada dia aceita uma única janela de tempo ou uma lista de janelas, no formato HH:MM de 24 horas. Os dias que você omitir mantêm o que já tinham, e qualquer chave que não seja um dia da semana é rejeitada — assim, um erro de digitação não pode passar despercebido sem fazer nada.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

Resposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Uma chave de dia da semana inválida retorna 400: "Invalid availability keys: funday. Allowed keys: monday through sunday."

Pausar ou retomar um Agente #

PATCH /agents/{agentId}/active — liga ou desliga o Agente. Um Agente pausado mantém toda a sua configuração, mas para de responder imediatamente; a retomada entra em vigor instantaneamente.

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});

Resposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }

active deve ser um booleano real — qualquer outro valor retorna 400 com "active (boolean) is required".

Duplicar um Agente #

POST /agents/{agentId}/duplicate — cria uma cópia com sua configuração preservada. A cópia não envia nada até que você aponte um canal ou um Ponto de Entrada para ela.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"

Resposta (201)

{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }

Uma duplicata conta para o limite de Agentes do seu plano exatamente como criar um do zero, portanto, é recusada com 403 quando a conta atinge o limite.

Excluir um Agente #

DELETE /agents/{agentId}

A exclusão é recusada enquanto o Agente ainda estiver anexado a algo que pararia de funcionar sem ele — uma transmissão, um Ponto de Entrada ou (em contas mais antigas) uma campanha. A resposta lista o que o está mantendo para que você possa desanexá-los primeiro e tentar novamente.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"

Resposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Bloqueado (409)

{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}

Rascunhos: revise as alterações antes que entrem em vigor #

As edições feitas no editor e qualquer reescrita produzida pelo Otimizar com IA são mantidas como um rascunho não publicado até que você as publique. O Agente ativo continua respondendo com sua configuração atual até lá.

Publicar o rascunho #

POST /agents/{agentId}/publish-draft — move o rascunho para a configuração ativa e limpa o rascunho na mesma etapa.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"

Resposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }

published_keys lista as configurações que foram movidas do rascunho para o Agente ativo, para que você possa mostrar o que mudou.

Verifique se um rascunho existe antes de chamar isso. Publicar um Agente que não possui rascunho não é uma chamada suportada e atualmente retorna um 500 com uma mensagem genérica, não específica. Para descartar um rascunho, use o descarte abaixo.

Descartar o rascunho #

POST /agents/{agentId}/discard-draft — descarta o rascunho e deixa a configuração ativa exatamente como está. É seguro chamar quando não há rascunho; nada acontece.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"

Otimizar um Agente com IA #

POST /agents/{agentId}/optimize — reescreve a configuração do Agente a partir do seu feedback (“ele continua oferecendo descontos”, “as respostas são muito longas”) e salva a reescrita como um rascunho em vez de colocá-la em produção.

Envie user_feedback (uma instrução simples) ou, ao reagir a uma resposta ruim específica, thumbs_down_feedback junto com a thumbs_down_message ofensiva. Pelo menos um dos dois deve conter texto.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'

Resposta (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

O trabalho é executado em segundo plano e a chamada retorna imediatamente. Leia o Agente com GET /agents/{agentId} e observe optimize_run.status; assim que ele voltar para Draft, a reescrita estará aguardando como rascunho do Agente. Revise-a e, em seguida, publique-a ou descarte-a.

Apenas uma execução por vez por Agente — uma segunda chamada enquanto uma está em andamento retorna 409. Isso utiliza créditos de IA.

Regras de marcação #

Uma regra de marcação é uma tag mais uma descrição de quando ela se aplica. Durante uma conversa, o Agente lê essa descrição e marca o contato quando ela se encaixa, que é como as automações baseadas em tags são acionadas.

O objeto de regra

Adicionar uma regra de marcação #

POST /agents/{agentId}/tags

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'

Resposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }

Substituir uma regra de marcação #

PUT /agents/{agentId}/tags/{tagId} — a regra é encontrada pelo ID da tag no caminho e substituída integralmente, não mesclada, portanto, envie a regra completa em vez de apenas a parte que você está alterando. A tag para a qual ela aponta é preservada mesmo se você omitir tag_id, portanto, uma edição não pode desvincular a regra de sua tag.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'

Remover uma regra de marcação #

DELETE /agents/{agentId}/tags/{tagId} — o Agente para de aplicar essa tag. A tag em si, e quaisquer contatos que já a possuam, permanecem inalterados.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"

Ambos os endpoints retornam 404 quando o Agente não existe ou quando ele não possui nenhuma regra para essa tag.

Gerar um conjunto de tags com IA #

POST /agents/{agentId}/tags/generate — projeta um conjunto completo de regras (os nomes das tags e a redação “aplicar quando…” por trás de cada uma) lendo as próprias instruções e o objetivo do Agente.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'

Resposta (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }

O trabalho é executado em segundo plano. Leia o Agente e observe tag_generation.status; as regras em si são inseridas em tags do Agente. Apenas uma execução por vez por Agente (409 caso contrário), e isso consome créditos de IA.

Fontes de conhecimento #

Fontes de conhecimento são as páginas e documentos que a plataforma leu para você. Anexar uma a um Agente permite que ele responda com base nesse conteúdo.

De onde vêm os IDs de origem. Adicione conteúdo com os endpoints da base de conhecimento — POST /kb-sources/url para uma página, POST /kb-sources/file para um documento, POST /kb-sources/bulk-import para um site inteiro. Eles retornam um source_id que você consulta com GET /kb-sources/{sourceId} até que esteja pronto. POST /kb-sources/url também aceita autoLinkToAgentId, que anexa a fonte a um Agente assim que a importação termina, para que você possa pular a chamada de anexo abaixo.

Anexar fontes de conhecimento #

POST /agents/{agentId}/kb-sources — envie kb_source_ids com uma lista para anexar um conjunto inteiro em uma única chamada (o que você deseja após rastrear um site), ou kb_source_id para uma única fonte. Envie uma ou outra. Anexar algo que já está anexado não altera nada.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'

Resposta (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}

Desanexar fontes de conhecimento #

DELETE /agents/{agentId}/kb-sources/{kbSourceId} para um, ou POST /agents/{agentId}/kb-sources/bulk-remove com kb_source_ids para vários. A remoção em massa é um POST porque a lista de IDs é enviada no corpo da requisição.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'

As fontes em si não são excluídas e permanecem disponíveis para seus outros Agentes. Desanexar algo que não está anexado não altera nada.

Perguntas Frequentes (FAQs) #

As FAQs são gerenciadas em seus próprios endpoints e vinculadas a um Agente a partir deles: POST /faqs/{faqId}/link com { "agent_id": "ag7HkQ2ZpLxR3mNb" }, e POST /faqs/{faqId}/unlink para removê-las novamente. Uma FAQ pode ser compartilhada por qualquer número de Agentes. Veja a API de FAQs.

Uma FAQ só é usada pelos Agentes aos quais está vinculada — criá-la não é suficiente por si só.

Ferramentas #

Funções personalizadas #

POST /agents/{agentId}/custom-functions permite que o Agente chame uma de suas funções personalizadas durante as conversas. Apenas funções pertencentes à mesma conta podem ser anexadas, e anexar uma que já esteja anexada não altera nada.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'

DELETE /agents/{agentId}/custom-functions/{customFunctionId} a desanexa. A função em si não é excluída e permanece disponível para seus outros Agentes.

Gerencie as funções em /custom-functions — veja Funções Personalizadas para saber o que são.

Servidores MCP #

Um servidor MCP é um pacote pronto de ferramentas que seu Agente pode descobrir e chamar por conta própria — veja Conectar Servidores MCP ao Seu Bot. Os servidores são registrados uma vez na conta e, em seguida, anexados aos Agentes que devem usá-los.

Os servidores MCP exigem o recurso de funções personalizadas em seu plano. Sem ele, os endpoints de nível de conta /mcp-servers retornam 403. Anexar um servidor já registrado a um Agente não é restrito.

Registrar um servidor #

POST /mcp-servers

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'

Resposta (201)

{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}

Ao salvar, a plataforma conecta-se ao servidor e faz cache da lista de ferramentas que ele oferece. Um servidor que não pode ser alcançado ainda é salvo, com o motivo em last_error e uma lista de ferramentas vazia — para que você possa registrar primeiro e corrigir a conectividade depois.

Um auth_type de oauth2 salva o registro com oauth_connected: false e sem ferramentas: ainda não há token. Autorizar um servidor OAuth requer um login via navegador e é feito pelo painel, não pela API.

Listar, atualizar e excluir servidores #

• GET /mcp-servers — todos os servidores registrados, do mais recente para o mais antigo, em servers.
• PUT /mcp-servers/{serverId} — envie apenas o que deseja alterar. Alterar a URL ou os campos de autenticação testa novamente a conexão e atualiza a lista de ferramentas em cache.
• DELETE /mcp-servers/{serverId} — remove o registro e desvincula-o de todos os Agentes e campanhas que o tinham ativado.

curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"

Segredos nunca retornam. As respostas trazem auth_header_value_set (um sinalizador true/false informando que um valor está armazenado) em vez da credencial, e tokens OAuth e segredos de cliente permanecem no lado do servidor. Todo o resto é retornado: name, url, enabled, auth_type, auth_header_name, tools, enabled_tools, tool_policies, oauth_connected, tools_cached_at, last_connected_at, last_error, created_at, updated_at.

Testar uma conexão #

POST /mcp-servers/test-connection — conecta-se a um servidor e lista suas ferramentas. Duas maneiras de chamá-lo:

• com server_id — testa a configuração salva e atualiza sua lista de ferramentas em cache;
• com um url em linha (mais auth_header_name / auth_header_value) — um teste pré-salvamento que não armazena nada.

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'

Resposta (200)

{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}

Uma falha de conexão não é um erro HTTP — você recebe um 200 com success: false e um error descrevendo o que deu errado, para que você possa exibi-lo ao lado do campo que o operador está editando.

Anexar um servidor a um Agente #

Registrar um servidor não dá a nenhum Agente acesso a ele. Anexe-o:

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'

Resposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }

DELETE /agents/{agentId}/mcp-servers/{mcpServerId} desanexa-o novamente. O servidor em si não é excluído e permanece disponível para seus outros Agentes. Anexar ou desanexar algo que já está nesse estado não altera nada.

Biblioteca de mídia #

A biblioteca de mídia armazena os arquivos que um Agente pode enviar durante uma conversa — um menu, uma lista de preços, uma foto de produto. Um Agente pode conter no máximo 50 itens.

Listar mídia #

GET /agents/{agentId}/media-library

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"

Resposta (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}

Os itens armazenados no Agente aparecem primeiro, seguidos por quaisquer itens mais antigos ainda armazenados na campanha a partir da qual o Agente foi criado; media_home (agent ou campaign) indica qual é qual. Dentro de cada grupo, o mais recente aparece primeiro.

media_url expira após 7 dias. É o link de download criado quando o arquivo foi carregado — trate um link antigo como obsoleto em vez de quebrado, e leia a lista novamente para obter um link atualizado.

Carregar mídia #

POST /agents/{agentId}/media-library — o arquivo é carregado inline como base64, até 10 MB. A chamada retorna assim que o arquivo é armazenado, portanto, permita um pouco mais de tempo do que para uma solicitação normal. Observe que este corpo usa nomes de campo em camelCase.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'

Duas coisas acontecem automaticamente: um GIF animado é convertido em vídeo para que seja reproduzido em todos os canais, e a plataforma escreve um breve resumo do que realmente está no arquivo para que o Agente saiba quando ele se encaixa.

Um 400 cobre campos ausentes, um tipo de arquivo não suportado, um arquivo vazio ou muito grande, e atingir o limite de 50 itens. Um 403 significa que a biblioteca de mídia está desativada para a conta.

Atualizar um item de mídia #

PATCH /agents/{agentId}/media-library/{itemId} — apenas metadados. O arquivo em si não pode ser substituído; carregue um novo item e exclua o antigo. Este corpo usa snake_case: title, description, send_message, max_sends_per_conversation (um número inteiro não negativo, ou null para limpar o limite).

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'

Resposta (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}

Excluir um item de mídia #

DELETE /agents/{agentId}/media-library/{itemId} — remove o item e seu arquivo armazenado. Excluir um item que já se foi é bem-sucedido e retorna deleted: false, portanto, a chamada é segura para tentar novamente.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"

Gerar mensagens de acompanhamento #

POST /agents/{agentId}/template-generation — escreve as mensagens de acompanhamento do Agente para você (os lembretes que ele envia quando uma conversa fica silenciosa), com base na finalidade do Agente.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

Existem duas maneiras de isso retornar, e o campo target informa qual:

• target: "agent" com um 200 — as mensagens foram gravadas durante a chamada e o resultado está em data. Leia-as a partir do follow_up_config do Agente. Este é o caso comum.
• target: "campaign" com um 202 — o trabalho foi colocado na fila da campanha nomeada em campaign_id. Monitore o template_generation_status dessa campanha até que ela termine.

cold_only requer uma campanha de saída e é recusado com 409 (reason: "cold_only_requires_campaign") em um Agente que não possui nenhuma. Um 403 significa que os acompanhamentos automáticos não estão ativados para a conta. Isso utiliza créditos de IA, e um 400 com "Insufficient credits." significa que a conta não possui créditos.

Encaminhando conversas para um Agente #

Um Agente só responde às conversas que um Ponto de Entrada envia para ele. Até que um canal tenha um, a primeira mensagem de alguém com quem você nunca falou ainda é armazenada, mas nada a captura e nenhum assistente responde.

Listar os Pontos de Entrada de um Agente #

GET /agents/{agentId}/entry-points — as regras de roteamento que enviam conversas para este Agente, da mais recente para a mais antiga. Tanto as regras atuais quanto as inativas retornam; uma regra inativa possui enabled: false.

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

Para os padrões de canal de toda a conta, incluindo um canal deliberadamente definido como sem ninguém, leia GET /entry-points/channel-defaults em vez disso.

Criar um Ponto de Entrada #

POST /agents/{agentId}/entry-points — o Agente no caminho sempre vence, portanto, uma regra nunca pode ser criada para um Agente diferente daquele na URL.

channels é obrigatório e indica quais canais a regra cobre — por exemplo whatsapp, whatsapp_web, instagram, messenger, telegram, sms, email, chat_widget ou custom_channel. Novas regras são habilitadas, a menos que você especifique o contrário.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

Resposta (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Qual regra vence quando várias podem: uma conversa em andamento ou uma atribuição manual mantém o Agente que já possui; caso contrário, as regras de palavra-chave superam as regras de comentário, que superam as regras de seguidor, e um padrão de canal é o último recurso. Se essas regras decidem algo em uma conta é relatado por GET /entry-points/routing-status.

Esta é a versão resumida. O guia da Entry Points API cobre todas as regras de ladder, comentários e seguidores, um Agente por número de WhatsApp, e como alterar ou excluir uma regra. Consulte Entry Points para o conceito, e a Channels API para conectar o canal em si.

Erros da API de Agentes de IA #

Os endpoints de Agente retornam o envelope de erro padrão:

{
  "success": false,
  "error": "Agent not found"
}

Os códigos compartilhados que todo endpoint pode retornar — 401, 403 (seu plano não inclui acesso à API), 429 (limite de taxa) e 500 — estão listados com orientações de nova tentativa em Erros e Paginação.

Uma nota sobre o explorador. Os endpoints /agents estão na especificação OpenAPI publicada, então você pode navegar pelos seus campos exatos e executar solicitações ao vivo na Referência da API. Os endpoints /mcp-servers em nível de conta também estão na especificação, então você pode explorá-los lá também.

Relacionado #

• Agentes de IA — o que é um Agente, em linguagem simples.
• Pontos de Entrada — como as conversas são direcionadas para um Agente.
• API de FAQs — crie e vincule o conhecimento a partir do qual seu Agente responde.
• API de Canais — conecte os canais nos quais um Agente responde.
• Conecte Servidores MCP ao Seu Bot · Funções Personalizadas
• Referência da API — o explorador de endpoints interativo completo.