---
title: API de Búsqueda de Documentación
description: Busca tu documentación de Jamdesk de forma programática. Potencia chatbots, bots de Slack, búsqueda personalizada y agentes de IA con respuestas actualizadas.
---

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

<Columns cols={2}>
  <Card title="Chatbots de soporte" icon="comment-dots">
    Conecta Intercom Fin, Zendesk AI o un chatbot personalizado a tu documentación para que responda preguntas con contenido preciso y citado.
  </Card>
  <Card title="Bots de Slack" icon="slack">
    Crea un comando `/docs` en Slack que busque en tu documentación y publique los mejores resultados en cualquier canal.
  </Card>
  <Card title="Búsqueda personalizada" icon="magnifying-glass">
    Añade una interfaz de búsqueda a tu producto, dashboard o herramientas internas que muestre documentación relevante en contexto.
  </Card>
  <Card title="Agentes de IA" icon="robot">
    Proporciona a agentes de IA como Claude o GPT una herramienta que recupere documentación actualizada, no datos de entrenamiento obsoletos.
  </Card>
</Columns>

## Inicio rápido

<Steps>
  <Step title="Genera una clave API">
    Ve a **Configuración del proyecto → Claves API** en el [Jamdesk dashboard](https://dashboard.jamdesk.com). Haz clic en **Generar clave**, dale un nombre y cópiala. Comienza con `jd_live_` seguido de 32 caracteres hexadecimales (40 caracteres en total) y se muestra una sola vez.
  </Step>
  <Step title="Realiza tu primera solicitud de búsqueda">
    Envía una solicitud `POST` a `/_api/search` en el subdominio de tu documentación:

    ```bash
    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"}'
    ```
  </Step>
  <Step title="Usa los resultados">
    La respuesta devuelve un array de fragmentos coincidentes con puntuaciones de relevancia y metadatos de la página:

    ```json
    {
      "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
    }
    ```
  </Step>
</Steps>

## Autenticación

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

```http
Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a
```

### Generación de claves API

<Steps>
  <Step title="Abre la configuración del proyecto">
    En el Jamdesk dashboard, navega a tu proyecto y haz clic en **Configuración**.
  </Step>
  <Step title="Ve a Claves API">
    Selecciona la pestaña **Claves API**.
  </Step>
  <Step title="Crea una clave">
    Haz clic en **Generar clave**, introduce un nombre descriptivo (p. ej., "chatbot de Intercom") y haz clic en **Crear**.
  </Step>
  <Step title="Copia la clave">
    Copia la clave de inmediato. Empieza con `jd_live_` seguido de 32 caracteres hexadecimales y se muestra **solo una vez**. Guárdala en tu gestor de secretos o en variables de entorno.
  </Step>
</Steps>

### Gestión de claves

<Info>
Las claves de API están limitadas a un único proyecto. Una clave para `acme.jamdesk.app` no puede consultar la documentación de un proyecto diferente.
</Info>

| Regla | Detalle |
|------|--------|
| **Formato** | `jd_live_<32 caracteres hex>` (40 caracteres en total, sin caducidad) |
| **Alcance** | Una clave por proyecto (no puede acceder a otros proyectos) |
| **Rotación** | Revocar y regenerar en cualquier momento desde la Configuración del proyecto |
| **Almacenamiento** | Guarda en variables de entorno o en un gestor de secretos; nunca confirmes en el control de versiones |

### 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.

| Plan | Límite |
|------|-------|
| **Pro** | 60 solicitudes / minuto |
| **Enterprise** | Personalizado; contacta con [soporte](mailto:support@jamdesk.com) |

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.

<Warning>
Si necesitas límites de velocidad más altos para una integración en producción, [contáctanos](mailto:support@jamdesk.com) para hablar sobre las opciones Enterprise.
</Warning>

## 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:

```json
{"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`).

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

| Regla | Detalle |
|-------|---------|
| **Por defecto** | `en` (inglés). Omite el campo, o pasa `null`, para usar el valor predeterminado. |
| **Formato** | BCP-47 (`^[a-zA-Z]{2,3}([-_][a-zA-Z]{2,4})?$`). Ejemplos: `en`, `es`, `fr`, `pt-BR`, `zh-Hans`. |
| **Validación** | Un valor mal formado devuelve `400` con `{"error": "Invalid language code"}`. |
| **Códigos de 3 segmentos** | No compatibles actualmente. Códigos como `zh-Hant-HK` o `sr-Latn-RS` devuelven `400`. [Contacta con soporte](mailto:support@jamdesk.com) si los necesitas. |
| **Proyectos multilingües** | El filtro es estricto — solo se devuelven los pasajes etiquetados con el idioma solicitado. Una solicitud para `de` en un proyecto que solo tiene inglés y francés devuelve un conjunto vacío, no un `400`. |
| **Proyectos monolingües** | El filtro se ignora; siempre obtienes el conjunto completo de resultados. Enviar `language` no es un error, es un no-op. |
| **Devuelto en la respuesta** | Cada respuesta correcta incluye un campo `language` con el valor resuelto por el servidor (valor de la solicitud, o `en` por defecto). |

