Docs Search API

La Docs Search API 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 tus docs, 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 de API

Gestión de Claves

Revocación de Claves

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

Límites de Velocidad

Las solicitudes tienen límite 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 sola respuesta. Si necesitas más contexto, prueba 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 docs admite varios idiomas, la API filtra los resultados a un único 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 programáticamente.

CORS

CORS está habilitado en todos los endpoints. Los clientes basados en 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 oficiales para ningún lenguaje. Usa la REST API directamente mediante fetch, requests, curl o cualquier cliente HTTP. La colección de Postman que se muestra a continuación ofrece ejemplos listos para clonar.

Versionado

La API se encuentra actualmente en v1.0.0. Los cambios incompatibles (renombrado de campos, endpoints eliminados, cambios de 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 contrato.

Colección de Postman

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

Próximos Pasos