API da Base de Conhecimento #

Sua base de conhecimento é de onde a IA lê as informações. Ela possui duas partes, e esta página cobre ambas:

• Fontes de conhecimento (/kb-sources) — as páginas da web e documentos enviados que você fornece à plataforma. Cada um é lido, dividido em seções e transformado em FAQs que sua IA pode usar para responder.
• Grupos de conhecimento (/kb-groups) — conjuntos nomeados de FAQs que você pode aplicar a um Agente ou a uma campanha em uma única chamada, para que um corpo de conhecimento que você já organizou possa ser reutilizado no próximo Agente que você criar.

As FAQs que uma fonte produz vão para a mesma biblioteca que aquelas que você escreve manualmente, portanto, assim que uma importação termina, você pode lê-las, editá-las e vinculá-las com a API de FAQs.

Todos os endpoints abaixo são relativos à URL base https://api.youraiconnector.com/v1. Cada solicitação deve ser autenticada — consulte Acesso à API e Autenticação. O acesso à API é um recurso pago; sem ele, as solicitações são rejeitadas com um 403.

A importação consome créditos. Ler uma página ou documento e escrever FAQs a partir dele consome créditos, aproximadamente em proporção à quantidade de conteúdo existente. Use Estimar uma importação antes de se comprometer com um rastreamento grande.

Como funciona uma importação #

A importação é um trabalho em segundo plano, não algo que termina enquanto você espera. Cada endpoint de importação responde imediatamente com um source_id, e você consulta essa fonte até que ela esteja concluída:

1. Inicie a importação — POST /kb-sources/url (uma página), POST /kb-sources/file (um documento enviado) ou POST /kb-sources/bulk-import (até 100 páginas). Você recebe um ID de fonte e um status: "queued".
2. Consulte (Poll) — GET /kb-sources/{sourceId} até que o status não seja mais queued ou processing.
3. Leia as FAQs — quando o status for ready, as entradas produzidas estarão em sua biblioteca de FAQs: GET /faqs.

Cada fonte relata um destes status:

Vincule conforme você importa. Passe autoLinkToAgentId em qualquer endpoint de importação e a fonte — além de cada FAQ que ela produz — será adicionada ao conhecimento daquele Agente na mesma chamada, sem necessidade de uma etapa de vinculação posterior. autoLinkToCampaignId faz o mesmo para uma campanha clássica. A vinculação é feita da melhor forma possível: um ID que não existe ou que pertence a outra conta é ignorado silenciosamente e a importação ainda é executada, portanto, confirme a vinculação lendo o Agente novamente.

Importar uma página da web #

POST /kb-sources/url

Adiciona uma página da web à sua base de conhecimento.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/url?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/url", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/pricing",
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { source_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://example.com/pricing",
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
source_id = res.json().get("source_id")

Resposta — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued",
  "batch_id": "batch_9f2a"
}

Faça polling em source_id com Verificar uma fonte até que o status seja ready ou failed.

Se a mesma página já estiver em sua base de conhecimento, nada de novo é colocado na fila e você recebe um 200 — e se você solicitou um link automático, a fonte existente é vinculada para você de qualquer maneira:

{
  "success": true,
  "status": "exists",
  "skipped_duplicate": 1
}

Um url ausente, ou um que não seja um endereço http/https válido, retorna 400.

Importar um documento enviado #

POST /kb-sources/file

Adiciona um documento que já está no armazenamento de arquivos da sua conta como uma fonte de conhecimento. Tipos suportados: PDF, DOCX, TXT, MD, CSV e XLSX.

Este endpoint não transporta o arquivo. Não há upload multipart, não há corpo base64 e não há download a partir de uma URL: você envia o local de armazenamento de um arquivo que já existe, e ele deve estar na sua própria pasta de uploads (storage_path deve começar com users/{your user id}/uploads/) ou a solicitação será recusada com 403. O painel coloca os arquivos lá quando você os arrasta para dentro. Se você não tiver como colocar um arquivo lá, importe uma página da web com Importar uma página da web em vez disso.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/file?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storage_path": "users/abc123uid/uploads/handbook.pdf",
    "filename": "handbook.pdf",
    "mime_type": "application/pdf",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

