Fontes e Treinamento da API v2

Liste e crie fontes do agente, envie arquivos diretamente para o armazenamento, exclua documentos, verifique o status do treinamento e inicie o retreinamento de fontes da web.

Use esses endpoints para gerenciar fontes de texto, Q&A, URL e arquivo, e para retreinar fontes web indexadas. Todo endpoint nesta página exige Authorization: Bearer YOUR_API_KEY e acesso a {agentId}.

Consulte o catálogo de erros para os erros compartilhados de autenticação, validação, cota e recurso.

Objeto Source

Campo	Tipo	Notas
`id`	string	ID do documento.
`title`	string	Título da fonte.
`sourceType`	string	Tipo de fonte armazenado, incluindo `web_crawl`, `file_upload`, `text_snippet` ou `qna_entry`.
`createdAt`	integer ou null	Timestamp Unix em segundos.
`lastCrawledAt`	integer ou null	Timestamp Unix em segundos.
`sourceMetadata`	qualquer valor JSON	Metadados da fonte armazenados.

Listar Fontes

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

GET /api/v2/agents/{agentId}/sources

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

Query	Obrigatório	Restrições
`limit`	Não	Número inteiro de 1 a 100; padrão é 20.
`cursor`	Não	Cursor opaco retornado pela página anterior. Reenvie sem alterações.
`sourceType`	Não	`web_crawl`, `file_upload`, `text_snippet` ou `qna_entry`.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources?sourceType=text_snippet&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Sucesso: 200 OK

