> ## Documentation Index > Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt > Use this file to discover all available pages before exploring further. # Archbee > Os documentos dos spaces do Archbee que você escolher chegam ao Knowledge em markdown, com link para o documento original. O conector Archbee lê os documentos dos spaces que você escolher no Data Catalog e os envia ao Knowledge como texto em markdown, cada um com o link para o documento no Archbee. A Strattum guarda só os metadados do documento no Data Catalog. O corpo vai direto para o Knowledge. | | | | - | - | | **Status** | Disponível | | **Conteúdo** | Documentos | | **Autenticação** | Chave de API de time | | **Permissões** | Sem permissão por item | | **Sincronização** | Full refresh | | **Última revisão** | 27/10/2026 | ## Capacidades * Traz ao Data Catalog uma linha por documento, com título, space, chaves de URL, marcação de privacidade, indicador de oculto, documento pai, datas de criação e atualização, versão e um hash do conteúdo. * Envia ao Knowledge o corpo de cada documento em markdown, sem o bloco de metadados que o Archbee coloca no início, com título, link para o Archbee e a data da última atualização. * Trabalha por space: você escolhe no Data Catalog quais spaces entram, e o que não foi escolhido não é lido. * Não alimenta o Memory: o conector não tem ontologia e o destino dos documentos é só o Knowledge. ## Recursos disponíveis | Recurso | O que contém | Carga | Cursor | Destino | Permissão por item | | - | - | - | - | - | - | | `docs` | Um documento por linha, com `name`, `space_id`, `space_name`, `url_key`, `url_alias`, `privacy`, `hidden`, `parent_doc_id`, `created_at`, `updated_at`, `version` e `content_hash`. O corpo não fica na tabela | Full refresh | Nenhum | Knowledge | Não | As páginas de categoria do Archbee não viram documento. O Archbee não devolve corpo para elas, e o conector as ignora. ## Permissões (ACL) Esta fonte não define permissões por registro, então todo mundo que puder usar o conector vê todos os registros. Quem pode usar o conector é definido em **Quem pode usar este conector**: "Todos os usuários" ou "Apenas times específicos". O **Comportamento dos dados** deste conector é sempre "Aberto". ### Como a fonte define acesso A API do Archbee não expõe membros, grupos nem permissões. Cada documento traz só uma marcação de privacidade (`private`, `shared with team`, `public-via-link` ou `public`), que descreve como o documento é publicado e não diz quem pode lê-lo. ### Como a Strattum traduz o acesso A Strattum não traduz nada: o conector não gera permissão por documento. A marcação de privacidade e o indicador de oculto ficam como metadados em `docs` e no documento enviado ao Knowledge, e não restringem ninguém. Documentos `private` e `hidden` entram como os demais. ### Quando a identidade não é encontrada Não se aplica. Sem permissão por item, a Strattum não compara pessoas do Archbee com usuários da Strattum. ### Quando a permissão é atualizada Não se aplica. Os documentos chegam ao Knowledge sem lista de acesso própria, e quem os vê é definido pelo contexto do Knowledge ao qual a fonte está ligada. Para limitar o acesso, use **Quem pode usar este conector** e escolha só os spaces que podem ser lidos por esse público. ## Pré-requisitos * Um plano pago do Archbee com o complemento **API Access**. Sem ele, o Archbee recusa a chave e o teste de conexão avisa que o plano não inclui acesso à API. * Permissão de admin do time no Archbee para criar a chave em **Settings → Developer**. * Ao menos um space com documentos. ## Autenticação e escopos A autenticação usa uma chave de API de time, que começa com `abteam_`. O Archbee não tem escopos nomeados: a chave lê o que o time dela tem, e só a opção de somente leitura limita a chave. O conector só faz leituras e funciona com uma chave somente leitura. | Escopo ou permissão | Para quê | | - | - | | Chave de time (`abteam_`) | Listar os spaces do time, em `GET /space-group/list`. Uma chave de um único space recebe 403 nesse endereço | | Acesso de leitura aos spaces do time | Listar os documentos de cada space e ler o corpo de cada um | **1. Abra as chaves de API** No Archbee, como admin do time, abra **Settings → Developer**. **2. Crie a chave** Crie uma chave de time somente leitura e copie o valor, que começa com `abteam_`. **3. Confirme o complemento** Confira que o plano do time inclui o complemento **API Access**. > [!WARNING] > > A chave de time enxerga todos os spaces do time, não só os que você vai escolher na Strattum. Use uma chave somente leitura e guarde-a como uma senha. ## Configuração no Console **1. Abra o assistente** Em **Conectores**, crie uma nova conexão e selecione **Archbee**. **2. Preencha a conexão** **Nome do Conector** (Opcional): como a conexão aparece na lista. O padrão é `Archbee`. **API Key** (Obrigatório): a chave de time copiada do Archbee. **3. Teste a conexão** Clique em **Testar Conexão**. Você só avança depois de um teste com sucesso. O teste faz uma única requisição de leitura, a lista de spaces do time. **4. Escolha a frequência** Na etapa **Sincronização** (Obrigatório), escolha a frequência. Ela vale para todos os spaces escolhidos no Data Catalog. **5. Defina o acesso** Na etapa **Permissionamento**, defina **Quem pode usar este conector** (Obrigatório). O **Comportamento dos dados** fica sempre em "Aberto". **6. Revise e salve** Em **Revisão**, confira os dados e salve. O assistente não pede space. **7. Escolha os spaces** No Data Catalog, abra o conector e, na seção **Espaços no contexto**, marque os spaces que devem entrar e clique em **Salvar seleção**. Sem nenhum space marcado, o conector não sincroniza. Na edição do conector, a chave salva não aparece. Deixe o campo em branco para manter a chave atual, ou informe uma nova para trocá-la. > [!NOTE] > > Os documentos só aparecem na busca quando um contexto do Knowledge inclui o conector. Ao incluí-lo, o seletor de **Espaços disponíveis** do contexto lista os mesmos spaces do time, e você marca os que esse contexto recebe. ## Como a sincronização funciona O conector lê tudo a cada execução, porque a API do Archbee não filtra documentos por data. A agenda padrão é a cada 6 horas, em UTC, e você pode mudar a frequência no assistente ou na edição do conector. **Ordem.** Em cada execução, o conector lista os spaces do time e, para cada space escolhido, faz uma busca com consulta vazia que devolve todos os documentos. Depois lê o corpo de cada documento em markdown, uma requisição por documento. O custo de uma execução é, portanto, uma requisição para os spaces, uma por space e uma por documento. Num teste com 250 documentos, a leitura completa levou cerca de 100 segundos. **Paginação.** A busca do Archbee não tem paginação e devolve o space inteiro de uma vez. O Archbee limita um space a 1.000 documentos. Se a busca devolve exatamente 1.000, o conector considera que o fim da lista não pode ser provado e não remove nada desse space. **Escrita.** A tabela `docs` é mesclada pelo `id`: cada execução atualiza as linhas que leu. O corpo não é gravado nela e vai só para o Knowledge, onde uma edição troca o conteúdo antigo pelo novo, sem duplicar o documento. **Documento apagado entre a listagem e a leitura.** Se o Archbee responde que o documento não existe na hora de ler o corpo, o conector o ignora nessa execução. **Falha em um space.** Se a listagem ou a leitura de um space falha depois das tentativas do conector, por exemplo por chave revogada ou erro do Archbee, esse space é marcado como não coberto e os outros seguem. Uma falha de acesso (401 ou 403) na leitura do corpo encerra a leitura daquele space. **Remoção.** Um documento apagado no Archbee só sai do Knowledge numa execução completa que listou o space inteiro sem falha: a verificação diária da Janela de manutenção, às 03:00 por padrão, ou uma **Sincronização completa** pedida por você. Ver [Atualização e remoção de documentos](https://docs.strattum.ai/data-pipelines/document-updates.md). A linha do documento continua na tabela `docs`. **Proteção contra remoção em massa.** Se uma execução completa mostra que um space perdeu mais da metade dos documentos que a Strattum tinha registrado, o conector não remove nada e registra o aviso `mass_removal_blocked` no resumo da execução. A redução só é aceita quando a execução completa seguinte lista o mesmo inventário reduzido. Não há botão para liberar a remoção antes disso. **Space desmarcado.** Quando você tira um space da seleção no Data Catalog, a Strattum mostra quantas páginas saem, e depois de confirmar com **Remover agora** elas saem do lake. O Knowledge recebe a remoção desses documentos na próxima execução. Se você desmarcar o último space, a próxima execução só publica essas remoções e depois o conector volta a aguardar uma seleção. ## API da fonte | Método e caminho | Usado para | Recurso | | - | - | - | | `GET /api/public-api/space-group/list` | Listar os spaces do time, no teste de conexão, no seletor de spaces e em toda execução | `docs` | | `POST /api/public-api/docs/search` | Listar os documentos de um space, com `query` vazia e `type` igual a `words` | `docs` | | `GET /api/public-api/doc` | Ler o corpo de um documento em markdown, com `docId` e `format` igual a `markdown` | `docs` | Todas as chamadas vão para `https://api.archbee.com`, e o conector nunca segue redirecionamentos, para que a chave não saia para outro endereço. **Rate limits.** O Archbee não publica um limite de requisições na documentação. Nas respostas, ele envia os cabeçalhos `x-ratelimit-limit`, `x-ratelimit-remaining` e `x-ratelimit-reset`. Numa medição de 26/10/2026, o valor foi 100 e a janela se renovou em cerca de 1 segundo, o que é uma observação e não uma garantia do vendor. O conector lê esses cabeçalhos: quando `x-ratelimit-remaining` chega a 0, ele espera até o horário de `x-ratelimit-reset`, por no máximo 10 segundos. Diante de um 429, ele respeita o cabeçalho `Retry-After` e tenta de novo até 5 vezes, com espera máxima de 300 segundos por tentativa e 900 segundos no total por requisição. Cada requisição tem tempo limite de 60 segundos. Se o 429 persiste, o space é marcado como não coberto e os demais seguem. Referência oficial: [Archbee, Search document](https://www.archbee.com/docs/search-document.md), [Get document](https://www.archbee.com/docs/get-document.md) e [List space groups and spaces](https://www.archbee.com/docs/list-space-groups-and-spaces.md). ## Limitações conhecidas * Não há sincronização incremental. Cada execução lista os spaces escolhidos e lê o corpo de todos os documentos, então o custo cresce com o tamanho dos spaces, e uma mudança só chega ao Knowledge na execução seguinte. * As categorias do Archbee não chegam ao Knowledge como pastas. O conector não envia o caminho do documento, então os documentos aparecem sem a hierarquia de categorias, e o documento pai fica só como metadado em `docs`. * A permissão não é por documento. Documentos `private`, `shared with team` e `hidden` entram e ficam visíveis para quem pode usar o conector e o contexto do Knowledge. * A tabela `docs` não traz autor, nem de criação nem da última edição. O conector descarta esses dados e também o token de link compartilhável de cada documento. * A remoção por ausência só acontece em execução completa, e a proteção contra remoção em massa segura reduções de mais de 50% de um space até uma segunda execução completa confirmar a redução. * O Archbee limita um space a 1.000 documentos. Um space com exatamente esse número nunca conta como lido por inteiro, e nada dele é removido por ausência. * A API do Archbee exige um plano pago com o complemento **API Access**. O Archbee não confirma esse requisito numa página pública de preços, e a informação vem do texto do próprio produto. * O conector lê só markdown de documentos. Um documento sem texto depois do bloco de metadados é ignorado e aparece como "Sem conteúdo indexável". ## Troubleshooting | Mensagem ou sintoma | Causa | O que fazer | | - | - | - | | Informe a chave de API antes de testar | O campo **API Key** está vazio. | Cole a chave de time e teste de novo. | | A chave de API do Archbee é obrigatória. | A chave chegou vazia ao teste. | Gere a chave em **Settings → Developer** e cole-a no campo. | | Chave de API do Archbee inválida. | O Archbee respondeu 401: a chave está errada ou foi revogada. | Gere uma nova chave de time, cole-a sem espaços e confira que ela não foi revogada. | | A chave não é uma chave de time do Archbee. | O Archbee respondeu 403: é uma chave de space, ou falta o complemento **API Access**. | Use uma chave de time (`abteam_`, somente leitura) de **Settings → Developer** e confira o complemento no plano. | | O plano do Archbee não inclui acesso à API. | O Archbee respondeu 402. | Peça ao admin do time para contratar o complemento "API Access" e teste de novo. | | Não foi possível contatar o Archbee. | Falha de rede ou resposta inesperada do Archbee. | Verifique a conectividade com `api.archbee.com` e tente de novo em instantes. | | O conector não sincroniza e fica aguardando configuração. | Nenhum space foi selecionado no Data Catalog. | Abra o conector no Data Catalog, marque os spaces em **Espaços no contexto** e salve a seleção. | | A execução registra `mass_removal_blocked`. | Um space perdeu mais da metade dos documentos conhecidos, e o conector segurou a remoção. | Confira se a redução é real. A próxima execução completa que listar o mesmo inventário aceita a redução. | | Um space aparece como não coberto no resumo da execução. | A listagem ou a leitura do space falhou, ou a chave deixou de listar o space. | Teste a conexão na edição do conector e confira se a chave ainda lê o space no Archbee. | ## Próximos passos > **[Data Catalog](https://docs.strattum.ai/data-catalog/overview.md)** > > Escolha os spaces do Archbee que entram no contexto. > **[Knowledge](https://docs.strattum.ai/knowledge/overview.md)** > > Veja como os documentos do Archbee são indexados e buscados. > **Desenvolvimento local** > > O conector não lê credenciais de variáveis de ambiente. A chave é gravada por conexão, quando você cria a conexão no Console, com a chave `ARCHBEE_API_KEY`, e os spaces escolhidos ficam em `space_ids`, gravados pelo Data Catalog. Para testar localmente, suba o ambiente pelo [guia de desenvolvimento local](https://docs.strattum.ai/data-pipelines/local-development.md) e crie a conexão pelo Console desse ambiente. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.