Resposta — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}

Verificar uma fonte #

GET /kb-sources/{sourceId}

O polling que segue cada importação e atualização. Repita-o até que o status seja ready ou failed.

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const source = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
source = res.json()

Resposta

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "ready",
  "faq_count": 24,
  "section_count": 31,
  "error_message": null
}

Excluir uma fonte #

DELETE /kb-sources/{sourceId}

Remove uma fonte de conhecimento. Por padrão, as FAQs produzidas por ela são mantidas — adicione delete_faqs=true para removê-las também.

Parâmetros de consulta

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?delete_faqs=true&apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "faqs_deleted": 24
}

faqs_deleted é 0 a menos que você tenha solicitado delete_faqs=true.

Importar várias páginas de uma vez #

POST /kb-sources/bulk-import

Adiciona até 100 páginas da web em uma única chamada. Sua conta pode ter até 5.000 páginas aguardando para serem importadas de uma vez (o limite de importação da sua conta), contando as páginas já na fila ou sendo lidas. Uma chamada que ultrapasse esse limite é recusada com 400 e error_code: kb_import_page_limit, e nada dessa chamada é colocado na fila. Importações acima de 5.000 páginas precisam de aprovação, portanto, entre em contato com o suporte para aumentar o limite. É o acompanhamento usual para Descobrir páginas em um site ou Encontrar novas páginas em um site. Páginas que já estão na sua base de conhecimento são ignoradas em vez de duplicadas (e ainda são vinculadas ao Agente quando você solicitou isso).

Uma importação que sua conta não pode pagar é recusada antes que qualquer coisa seja colocada na fila, com 402 e error_code: kb_import_insufficient_credits (a resposta também carrega required_credits, available_credits e waiting_pages). Cada página conta como pelo menos um chunk para esta verificação, e as páginas que você já tem aguardando para serem importadas também contam, porque elas só são cobradas quando são processadas. Contas com recarga automática configurada não são recusadas por saldo. Contas que usam sua própria chave de IA também não são recusadas, a menos que operem no nível Max, que é cobrado em créditos. Para uma subconta, available_credits é null.

Importar mais de 100 páginas significa várias chamadas. Envie o tamanho da seleção completa como plannedTotal na primeira chamada. O limite de páginas e a verificação de crédito cobrem então toda a seleção nessa chamada, de modo que uma importação que não pode ser concluída é recusada antes que qualquer página seja colocada na fila, em vez de parar no meio do caminho. Quando a primeira chamada é aceita, sua resposta inclui um import_session: envie-o de volta como importSession em todas as chamadas subsequentes da mesma seleção. Essas chamadas então ignoram a verificação de crédito antecipada para até o número aprovado de páginas, por uma hora. O limite de páginas ainda se aplica, e cada página ainda é cobrada quando é processada.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing", "https://example.com/faq"],
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/bulk-import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: ["https://example.com/pricing", "https://example.com/faq"],
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { queued_source_ids } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/bulk-import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "urls": ["https://example.com/pricing", "https://example.com/faq"],
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
queued_source_ids = res.json()["queued_source_ids"]

Resposta — 202 Accepted

{
  "success": true,
  "batch_id": "batch_9f2a",
  "queued": 2,
  "skipped_duplicate": 0,
  "queued_source_ids": ["kb_src_abc123", "kb_src_def456"]
}

Verifique cada ID em queued_source_ids com Verificar uma fonte. Enviar um array urls vazio, uma entrada que não seja string ou mais de 100 entradas retorna 400.

Excluir várias fontes de uma vez #

POST /kb-sources/bulk-delete

Remove até 2.000 fontes de conhecimento em uma única chamada. A remoção é executada em segundo plano e você recebe um e-mail quando ela for concluída.

A exclusão em massa sempre remove as FAQs também. Diferente de Excluir uma fonte, que as mantém a menos que você solicite o contrário, este endpoint exclui cada fonte juntamente com as FAQs que ela produziu. Não há opção para mantê-las.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-delete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceIds": ["kb_src_abc123", "kb_src_def456"],
    "domainLabel": "example.com"
  }'