{
  "data": [
    {
      "id": "41b4c1d3-887d-46a5-95ae-c761922c6bc7",
      "title": "Refund policy",
      "sourceType": "text_snippet",
      "createdAt": 1784332800,
      "lastCrawledAt": null,
      "sourceMetadata": null
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Limites, cursores e tipos de fonte inválidos retornam 400 VALIDATION_INVALID_BODY.

Adicionar uma Fonte de Texto

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

POST /api/v2/agents/{agentId}/sources/text

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

Campo do corpo	Obrigatório	Tipo e restrições
`title`	Sim	String de 1 a 200 caracteres antes do corte; o valor aceito é cortado (trim).
`content`	Sim	String não vazia, com no máximo 262.144 bytes UTF-8 (256 KB), e que não seja apenas espaços em branco.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/text' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Refund policy","content":"Refunds are available within 30 days."}'

Sucesso: 201 Created

{
  "documentId": "41b4c1d3-887d-46a5-95ae-c761922c6bc7"
}

Entradas inválidas ou uma falha de processamento não relacionada a armazenamento retornam 400 VALIDATION_INVALID_BODY. Uma falha de processamento por limite de armazenamento retorna 403 QUOTA_STORAGE_LIMIT.

Adicionar uma Fonte de Q&A

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

POST /api/v2/agents/{agentId}/sources/qna

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

Campo do corpo	Obrigatório	Tipo e restrições
`title`	Sim	String de 1 a 200 caracteres antes do corte; o valor aceito é cortado (trim).
`questions`	Sim	Array com no máximo 10 strings, cada uma com no máximo 500 caracteres. Pelo menos uma entrada deve conter um caractere que não seja espaço em branco.
`answer`	Sim	String não vazia, com no máximo 262.144 bytes UTF-8 (256 KB), e que não seja apenas espaços em branco.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/qna' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Shipping time","questions":["How long does shipping take?","When will my order arrive?"],"answer":"Standard shipping takes 3–5 business days."}'

Sucesso: 201 Created

{
  "documentId": "531a3fbe-40c2-4d22-a524-1f4a70f509f1"
}

Adicionar ou Retreinar uma Fonte de URL

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

POST /api/v2/agents/{agentId}/sources/url

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

Campo do corpo	Obrigatório	Tipo e restrições
`url`	Sim	URL HTTP ou HTTPS não vazia, com um domínio. Um protocolo ausente é normalizado para `https://`. Loopback, faixas de IP privadas, link-local, unique-local, reservadas, variantes de localhost, TLDs internos e hostnames de rótulo único são rejeitados.

Enviar uma URL já indexada para o agente cria um job de retreinamento. Uma URL nova primeiro verifica a capacidade de armazenamento. URLs de vídeo também exigem acesso ao plano de transcrição de vídeo.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/url' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://docs.example.com/getting-started"}'

Sucesso: 202 Accepted

{
  "jobId": "c3c61f67-70fe-42da-a843-24112ded8aeb",
  "isRetrain": false
}

Entradas inválidas retornam 400 VALIDATION_INVALID_BODY. A falta de acesso à transcrição de vídeo retorna 403 SUBSCRIPTION_API_RESTRICTED_PLAN; falhas de cota de armazenamento ou fila retornam 403 QUOTA_STORAGE_LIMIT; uma falha na criação do job não relacionada a cota retorna 500 INTERNAL_SERVER_ERROR.

Adicionar Fontes de Arquivo com URLs de Upload Assinadas

Fontes de arquivo usam um fluxo de API em duas etapas para que os bytes do arquivo viajem diretamente do seu cliente para o armazenamento privado, em vez de passar pela rota da API. Cada arquivo pode ter no máximo 50 MB, e uma requisição pode conter no máximo 20 arquivos. As extensões suportadas são .pdf, .txt, .md, .docx, .xlsx e .pptx.

1. Criar URLs de Upload Assinadas

Caminho: /api/v2/agents/{agentId}/sources/file/upload-url

POST /api/v2/agents/{agentId}/sources/file/upload-url

Envie os nomes originais dos arquivos:

{
  "files": [
    { "fileName": "product-guide.pdf" },
    { "fileName": "faq.md" }
  ]
}

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/file/upload-url' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"files":[{"fileName":"product-guide.pdf"},{"fileName":"faq.md"}]}'

Sucesso: 200 OK

{
  "files": [
    {
      "fileName": "product-guide.pdf",
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/V1StGXR8_Z5jdHi6-product-guide.pdf",
      "uploadUrl": "https://storage.example.com/storage/v1/object/upload/sign/training_files/chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/V1StGXR8_Z5jdHi6-product-guide.pdf?token=SIGNED_TOKEN",
      "token": "SIGNED_TOKEN"
    },
    {
      "fileName": "faq.md",
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/N5jFt4Z9kSC3vHqA-faq.md",
      "uploadUrl": "https://storage.example.com/storage/v1/object/upload/sign/training_files/chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/N5jFt4Z9kSC3vHqA-faq.md?token=SIGNED_TOKEN",
      "token": "SIGNED_TOKEN"
    }
  ]
}

2. Fazer Upload dos Bytes do Arquivo

Faça upload de cada arquivo diretamente para sua uploadUrl com PUT:

await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': file.type },
  body: file,
});

Ao usar o cliente JavaScript do Supabase, passe o caminho e o token correspondentes da etapa 1:

await supabase.storage
  .from('training_files')
  .uploadToSignedUrl(storagePath, token, file);

Não altere ou construa os caminhos de armazenamento você mesmo. O registro aceita apenas caminhos retornados para este agente pela etapa 1.

3. Registrar os Arquivos Enviados

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

POST /api/v2/agents/{agentId}/sources/file

Depois que cada upload direto for concluído, registre os caminhos retornados com seus nomes de arquivo originais:

{
  "files": [
    {
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/V1StGXR8_Z5jdHi6-product-guide.pdf",
      "fileName": "product-guide.pdf"
    },
    {
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/N5jFt4Z9kSC3vHqA-faq.md",
      "fileName": "faq.md"
    }
  ]
}

Sucesso: 202 Accepted

{
  "jobId": 321,
  "fileCount": 2
}

O registro verifica se cada objeto existe, não está vazio, não é maior que 50 MB e pertence ao agente solicitado antes de iniciar o job de processamento. Uploads inválidos ou ausentes retornam 400 VALIDATION_INVALID_BODY; uma negação por cota de armazenamento retorna 403 QUOTA_STORAGE_LIMIT; falhas de Storage ou fila retornam 500 INTERNAL_SERVER_ERROR.

Excluir uma Fonte

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

DELETE /api/v2/agents/{agentId}/sources/{documentId}

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

{documentId} deve ser um UUID retornado por uma resposta de criação de fonte ou de listagem.

curl -X DELETE 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/41b4c1d3-887d-46a5-95ae-c761922c6bc7' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Sucesso: 200 OK

{
  "deleted": true
}

Um UUID inválido retorna 400 VALIDATION_INVALID_BODY. Um UUID válido que não identifica um documento do agente retorna 404 RESOURCE_DOCUMENT_NOT_FOUND.

Obter Status de Treinamento

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

GET /api/v2/agents/{agentId}/train

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

Sucesso: 200 OK, com um objeto de status simples.

Campo	Tipo	Notas
`status`	string	`training` quando existe um job pendente/em execução, caso contrário `trained` quando existe um timestamp do último treinamento, caso contrário `idle`.
`documentCount`	integer	Número de documentos-fonte do agente.
`lastTrainedAt`	integer ou null	Timestamp Unix em segundos.
`activeJob`	object ou null	Job pendente/em execução mais recente.
`activeJob.id`	string	ID do job.
`activeJob.status`	string	Status do job armazenado.
`activeJob.tasksCount`	integer	Contagem total de tarefas.
`activeJob.tasksCompletedCount`	integer	Contagem de tarefas concluídas.
`activeJob.createdAt`	integer ou null	Timestamp Unix em segundos.

{
  "status": "training",
  "documentCount": 12,
  "lastTrainedAt": 1784246400,
  "activeJob": {
    "id": "c3c61f67-70fe-42da-a843-24112ded8aeb",
    "status": "running",
    "tasksCount": 8,
    "tasksCompletedCount": 3,
    "createdAt": 1784332800
  }
}

Iniciar Retreinamento de Fontes Web

POST /api/v2/agents/{agentId}/train

Autenticação: Chave de API Bearer com acesso a {agentId}. Este endpoint não recebe corpo de requisição.

O endpoint retreina URLs web indexadas, não fontes de texto, Q&A ou arquivo enviado.

Quando existe pelo menos uma URL indexada, o sucesso é 202 Accepted:

{
  "jobId": "c3c61f67-70fe-42da-a843-24112ded8aeb",
  "count": 8,
  "message": "Retraining started for 8 URLs"
}

Quando não existem URLs indexadas, o sucesso é 200 OK e nenhum job é criado:

{
  "jobId": null,
  "count": 0,
  "message": "No web sources to retrain"
}

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

Fontes e Treinamento da API v2

Liste e crie fontes do agente, envie arquivos diretamente para o armazenamento, exclua documentos, verifique o status do treinamento e inicie o retreinamento de fontes da web.

Objeto Source

Listar Fontes

Adicionar uma Fonte de Texto

Adicionar uma Fonte de Q&A

Adicionar ou Retreinar uma Fonte de URL

Adicionar Fontes de Arquivo com URLs de Upload Assinadas

1. Criar URLs de Upload Assinadas

2. Fazer Upload dos Bytes do Arquivo

3. Registrar os Arquivos Enviados

Excluir uma Fonte

Obter Status de Treinamento

Iniciar Retreinamento de Fontes Web

Referência Relacionada