API da Base de Conhecimento

A sua base de conhecimento é aquilo que a IA lê. É composta por duas partes, e esta página abrange ambas:

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

As FAQs que uma fonte produz vão parar à mesma biblioteca que as que escreve manualmente, por isso, assim que uma importação termina, pode lê-las, editá-las e associá-las com a API de FAQs.

Todos os endpoints abaixo são relativos ao URL base https://api.youraiconnector.com/v1. Todos os pedidos devem ser autenticados — consulte Acesso à API e Autenticação. O acesso à API é uma funcionalidade paga; sem ele, os pedidos são rejeitados 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. Utilize Estimar uma importação antes de se comprometer com uma pesquisa de grande dimensão.

Como funciona uma importação

A importação é uma tarefa em segundo plano, não algo que termina enquanto espera. Cada endpoint de importação responde imediatamente com um source_id, e deve consultar essa fonte até que esteja concluída:

Iniciar a importação — POST /kb-sources/url (uma página), POST /kb-sources/file (um documento carregado) ou POST /kb-sources/bulk-import (até 100 páginas). Recebe um ID de fonte e um status: "queued".
Consultar — GET /kb-sources/{sourceId} até que o status deixe de ser queued ou processing.
Ler as FAQs — quando o estado for ready, as entradas produzidas estarão na sua biblioteca de FAQs: GET /faqs.

Cada fonte reporta um destes estados:

Estado	O que significa
`queued`	À espera de ser lido. Ainda não foi cobrado nada.
`processing`	A ser lido e transformado em FAQs neste momento.
`ready`	Concluído. As suas FAQs estão na sua biblioteca.
`failed`	Não pôde ser importado. O `error_message` indica o motivo.
`cancelled`	Parado antes de ser lido (ver Parar uma importação).
`paused`	Parado porque a sua própria chave de IA falhou a meio da importação (ver Retomar uma importação em pausa).
`deleting`	Uma remoção em massa está a processar o conteúdo.
`unknown`	O registo não apresenta estado. Considere-o como não pronto.

Anexar ao importar. Passe autoLinkToAgentId em qualquer endpoint de importação e a fonte — juntamente com cada FAQ que produz — é adicionada ao conhecimento desse Agente na mesma chamada, sem necessidade de um passo de associação posterior. O autoLinkToCampaignId faz o mesmo para uma campanha clássica. A associação é feita com o melhor esforço: um ID que não existe, ou que pertence a outra conta, é ignorado silenciosamente e a importação continua a decorrer, por isso confirme a associação lendo o Agente novamente.

Importar uma página web

POST /kb-sources/url

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

Campos do pedido

Campo	Obrigatório	Descrição
`url`	Sim	`http` ou `https` completo da página.
`autoLinkToAgentId`	Não	ID de um Agente de IA ao qual anexar a fonte importada.
`autoLinkToCampaignId`	Não	Legado. ID de uma campanha à qual anexar a fonte importada.

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

Consulte source_id com Verificar uma fonte até que o estado seja ready ou failed.

Se a mesma página já estiver na sua base de conhecimento, nada de novo é colocado na fila e recebe um 200 em vez disso — e se pediu uma ligação automática, a fonte existente é ligada para si de qualquer forma:

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

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

Importar um documento carregado

POST /kb-sources/file

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

Este endpoint não transporta o ficheiro. Não existe carregamento multipart, nem corpo base64, nem transferência a partir de um URL: envia a localização de armazenamento de um ficheiro que já existe, e este deve estar na sua própria pasta de carregamentos (storage_path tem de começar com users/{your user id}/uploads/) ou o pedido será recusado com 403. O painel de controlo coloca os ficheiros lá quando os arrasta para lá. Se não tiver forma de colocar um ficheiro lá, importe uma página web com Importar uma página web em vez disso.

Campos do pedido