<Info>
Un proyecto es multilingüe cuando su `docs.json` tiene un arreglo `navigation.languages` con dos o más entradas. Para comprobarlo, abre la pestaña **Settings → Languages** del dashboard, o revisa `docs.json` directamente.
</Info>

<Warning>
La opción predeterminada «inglés» se aplica incluso si tu proyecto no tiene versión en inglés. Si tu proyecto multilingüe es, por ejemplo, solo francés y español, llamar al endpoint sin `language` filtrará por `en` y devolverá un resultado vacío. Pasa siempre un `language` explícito desde sitios sin versión en inglés.
</Warning>

## Manejo de errores

Todas las respuestas de error incluyen un campo `error` legible por máquina sobre el que puedes ramificar programáticamente.

| Estado | Valor de `error` | Significado | Acción |
|--------|---------------|---------|--------|
| **400** | `Missing or empty "query" field` | El cuerpo de la solicitud falta o no tiene `query` | Añade una cadena `query` no vacía |
| **400** | `Invalid language code` | El campo `language` no es una cadena o no coincide con el patrón BCP-47 (`null` se acepta; cadenas vacías/en blanco y códigos de 3 segmentos no) | Use un código de 1 o 2 segmentos válido como `en`, `es`, `fr` o `pt-BR` |
| **401** | `invalid_key_format` | El encabezado `Authorization` falta o la clave no coincide con `jd_live_<32 hex>` | Comprueba el formato del encabezado; debe ser `Bearer jd_live_...` |
| **401** | `invalid_key` | La clave no se reconoce o ha sido revocada | Genera una nueva clave en el dashboard |
| **403** | `wrong_project` | La clave es válida pero fue generada para un proyecto diferente | Usa una clave que coincida con el slug del proyecto en la URL |
| **429** | `Rate limit exceeded` | Se superaron 60 solicitudes por minuto | Espera el número de segundos indicado en el encabezado `Retry-After` |
| **502** | `Search temporarily unavailable` | El backend de búsqueda vectorial está caído | Reintenta después de un breve retroceso |
| **503** | `lookup_failed` o `redis_unavailable` | El backend de verificación de claves no está disponible | Reintenta después de un breve retroceso |

<Info>
401 y 403 son fallos permanentes. Reintentar con la misma clave no servirá de nada. 429, 502 y 503 son transitorios, así que reintenta con retroceso exponencial.
</Info>

## 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](#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](https://www.jamdesk.com/blog) 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.

<Columns cols={2}>
  <Card title="Descargar YAML de OpenAPI" icon="file-arrow-down" href="https://raw.githubusercontent.com/jamdesk/jamdesk-docs/main/openapi/docs-search-api.yaml">
    `docs-search-api.yaml` — OpenAPI 3.1, siempre sincronizado con la última versión publicada.
  </Card>
  <Card title="Ver en GitHub" icon="github" href="https://github.com/jamdesk/jamdesk-docs/blob/main/openapi/docs-search-api.yaml">
    Lee el código fuente de la especificación, reporta incidencias o sigue los cambios.
  </Card>
</Columns>

## 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.

<Columns cols={2}>
  <Card title="Workspace de la API de Docs de Jamdesk" icon="rocket" href="https://www.postman.com/jamdesk/jamdesk-docs-api">
    Bifurca la colección y ejecuta solicitudes en Postman. Incluye una carpeta de inicio y ejemplos funcionales.
  </Card>
  <Card title="Todas las APIs de Jamdesk" icon="layer-group" href="https://www.postman.com/jamdesk">
    Explora todos los workspaces públicos de la API de Jamdesk y mantente al día a medida que se publican nuevas APIs.
  </Card>
</Columns>

<Warning>
Después de bifurcar la colección, **debes** actualizar dos variables de colección antes de que cualquier solicitud funcione:

- **`baseUrl`**: establécela en tu propio sitio de documentación de Jamdesk. Para la mayoría de los clientes es `https://your-project.jamdesk.app` (reemplaza `your-project` con el slug de tu proyecto). Los clientes con dominio personalizado usan su propio host. Los clientes que sirven documentación en una subruta incluyen la ruta completa (p. ej., `https://example.com/docs`).
- **`apiKey`**: reemplaza el marcador de posición con una clave real generada en **Dashboard → Configuración del proyecto → Claves API**.
</Warning>

## Próximos pasos

<Columns cols={2}>
  <Card title="Endpoint de búsqueda" icon="magnifying-glass" href="/es/jamdesk-api/search">
    Referencia completa con esquemas de solicitud/respuesta y playground interactivo
  </Card>
  <Card title="Guías de integración" icon="plug" href="/es/jamdesk-api/integrations">
    Guías paso a paso para Intercom, Zendesk, bots de Slack y chatbots personalizados
  </Card>
</Columns>