Resposta — 202 Accepted

{
  "success": true,
  "batch_id": "del_batch_31a",
  "queued": 2
}

Descobrir páginas em um site #

POST /kb-sources/discover-pages

Explora um site a partir de um endereço inicial e lista as páginas encontradas no mesmo domínio, cada uma com uma opinião sobre se vale a pena importá-la. Nada é importado e nada é selecionado para você — este é o passo “o que há neste site” que você executa antes de decidir o que enviar para Importar várias páginas de uma vez.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/discover-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "maxPages": 100 }'

Resposta

{
  "success": true,
  "source_type": "sitemap",
  "pages": [
    {
      "url": "https://example.com/pricing",
      "title": "Pricing",
      "depth": 1,
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ]
}

A exploração é feita da melhor forma possível. Se o site não puder ser lido, a resposta ainda será 200, com success: false, uma lista pages vazia e uma mensagem error. Verifique success antes de ler pages.

Um url ausente retorna 400.

Estimar quanto custará uma importação #

POST /kb-sources/estimate-cost

Calcula quantos créditos uma importação proposta consumiria, antes de você se comprometer com ela. As páginas são buscadas e os documentos são lidos para medir seu tamanho, mas nada é importado e a estimativa em si não gasta créditos.

Campos da requisição

Envie urls, files ou ambos.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/estimate-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://example.com/pricing"] }'

Resposta

{
  "success": true,
  "estimates": [
    { "ref": "https://example.com/pricing", "chunks": 7, "credits": 7 }
  ],
  "total_chunks": 7,
  "total_credits": 7,
  "affordable": true,
  "required_credits": 7,
  "available_credits": 120,
  "checked_chunks": 7,
  "waiting_pages": 0,
  "max_affordable_chunks": 120
}

Cada linha reflete a URL ou o caminho de armazenamento em ref para que você possa correspondê-lo à sua entrada. Uma página ou arquivo que não pôde ser lido ainda recebe uma linha, contada como um chunk, com um error nela.

affordable diz se sua conta pode pagar por esta estimativa, contando as páginas que você já tem aguardando para serem importadas (waiting_pages). max_affordable_chunks é o máximo de chunks adicionais que ela pode pagar, para que você possa comparar um total acumulado ao estimar uma grande seleção em várias chamadas. É null quando seu saldo não o limita (recarga automática configurada, ou sua própria chave de IA abaixo do nível Max), e sempre null para uma subconta, que recebe apenas affordable (envie prior_chunks para que cubra toda a seleção) e um null available_credits.

Parar uma importação #

POST /kb-sources/cancel-import

Para páginas que ainda estão aguardando na fila de importação — o botão “parar importação” para um rastreamento que acabou sendo maior do que você esperava. Cancelar uma página em espera não custa nada, pois ela ainda não foi lida.

Páginas que já estão sendo processadas não são interrompidas: o trabalho delas está em andamento e é cobrado de qualquer forma, então elas são concluídas. A resposta informa quantas foram.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/cancel-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "host": "docs.example.com" }'

Resposta

{
  "success": true,
  "cancelled": 412,
  "in_flight": 3
}

Retomar uma importação pausada #

POST /kb-sources/resume-import

Reinicia uma importação que foi pausada porque sua própria chave de IA parou de funcionar.

Chamar isso é o seu consentimento para concluir a importação com qualquer chave que esteja ativa no momento — o que pode significar gastar créditos da plataforma se sua própria chave ainda estiver inativa.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/resume-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta

{
  "success": true,
  "resumed": 58
}

Encontrar novas páginas em um site #

POST /kb-sources/refresh-domain

Explora um site do qual você já importou e relata apenas as páginas que ainda não estão na sua base de conhecimento, cada uma com a mesma recomendação da descoberta de páginas. Nada é importado e nada é alterado.

Os dois acompanhamentos são chamadas deliberadamente separadas, portanto, desistir desta não custa nada:

• importe as novas páginas que você deseja com Importar várias páginas de uma vez;
• releia as páginas que você já possui com Atualizar todas as páginas de um site.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

