API de pesquisa de docs

A API de pesquisa de docs oferece acesso programático ao conteúdo da sua documentação por meio de pesquisa semântica. Um endpoint (POST /_api/search) recebe uma consulta em linguagem natural e retorna as passagens mais relevantes dos seus docs, classificadas por relevância.

Casos de uso

Início rápido

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

{
  "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 solicitações exigem um token Bearer no cabeçalho Authorization.

Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a

Gerar chaves de API

Gerenciamento de chaves

Revogar chaves

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

Limites de requisições

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

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

Limites de consulta

Cada solicitação aceita um parâmetro limit que controla quantos resultados serão retornados. 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. Se precisar de mais contexto, tente fazer uma consulta mais específica em vez de aumentar o limite.

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

Se o site dos seus docs for compatível com vários idiomas, a API filtrará os resultados para um único idioma por solicitação. Envie language no corpo da solicitaçã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"}'

Tratamento de erros

Todas as respostas de erro incluem um campo error legível por máquina, que pode ser usado para ramificar o fluxo programaticamente.

CORS

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

SDKs

Atualmente, não há SDKs oficiais de linguagem. Use a REST API diretamente por meio de fetch, requests, curl ou qualquer cliente HTTP. A coleção do Postman abaixo fornece exemplos prontos para bifurcar.

Versionamento

A API está atualmente na versão v1.0.0. Alterações incompatíveis (renomeação de campos, remoção de endpoints ou mudanças na autenticação) serão anunciadas pelo blog do Jamdesk e por um aviso de descontinuação no cabeçalho de resposta X-Deprecation pelo menos 90 dias antes da remoção.

Especificação OpenAPI

A especificação completa da OpenAPI 3.1 está disponível como YAML. Importe-a na sua ferramenta de geração de código, cliente de API ou pipeline de testes de contrato.

Coleção do Postman

Publicamos um workspace oficial do Postman com a especificação completa da OpenAPI e uma coleção pronta para bifurcar, para que você possa testar solicitações na interface do Postman sem escrever código.

Próximas etapas