Campo	Obrigatório	Descrição
`storage_path`	Sim	Onde reside o ficheiro carregado. Deve começar com `users/{your user id}/uploads/`.
`filename`	Sim	Nome original do ficheiro, incluindo a sua extensão — é assim que o tipo de ficheiro é detetado.
`mime_type`	Sim	Tipo MIME do ficheiro, por exemplo `application/pdf`.
`autoLinkToAgentId`	Não	ID de um Agente de IA ao qual anexar o documento.
`autoLinkToCampaignId`	Não	Legado. ID de uma campanha à qual anexar o documento.

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

Estado	Quando
`400`	Falta um campo obrigatório, ou o ficheiro não é de um tipo que possamos ler.
`403`	`storage_path` está fora da sua própria pasta de carregamentos.

Verificar uma fonte

GET /kb-sources/{sourceId}

A consulta que se segue a cada importação e atualização. Repita-a até que o estado 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
}

Campo	Tipo	Descrição
`status`	string	Onde a origem se encontra no pipeline (consulte a tabela de estado).
`faq_count`	integer	Quantas FAQs foram geradas a partir desta origem até ao momento.
`section_count`	integer	Em quantas secções de conteúdo a origem foi dividida.
`error_message`	string \| null	O motivo da falha da importação, quando o estado é `failed`. `null` caso contrário.

Eliminar uma origem

DELETE /kb-sources/{sourceId}

Remove uma origem de conhecimento. Por predefinição, as FAQs produzidas pela mesma são mantidas — adicione delete_faqs=true para as remover também.

Parâmetros de consulta

Parâmetro	Obrigatório	Descrição
`delete_faqs`	Não	Defina como `true` para eliminar também todas as FAQs que esta origem produziu. O valor predefinido é `false`.

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 tenha solicitado delete_faqs=true.

Importar várias páginas de uma só vez

POST /kb-sources/bulk-import

Adiciona até 100 páginas web numa única chamada — o seguimento habitual de Descobrir páginas num website ou Encontrar novas páginas num website. As páginas que já se encontram na sua base de conhecimento são ignoradas em vez de duplicadas (e continuam ligadas ao Agente quando solicitado).

Campos do pedido

Campo	Obrigatório	Descrição
`urls`	Sim	Endereços a importar. Pelo menos 1, no máximo 100 por chamada.
`autoLinkToAgentId`	Não	ID de um Agente de IA ao qual associar cada página importada.
`autoLinkToCampaignId`	Não	Legado. ID de uma campanha à qual associar cada página importada.

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

Consulte cada ID em queued_source_ids com Verificar uma origem. O envio de uma matriz urls vazia, uma entrada que não seja uma string ou mais de 100 entradas devolve 400.

Eliminar várias origens de uma só vez

POST /kb-sources/bulk-delete

Remove até 2.000 origens de conhecimento numa única chamada. A remoção é executada em segundo plano e receberá um e-mail quando terminar.

A eliminação em massa remove sempre as FAQs também. Ao contrário de Eliminar uma fonte, que as mantém a menos que peça o contrário, este endpoint elimina cada fonte juntamente com as FAQs que produziu. Não existe opção para as manter.

Campos do pedido

Campo	Obrigatório	Descrição
`sourceIds`	Sim	IDs das fontes a remover. Pelo menos 1, no máximo 2.000 por chamada.
`domainLabel`	Não	Um nome amigável para esta limpeza. Usado apenas no e-mail de conclusã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 num 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 importar. Nada é importado e nada é selecionado por si — este é o passo “o que existe neste site” que executa antes de decidir o que enviar para Importar muitas páginas de uma vez.

Campos do pedido

Campo	Obrigatório	Descrição
`url`	Sim	Endereço a partir do qual começar a explorar, normalmente a página inicial do site.
`maxPages`	Não	Limite superior de quantas páginas devolver.

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

Campo	Tipo	Descrição
`source_type`	string	Como as páginas foram encontradas — `sitemap` (o sitemap do próprio site) ou `link_discovery` (seguindo links).
`url`	string	Endereço completo da página.
`title`	string \| null	Título da página, quando foi possível lê-lo.
`depth`	integer	A quantos links de distância da página inicial esta página foi encontrada.
`score`	integer	Quão útil a página parece como conhecimento, de `0` a `100`.
`recommendation`	string	`add` (claramente vale a pena importar, pontuação 90 ou superior), `maybe` (limítrofe), ou `skip` (conteúdo que raramente ajuda um assistente — registos de alterações, páginas legais, traduções duplicadas).
`reason_key`	string	Uma razão estável e legível por máquina por trás da recomendação, por exemplo `core_page`, `changelog_history`, `legal_page` ou `locale_duplicate`.

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

