API de Búsqueda de Documentación

La API de Búsqueda de Docs 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 fragmentos 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

Generación de claves API

Gestión de claves

Revocación de claves

Para revocar una clave, ve a Configuración del proyecto → Claves API, encuentra la clave por nombre y haz clic en Revocar. Las claves revocadas dejan de funcionar de inmediato. Genera una nueva clave para reemplazarla.

Límites de velocidad

Las solicitudes tienen límites de velocidad 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 se devuelven en una única 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. Indica language en el cuerpo de la solicitud con un código BCP-47 (por ejemplo 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 programáticamente.

CORS

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

SDKs

Actualmente no hay SDKs de lenguaje oficiales. Usa la API REST directamente mediante fetch, requests, curl o cualquier cliente HTTP. La colección de Postman a continuación proporciona ejemplos listos para bifurcar.

Versionado

La API está actualmente en v1.0.0. Los cambios que rompan la compatibilidad (renombrado de campos, endpoints eliminados, cambios en la autenticación) se anunciarán a través del blog de Jamdesk y 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 completa OpenAPI 3.1 está disponible en YAML. Impórtala en tu herramienta de generación de código, cliente de API o pipeline de pruebas de contratos.

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 ningún código.

Próximos pasos