Resposta

{
  "success": true,
  "source_type": "sitemap",
  "discovered": 249,
  "new_pages": [
    {
      "url": "https://example.com/new-guide",
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ],
  "new_urls_queued": 0,
  "existing_refresh_queued": 249
}

Assim como a descoberta, isso falha suavemente: um site que não pode ser lido ainda retorna 200, com success: false, um new_pages vazio e um error. Um baseUrl ausente ou vazio retorna 400.

Atualizar todas as páginas de um site #

POST /kb-sources/trigger-domain-refresh

Releia todas as páginas que você já importou de um site, para que suas FAQs sigam o conteúdo atual do site: seções alteradas são atualizadas, novas seções são adicionadas e seções removidas são descartadas.

Isso coloca o trabalho na fila e retorna imediatamente. Acompanhe com Acompanhar uma atualização de site e interrompa com Parar uma atualização de site.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/trigger-domain-refresh?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

Resposta

{
  "success": true,
  "queued": 249
}

Acompanhar uma atualização de site #

GET /kb-sources/domain-refresh-status

O progresso de uma atualização de site, para que você possa exibir algo como “221 de 249”.

Parâmetros de consulta

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/domain-refresh-status?baseUrl=https://example.com&apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "job": {
    "domainBatchId": "job_7c1e",
    "host": "example.com",
    "total": 249,
    "pending": 28,
    "succeeded": 219,
    "failed": 2,
    "skippedDuplicate": 0,
    "status": "refreshing",
    "startedAtIso": "2026-06-15T09:00:00.000Z"
  }
}

job é null quando nenhuma atualização está sendo executada para aquele site. As páginas concluídas até o momento são total menos pending. O trabalho status é um entre refreshing (ainda processando páginas), deduplicating (a etapa de limpeza no final), ou os estados finais completed, failed e cancelled. Guarde o domainBatchId — é ele que você passa para o endpoint de cancelamento.

Um baseUrl ausente ou vazio retorna 400.

Interromper a atualização de um site #

POST /kb-sources/refresh-domain/cancel

Interrompe a atualização de um site que ainda está processando suas páginas. As páginas já concluídas mantêm seu conteúdo atualizado; as páginas não iniciadas são descartadas, e as páginas que estavam sendo relidas retornam ao seu estado anterior.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain/cancel?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jobId": "job_7c1e" }'

Resposta

{
  "success": true,
  "status": "cancelled",
  "cancelled_units": 28,
  "sources_reset": 3,
  "sources_cancelled": 25
}

Cancelar duas vezes é inofensivo — a segunda chamada relata o mesmo estado final. Uma vez que a atualização tenha avançado para a etapa de limpeza, ela não pode mais ser interrompida, e a resposta retorna com success: false e reason: "already_finalizing". Um jobId ausente retorna 400, e um trabalho que não está em sua conta retorna 404.

Atualizar uma única fonte #

POST /kb-sources/{sourceId}/refresh

Relê uma página da web que você já importou e alinha suas FAQs com o conteúdo atual da página: seções alteradas são atualizadas, novas são adicionadas e as removidas são descartadas.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123/refresh?apiKey=YOUR_API_KEY"

Resposta — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}

Verifique a fonte até que seu status saia de queued e processing. Um ID de fonte que não está em sua conta retorna 404.

Escolher as páginas mais relevantes #

POST /kb-sources/select-relevant-pages

Solicita à IA que escolha as cinco páginas, a partir de uma lista de candidatos, que melhor descrevem um negócio — usado ao gerar um manual de campanha a partir de um site. Isso consome créditos.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/select-relevant-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "homeUrl": "https://example.com",
    "urls": ["https://example.com/about", "https://example.com/pricing"]
  }'

Resposta

{
  "success": true,
  "pages": [
    { "url": "https://example.com/pricing", "title": "Pricing", "type": "pricing" }
  ]
}

Este é um auxiliar, não um recurso: em caso de falha, ele ainda responde 200, com success: false, uma lista pages vazia e uma mensagem error.

Grupos de conhecimento #