Um url em falta devolve 400.

Estimar o custo de uma importação

POST /kb-sources/estimate-cost

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

Campos do pedido

Campo	Obrigatório	Descrição
`urls`	Não	Endereços de páginas que está a considerar importar.
`files`	Não	Ficheiros já carregados que está a considerar. Cada entrada precisa de `storage_path`, `filename` e `mime_type`.
`tier`	Não	O nível de qualidade de IA em que a importação será executada, para que a estimativa corresponda ao que lhe será realmente cobrado. Deixe de fora para a taxa padrã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
}

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

Parar uma importação

POST /kb-sources/cancel-import

Para as páginas que ainda estão à espera na fila de importação — o botão “parar importação” para uma pesquisa que se revelou maior do que esperava. Cancelar uma página em espera não tem custos, porque ainda não foi lida.

As páginas que já estão a ser processadas não são paradas: o seu trabalho está em curso e é cobrado de qualquer forma, por isso concluem o processo. A resposta indica quantas foram.

Campos do pedido

Campo	Obrigatório	Descrição
`host`	Não	Parar apenas as páginas em espera neste website (por exemplo `docs.example.com`). Deixe em branco para parar todas as importações em espera na conta.

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 a sua própria chave de IA deixou de funcionar.

Ao chamar isto, está a dar o seu consentimento para concluir a importação com a chave que estiver ativa no momento — o que pode significar gastar créditos da plataforma se a sua própria chave continuar inativa.

Campos do pedido

Campo	Obrigatório	Descrição
`host`	Não	Retomar apenas as páginas pausadas neste website. Deixe em branco para retomar tudo o que está pausado.

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 num website

POST /kb-sources/refresh-domain

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

As duas ações de seguimento são chamadas deliberadamente separadas, pelo que desistir desta não tem qualquer custo:

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

Campos do pedido

Campo	Obrigatório	Descrição
`baseUrl`	Sim	Qualquer endereço no site, ou apenas o host.
`maxPages`	Não	Limite superior de quantas páginas explorar.

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
}

Campo	Tipo	Descrição
`discovered`	integer	Quantas páginas foram encontradas no site no total.
`new_pages`	array	Páginas que ainda não estão na sua base de conhecimento. Nada é colocado em fila para si — importe as que desejar.
`new_urls_queued`	integer	Sempre `0`. Mantido por retrocompatibilidade; este endpoint nunca coloca nada em fila.
`existing_refresh_queued`	integer	Quantas páginas que já importou deste site foram encontradas prontas para serem relidas. Nada é colocado em fila por esta chamada.
`batch_id`	string	Presente apenas quando um lote foi criado.

Tal como a descoberta, isto falha de forma suave: um site que não pode ser lido ainda devolve 200, com success: false, um new_pages vazio e um error. Um baseUrl em falta ou vazio devolve 400.

Atualizar todas as páginas de um site

POST /kb-sources/trigger-domain-refresh

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

Isto coloca o trabalho em fila e devolve imediatamente. Acompanhe com Acompanhar a atualização de um site e pare com Parar a atualização de um site.

Campos do pedido

Campo	Obrigatório	Descrição
`baseUrl`	Sim	Qualquer endereço no site, ou apenas o host.

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 a atualização de um site

GET /kb-sources/domain-refresh-status

O estado de progresso da atualização de um site, para que possa mostrar o progresso como “221 de 249”.

Parâmetros de consulta

Parâmetro	Obrigatório	Descrição
`baseUrl`	Sim	Qualquer endereço no site, ou apenas o host.

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 não existe nenhuma atualização em curso para esse site. As páginas concluídas até ao momento são total menos pending. O trabalho status é um de refreshing (ainda a processar páginas), deduplicating (a passagem de limpeza no final), ou o final completed, failed e cancelled. Guarde o domainBatchId — é o que passa para o endpoint de cancelamento.

