API de búsqueda de documentación

La API de búsqueda de documentación te da acceso programático al contenido de tu documentación mediante búsqueda semántica. Un endpoint (POST /_api/search) recibe una consulta en lenguaje natural y devuelve los pasajes más relevantes de tu documentación, ordenados por relevancia.

Casos de uso

Inicio 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
}

Autenticación

Todas las solicitudes requieren un token Bearer en el encabezado Authorization.

Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a

Generar claves de API

Gestión de claves

Revocar claves

Para revocar una clave, ve a Project Settings → API Keys, busca la clave por nombre y haz clic en Revoke. Las claves revocadas dejan de funcionar de inmediato. Genera una clave nueva para reemplazarla.

Límites de tasa

Las solicitudes tienen un límite de frecuencia por clave de API.

Cuando superas el límite, la API devuelve 429 Too Many Requests con un encabezado Retry-After: 60 y {"error": "Rate limit exceeded"} en el cuerpo.

Límites de consulta

Cada solicitud acepta un parámetro limit que controla cuántos resultados devolver. El máximo es 20, el valor predeterminado es 5 y el mínimo es 1. No hay paginación; todos los resultados coincidentes llegan en una sola respuesta. Si necesitas más contexto, prueba con una consulta más específica en lugar de aumentar el límite.

Una consulta sin coincidencias devuelve HTTP 200 con un array de resultados vacío:

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

Filtrado por idioma

Si tu sitio de documentación admite varios idiomas, la API filtra los resultados a un solo idioma por solicitud. Pasa language en el cuerpo de la solicitud con un código BCP-47 (p. ej. 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"}'

Manejo de errores

Todas las respuestas de error incluyen un campo error legible por máquina sobre el que puedes ramificar la lógica de tu programa.

CORS

CORS está habilitado en todos los endpoints. Los clientes basados en navegador (aplicaciones de una sola página, extensiones de navegador, sitios estáticos) pueden llamar a /_api/search directamente sin un proxy backend. Se permiten todos los orígenes.

SDKs

No hay SDKs oficiales de lenguaje por el momento. Usa la API REST directamente mediante fetch, requests, curl o cualquier cliente HTTP. La colección de Postman a continuación ofrece ejemplos listos para bifurcar.

Versionado

La API está actualmente en la versión v1.0.0. Los cambios incompatibles (renombrado de campos, endpoints eliminados, cambios de autenticación) se anunciarán en el blog de Jamdesk y mediante un aviso de obsolescencia en el encabezado de respuesta X-Deprecation al menos 90 días antes de su eliminación.

Especificación OpenAPI

La especificación OpenAPI 3.1 completa está disponible en YAML. Impórtala en tu herramienta de generación de código, cliente de API o pipeline de pruebas de contrato.

Colección de Postman

Publicamos un workspace oficial de Postman con la especificación OpenAPI completa y una colección lista para bifurcar para que puedas probar solicitudes en la interfaz de Postman sin escribir código.

Próximos pasos