Jamdesk Documentation logo

API de busca de documentação

Pesquise sua documentação Jamdesk programaticamente. Alimente chatbots, bots do Slack, buscas personalizadas e agentes de IA com respostas atualizadas.

A API de busca de documentação oferece acesso programático ao conteúdo da sua documentação por meio de busca semântica. Um único endpoint (POST /_api/search) recebe uma consulta em linguagem natural e retorna os trechos mais relevantes da sua documentação, ordenados por relevância.

Casos de uso

Chatbots de suporte

Conecte o Intercom Fin, o Zendesk AI ou um chatbot personalizado à sua documentação. O bot responde às perguntas com conteúdo citado.

Bots do Slack

Crie um comando /docs no Slack que pesquisa na sua documentação e publica os principais resultados em qualquer canal.

Busca personalizada

Adicione uma interface de busca ao seu produto, painel ou ferramentas internas que exibe documentação relevante no contexto.

Agentes de IA

Dê a agentes de IA como Claude ou GPT uma ferramenta que recupera sua documentação atual, em vez de depender dos dados de treinamento.

Início rápido

1
Gere uma chave de API

Acesse Project Settings → API Keys no painel Jamdesk. Clique em Generate Key, dê um nome à chave e copie-a. Ela começa com jd_live_ seguido de 32 caracteres hexadecimais (40 caracteres no total). Ela é exibida apenas uma vez.

2
Faça sua primeira requisição de busca

Envie uma requisição POST para /_api/search no subdomínio da sua documentação:

curl -X POST https://your-project.jamdesk.app/_api/search \
  -H "Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I set up a custom domain?", "limit": 5, "language": "en"}'
3
Use os resultados

A resposta retorna uma matriz de trechos correspondentes com pontuações de relevância e metadados da página:

{
  "query": "How do I set up a custom domain?",
  "language": "en",
  "results": [
    {
      "title": "Custom Domains",
      "section": "Step 4: Deploy",
      "slug": "deploy/custom-domains",
      "content": "To add a custom domain, go to Project Settings and enter your domain. You'll need to add a CNAME record pointing to your Jamdesk subdomain.",
      "url": "https://your-project.jamdesk.app/deploy/custom-domains",
      "score": 0.94
    }
  ],
  "total": 1,
  "durationMs": 85
}

Autenticação

Todas as requisições exigem um token Bearer no cabeçalho Authorization.

Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a

A API de busca funciona em sites com autenticação por senha ou JWT. Ela verifica sua chave de API, não o login de um visitante. Você não precisa adicionar /_api/search a auth.jwt.public. Os resultados podem incluir páginas protegidas por login. Chame a API a partir do seu servidor e nunca coloque a chave em código do navegador. Os resultados seguem as mesmas regras da busca do site: páginas restritas a grupos nunca são retornadas. Páginas ocultas e páginas com search: false ficam de fora, a menos que você as tenha tornado pesquisáveis.

A mesma chave também libera o servidor MCP, as URLs de página .md e o llms.txt e llms-full.txt nesses sites.

Gerar chaves de API

1
Abra as configurações do projeto

No painel Jamdesk, acesse seu projeto e clique em Settings.

2
Acesse API Keys

Selecione a aba API Keys.

3
Crie uma chave

Clique em Generate Key, insira um nome descritivo (por exemplo, "Chatbot Intercom") e clique em Create.

4
Copie a chave

Copie a chave imediatamente. Ela começa com jd_live_ seguido de 32 caracteres hexadecimais. É exibida apenas uma vez. Armazene-a no seu gerenciador de segredos ou em variáveis de ambiente.

Gerenciamento de chaves

As chaves de API são limitadas a um projeto. Uma chave para acme.jamdesk.app não pode consultar a documentação de outro projeto.

RegraDetalhe
Formatojd_live_<32 caracteres hex> (40 caracteres no total, não expira)
EscopoUma chave por projeto (não acessa outros projetos)
RotaçãoRevogue e gere uma nova a qualquer momento nas configurações do projeto
ArmazenamentoGuarde em variáveis de ambiente ou em um gerenciador de segredos; nunca faça commit no controle de versão

Revogar chaves

Acesse Project Settings → API Keys, encontre a chave pelo nome e clique em Revoke. Chaves revogadas deixam de funcionar imediatamente. Gere uma nova chave para substituí-la.

Limites de requisições

As requisições são limitadas por chave de API.

PlanoLimite
Pro60 requisições / minuto
EnterprisePersonalizado; entre em contato com o suporte

Em um site protegido por login, requisições MCP, .md e llms.txt feitas com a mesma chave compartilham um limite separado de 120 requisições por minuto. Elas não contam para o limite da API de busca, e as requisições da API de busca não contam para o limite delas.

Ao exceder o limite, a API retorna 429 Too Many Requests com o cabeçalho Retry-After: 60 e {"error": "Rate limit exceeded"} no corpo.

Entre em contato conosco sobre as opções Enterprise para limites de taxa mais altos em uma integração de produção.

Limites de consulta

Cada requisição aceita um parâmetro limit que controla quantos resultados retornar. O máximo é 20, o padrão é 5 e o mínimo é 1. Não há paginação. Todos os resultados correspondentes são retornados em uma única resposta. Para obter mais contexto, tente uma consulta mais específica em vez de um limite maior.

Uma consulta sem correspondências retorna HTTP 200 com uma matriz de resultados vazia:

{"query": "quantum entanglement", "results": [], "total": 0, "durationMs": 48}

Filtrar por linguagem

Em um site multilíngue, a API filtra os resultados para um idioma por requisição. Passe language no corpo da requisição com um código BCP-47 (por exemplo, en, es, fr, pt-BR, zh-Hans).