Um baseUrl em falta ou vazio devolve 400.

Parar a atualização de um site

POST /kb-sources/refresh-domain/cancel

Para a atualização de um site que ainda está a processar as suas páginas. As páginas já concluídas mantêm o seu conteúdo atualizado; as páginas que ainda não foram iniciadas são descartadas e as páginas que estavam a ser lidas novamente regressam ao seu estado anterior.

Campos do pedido

Campo	Obrigatório	Descrição
`jobId`	Sim	O `domainBatchId` devolvido por Monitorizar a atualização de um site.

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
}

Campo	Tipo	Descrição
`status`	string	Estado da atualização após esta chamada: `cancelled`, `deduplicating`, `completed` ou `failed`.
`cancelled_units`	integer	Quanto trabalho ainda estava pendente quando o cancelamento foi efetuado. `0` num cancelamento repetido.
`sources_reset`	integer	Páginas retiradas do processamento e devolvidas a `ready`.
`sources_cancelled`	integer	Páginas novas desta atualização que ainda estavam na fila e foram agora canceladas.

Cancelar duas vezes não tem consequências — a segunda chamada reporta o mesmo estado final. Uma vez que a atualização tenha avançado para a fase de limpeza, já não pode ser parada e a resposta devolve success: false e reason: "already_finalizing". Um jobId em falta devolve 400, e um trabalho que não se encontra na sua conta devolve 404.

Atualizar uma única fonte

POST /kb-sources/{sourceId}/refresh

Lê novamente uma página web que já importou e alinha as suas FAQ com o conteúdo atual da página: as secções alteradas são atualizadas, as 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"
}

Consulte a fonte até que o seu estado saia de queued e processing. Um ID de fonte que não se encontre na sua conta devolve 404.

Escolher as páginas mais relevantes

POST /kb-sources/select-relevant-pages

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

Campos do pedido

Campo	Obrigatório	Descrição
`urls`	Sim	Endereços das páginas candidatas a escolher, normalmente provenientes da descoberta de páginas.
`homeUrl`	Sim	A página inicial do site, utilizada como contexto para a escolha.

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, responde na mesma com 200, com success: false, uma lista pages vazia e uma mensagem error.

Grupos de conhecimento

Um grupo de conhecimento é um conjunto nomeado de FAQs — “Envios e devoluções”, “Integração” — que pode aplicar a um Agente ou a uma campanha numa única chamada. O grupo contém referências, não cópias: as próprias FAQs permanecem na sua biblioteca única, pelo que editar uma com a API de FAQs atualiza-a em todos os locais onde é utilizada.

Aplicar um grupo apenas adiciona o que falta, pelo que aplicar o mesmo grupo duas vezes é inofensivo e added_count devolve 0 na segunda vez.

Criar um grupo de conhecimento

POST /kb-groups

Cria um grupo. Começa vazio — adicione-lhe FAQs com Adicionar uma FAQ a um grupo.

Campos do pedido

Campo	Obrigatório	Descrição
`name`	Sim	Nome do grupo.

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

Mudar o nome de um grupo de conhecimento

PUT /kb-groups/{groupId}

Altera o nome de um grupo. As suas FAQs permanecem inalteradas.

Campos do pedido

Campo	Obrigatório	Descrição
`name`	Sim	Novo nome do grupo.

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

Eliminar um grupo de conhecimento

DELETE /kb-groups/{groupId}

Elimina o grupo. Apenas o conjunto é removido — as FAQs nele contidas permanecem na sua biblioteca e tudo ao que o grupo já tinha sido 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 uma FAQ a um grupo

POST /kb-groups/{groupId}/faqs

Coloca uma FAQ existente num grupo. Isto apenas altera o pacote — não associa a FAQ a nenhum Agente por si só; aplique o grupo para esse efeito.

Campos do pedido

Campo	Obrigatório	Descrição
`faq_id`	Sim	ID da FAQ a adicionar.

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 uma FAQ de um grupo

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

