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
Início rápido
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.
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"}'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
No painel Jamdesk, acesse seu projeto e clique em Settings.
Selecione a aba API Keys.
Clique em Generate Key, insira um nome descritivo (por exemplo, "Chatbot Intercom") e clique em Create.
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.
| Regra | Detalhe |
|---|---|
| Formato | jd_live_<32 caracteres hex> (40 caracteres no total, não expira) |
| Escopo | Uma chave por projeto (não acessa outros projetos) |
| Rotação | Revogue e gere uma nova a qualquer momento nas configurações do projeto |
| Armazenamento | Guarde 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.
| Plano | Limite |
|---|---|
| Pro | 60 requisições / minuto |
| Enterprise | Personalizado; 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"}'
| Regra | Detalhe |
|---|---|
| Padrão | en (inglês). Omita o campo, ou passe null, para usar o padrão. |
| Formato | BCP-47 (^[a-zA-Z]{2,3}([-_][a-zA-Z]{2,4})?$). Exemplos: en, es, fr, pt-BR, zh-Hans. |
| Validação | Valores malformados retornam 400 com {"error": "Invalid language code"}. |
| Tags de 3 segmentos | Atualmente 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íngues | O 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 único | O filtro é ignorado. Você sempre recebe o conjunto completo de resultados. Enviar language não causa erro. |
| Ecoado na resposta | Toda 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.
| Status | Valor de error | Significado | Ação |
|---|---|---|---|
| 400 | Missing or empty "query" field | O corpo da requisição não tem query ou está vazio | Adicione uma string query não vazia |
| 400 | Invalid language code | O 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 |
| 401 | invalid_key_format | O 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_... |
| 401 | invalid_key | A chave não é reconhecida ou foi revogada | Gere uma nova chave no painel |
| 403 | wrong_project | A chave é válida, mas foi gerada para outro projeto | Use uma chave que corresponda ao slug do projeto na URL |
| 429 | Rate limit exceeded | Excedeu 60 requisições por minuto | Aguarde o número de segundos indicado no cabeçalho Retry-After |
| 502 | Search temporarily unavailable | O backend de busca vetorial está indisponível | Tente novamente após um breve intervalo |
| 503 | lookup_failed ou redis_unavailable | O backend de verificação de chaves está inacessível | Tente 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.
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.
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(substituayour-projectpelo 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.