curl -X POST https://your-project.jamdesk.app/_api/search \
  -H "Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a" \
  -H "Content-Type: application/json" \
  -d '{"query": "¿Cómo configuro un dominio personalizado?", "language": "es"}'
RegraDetalhe
Padrãoen (inglês). Omita o campo, ou passe null, para usar o padrão.
FormatoBCP-47 (^[a-zA-Z]{2,3}([-_][a-zA-Z]{2,4})?$). Exemplos: en, es, fr, pt-BR, zh-Hans.
ValidaçãoValores malformados retornam 400 com {"error": "Invalid language code"}.
Tags de 3 segmentosAtualmente não suportadas. Códigos como zh-Hant-HK e sr-Latn-RS retornam 400. Entre em contato com o suporte se precisar delas.
Projetos multilínguesO filtro é estrito: somente trechos marcados com o idioma solicitado são retornados. Uma requisição para de em um projeto que só tem inglês e francês retorna um conjunto de resultados vazio, não um 400.
Projetos de idioma únicoO filtro é ignorado. Você sempre recebe o conjunto completo de resultados. Enviar language não causa erro.
Ecoado na respostaToda resposta bem-sucedida inclui um campo language com o valor que o servidor resolveu (valor da requisição ou o padrão en).

Um projeto é multilíngue quando seu docs.json tem um array navigation.languages com duas ou mais entradas. Verifique a aba Settings → Languages no painel, ou o docs.json, para ver se seu site é multilíngue.

O padrão en se aplica mesmo em projetos que não têm versão em inglês. Um projeto em francês e espanhol chamado sem um campo language filtra por en e retorna um conjunto de resultados vazio. Sempre passe um language explícito em sites sem inglês.

Tratamento de erros

Todas as respostas de erro incluem um campo error legível por máquina que você pode usar programaticamente.

StatusValor de errorSignificadoAção
400Missing or empty "query" fieldO corpo da requisição não tem query ou está vazioAdicione uma string query não vazia
400Invalid language codeO campo language não é uma string ou não corresponde ao padrão BCP-47 (null é aceito; strings vazias ou com espaços e tags de 3 segmentos não)Use um código válido de 1 ou 2 segmentos, como en, es, fr ou pt-BR
401invalid_key_formatO cabeçalho Authorization está ausente ou a chave não corresponde a jd_live_<32 hex>Verifique o formato do cabeçalho; deve ser Bearer jd_live_...
401invalid_keyA chave não é reconhecida ou foi revogadaGere uma nova chave no painel
403wrong_projectA chave é válida, mas foi gerada para outro projetoUse uma chave que corresponda ao slug do projeto na URL
429Rate limit exceededExcedeu 60 requisições por minutoAguarde o número de segundos indicado no cabeçalho Retry-After
502Search temporarily unavailableO backend de busca vetorial está indisponívelTente novamente após um breve intervalo
503lookup_failed ou redis_unavailableO backend de verificação de chaves está inacessívelTente novamente após um breve intervalo

401 e 403 são falhas permanentes. Tentar novamente com a mesma chave não ajuda. 429, 502 e 503 são transitórias. Tente novamente com backoff exponencial.

CORS

O CORS está habilitado em todos os endpoints. Clientes baseados em navegador (aplicações de página única, extensões de navegador, sites estáticos) podem chamar /_api/search diretamente, sem um proxy de backend. Todas as origens são permitidas.

SDKs

No momento não há SDKs oficiais para linguagens. Use a API REST diretamente via fetch, requests, curl ou qualquer cliente HTTP. A coleção do Postman abaixo oferece exemplos prontos para fazer fork.

Versionamento

A API está atualmente na v1.0.0. Mudanças incompatíveis (renomeação de campos, endpoints removidos, autenticação alterada) serão anunciadas no blog da Jamdesk e em um aviso de descontinuação no cabeçalho de resposta X-Deprecation, com pelo menos 90 dias de antecedência antes da remoção.

Especificação OpenAPI

A especificação OpenAPI 3.1 completa está disponível em YAML. Importe-a na sua ferramenta de codegen, cliente de API ou pipeline de testes de contrato.

Baixar OpenAPI YAML

docs-search-api.yaml (OpenAPI 3.1, sempre sincronizado com a versão publicada mais recente).

Ver no GitHub

Leia o código-fonte da especificação, abra issues ou acompanhe as mudanças.

Coleção do Postman

Publicamos um workspace oficial do Postman com a especificação OpenAPI completa e uma coleção pronta para fork. Teste requisições na interface do Postman sem escrever código.

Workspace da API de documentação Jamdesk

Faça fork da coleção e execute requisições no Postman. Inclui uma pasta de Primeiros passos e exemplos funcionais.

Todas as APIs Jamdesk

Navegue por todos os workspaces públicos de API da Jamdesk e fique por dentro de novas APIs.

Atualize duas variáveis da coleção na cópia que você criou. Nenhuma requisição funciona até que você faça isso:

  • baseUrl: defina como o site de documentação Jamdesk. Geralmente é https://your-project.jamdesk.app (substitua your-project pelo slug do seu projeto). Em um domínio personalizado, use seu próprio host. Para documentação em um subcaminho, inclua o caminho completo (por exemplo, https://example.com/docs).
  • apiKey: substitua o marcador de posição por uma chave real gerada em Dashboard → Project Settings → API Keys.

Próximas etapas

Endpoint de busca

Referência completa com esquemas de requisição/resposta e playground interativo

Guias de integração

Guias passo a passo para Intercom, Zendesk, bots do Slack e chatbots personalizados