Retira uma FAQ de um grupo. A FAQ em si não é eliminada e os Agentes aos quais o grupo já tinha sido aplicado mantêm-na.

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 todas as FAQs do grupo ao conhecimento de um Agente de IA numa única chamada — a forma rápida de fornecer a um novo Agente um conjunto de conhecimentos que já tenha organizado.

Campos do pedido

Campo	Obrigatório	Descrição
`agent_id`	Sim	ID do Agente de IA ao qual aplicar o grupo.

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 é o número de FAQs que foram efetivamente adicionadas — 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. Numa conta baseada em Agentes, utilize Aplicar um grupo a um Agente em vez disso.

Campos do pedido

Campo	Obrigatório	Descrição
`campaign_id`	Sim	ID da campanha à qual aplicar o grupo.

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 devolvem o envelope de erro padrão:

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

Estado	Quando ocorre num endpoint da base de conhecimento
`400`	Falta um campo obrigatório ou é inválido — um `url` vazio, um `baseUrl` ou `jobId` em falta, mais de 100 URLs numa importação em massa, mais de 2.000 IDs numa eliminação em massa, ou um tipo de ficheiro que não conseguimos ler.
`402`	Créditos insuficientes para executar a importação. Carregue a conta e tente novamente.
`403`	Um `storage_path` fora da sua própria pasta de carregamentos — ou o seu plano não inclui acesso à API.
`404`	A fonte, grupo, FAQ, Agente, campanha ou tarefa de atualização não foi encontrada — ou não existe ou pertence a outra conta.

As falhas parciais não são erros. A descoberta (discover-pages, refresh-domain) e o auxiliar de seleção de páginas respondem 200 com success: false e uma mensagem error quando o website não pode ser lido, em vez de falhar o pedido. Verifique sempre success antes de ler os dados.

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

Relacionado

API de FAQs — leia, edite e associe as FAQs que as suas fontes produzem.
Gerir FAQs — a mesma base de conhecimento no painel de controlo.
Agentes de IA — os Agentes aos quais associa fontes e grupos.
Acesso à API — gere a sua chave de API.
Autenticação — todas as formas de transmitir a sua chave.

API da Base de Conhecimento #

Como funciona uma importação #

Importar uma página web #

Importar um documento carregado #

Verificar uma fonte #

Eliminar uma origem #

Importar várias páginas de uma só vez #

Eliminar várias origens de uma só vez #

Descobrir páginas num site #

Estimar o custo de uma importação #

Parar uma importação #

Retomar uma importação pausada #

Encontrar novas páginas num website #

Atualizar todas as páginas de um site #

Acompanhar a atualização de um site #

Parar a atualização de um site #

Atualizar uma única fonte #

Escolher as páginas mais relevantes #

Grupos de conhecimento #

Criar um grupo de conhecimento #

Mudar o nome de um grupo de conhecimento #

Eliminar um grupo de conhecimento #

Adicionar uma FAQ a um grupo #

Remover uma FAQ de um grupo #

Aplicar um grupo a um Agente #

Aplicar um grupo a uma campanha #

Erros da API da Base de Conhecimento #

Relacionado #

API da Base de Conhecimento

Como funciona uma importação

Importar uma página web

Importar um documento carregado

Verificar uma fonte

Eliminar uma origem

Importar várias páginas de uma só vez

Eliminar várias origens de uma só vez

Descobrir páginas num site

Estimar o custo de uma importação

Parar uma importação

Retomar uma importação pausada

Encontrar novas páginas num website

Atualizar todas as páginas de um site

Acompanhar a atualização de um site

Parar a atualização de um site

Atualizar uma única fonte

Escolher as páginas mais relevantes

Grupos de conhecimento

Criar um grupo de conhecimento

Mudar o nome de um grupo de conhecimento

Eliminar um grupo de conhecimento

Adicionar uma FAQ a um grupo

Remover uma FAQ de um grupo

Aplicar um grupo a um Agente

Aplicar um grupo a uma campanha

Erros da API da Base de Conhecimento

Relacionado