Um grupo de conhecimento é um conjunto nomeado de FAQs — “Envio e devoluções”, “Integração” — que você pode aplicar a um Agente ou a uma campanha em uma única chamada. O grupo contém referências, não cópias: as próprias FAQs permanecem em sua biblioteca única, portanto, editar uma delas com a API de FAQs a atualiza onde quer que ela seja usada.

Aplicar um grupo sempre adiciona apenas o que está faltando, portanto, aplicar o mesmo grupo duas vezes é inofensivo e added_count retorna como 0 na segunda vez.

Criar um grupo de conhecimento #

POST /kb-groups

Cria um grupo. Ele começa vazio — adicione FAQs a ele com Adicionar uma FAQ a um grupo.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping and returns" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-groups", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Shipping and returns" }),
});
const { group_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Shipping and returns"},
)
group_id = res.json()["group_id"]

Resposta — 201 Created

{
  "success": true,
  "group_id": "kbg_abc123"
}

Renomear um grupo de conhecimento #

PUT /kb-groups/{groupId}

Altera o nome de um grupo. Suas FAQs permanecem inalteradas.

Campos da requisição

cURL

curl -X PUT "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping, returns and refunds" }'

Resposta

{
  "success": true,
  "group_id": "kbg_abc123",
  "name": "Shipping, returns and refunds"
}

Excluir um grupo de conhecimento #

DELETE /kb-groups/{groupId}

Exclui o grupo. Apenas o conjunto é removido — as FAQs contidas nele permanecem em sua biblioteca, e tudo ao que o grupo já estava aplicado mantém essas FAQs.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true
}

Adicionar um FAQ a um grupo #

POST /kb-groups/{groupId}/faqs

Coloca um FAQ existente em um grupo. Isso altera apenas o pacote — não anexa o FAQ a nenhum Agente por si só; aplique o grupo para isso.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "faq_id": "aBcD1234eFgH5678" }'

Resposta

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

Remover um FAQ de um grupo #

DELETE /kb-groups/{groupId}/faqs/{faqId}

Remove um FAQ de um grupo. O FAQ em si não é excluído, e os Agentes aos quais o grupo já foi aplicado o mantêm.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

Aplicar um grupo a um Agente #

POST /kb-groups/{groupId}/apply-to-agent

Adiciona todos os FAQs do grupo ao conhecimento de um Agente de IA em uma única chamada — a maneira rápida de fornecer a um novo Agente um corpo de conhecimento que você já curou.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent_id: "ag7HkQ2ZpLxR3mNb" }),
  }
);
const { added_count } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"agent_id": "ag7HkQ2ZpLxR3mNb"},
)
added_count = res.json()["added_count"]

Resposta

{
  "success": true,
  "group_id": "kbg_abc123",
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "added_count": 12
}

added_count é a quantidade de FAQs que foram realmente adicionados — 0 quando o grupo está vazio ou já foi aplicado.

Aplicar um grupo a uma campanha #

POST /kb-groups/{groupId}/apply-to-campaign

A versão de campanha clássica da chamada acima. Em uma conta baseada em Agente, use Aplicar um grupo a um Agente em vez disso.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign123" }'

Resposta

{
  "success": true,
  "group_id": "kbg_abc123",
  "campaign_id": "campaign123",
  "added_count": 12
}

Erros da API da Base de Conhecimento #

Estes endpoints retornam o envelope de erro padrão:

{
  "success": false,
  "error": "Knowledge base source not found."
}

Falhas leves não são erros. A descoberta (discover-pages, refresh-domain) e o auxiliar de seleção de página respondem 200 com success: false e uma mensagem error quando o site não pode ser lido, em vez de falhar na solicitação. Sempre verifique success antes de ler os dados.

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.

Relacionado #

• API de FAQs — leia, edite e vincule as FAQs que suas fontes produzem.
• Gerenciando FAQs — a mesma base de conhecimento no painel.
• Agentes de IA — os Agentes aos quais você anexa fontes e grupos.
• Acesso à API — gere sua chave de API.
• Autenticação — todas as maneiras de passar sua chave.