---
title: API de recherche dans les docs
description: Recherchez votre documentation Jamdesk par programmation via un endpoint sémantique. Alimentez chatbots, bots Slack et agents IA avec des réponses à jour.
---

L'API de recherche de documentation vous donne un accès programmatique au contenu de votre documentation via la recherche sémantique. Un seul endpoint (`POST /_api/search`) accepte une requête en langage naturel et retourne les passages les plus pertinents de votre documentation, classés par pertinence.

## Cas d'utilisation

<Columns cols={2}>
  <Card title="Chatbots de support" icon="comment-dots">
    Connectez Intercom Fin, Zendesk AI ou un chatbot personnalisé à votre documentation afin qu'il réponde aux questions avec un contenu précis et cité.
  </Card>
  <Card title="Bots Slack" icon="slack">
    Créez une commande Slack `/docs` qui recherche dans votre documentation et publie les meilleurs résultats dans n'importe quel canal.
  </Card>
  <Card title="Recherche personnalisée" icon="magnifying-glass">
    Ajoutez une interface de recherche à votre produit, dashboard ou outils internes qui affiche les docs pertinentes en contexte.
  </Card>
  <Card title="Agents IA" icon="robot">
    Donnez aux agents IA comme Claude ou GPT un outil qui récupère une documentation à jour, pas des données d'entraînement obsolètes.
  </Card>
</Columns>

## Démarrage rapide

<Steps>
  <Step title="Générer une clé API">
    Accédez à **Paramètres du projet → Clés API** dans le [dashboard Jamdesk](https://dashboard.jamdesk.com). Cliquez sur **Générer une clé**, donnez-lui un nom et copiez la clé. Elle commence par `jd_live_` suivi de 32 caractères hexadécimaux (40 caractères au total) et n'est affichée qu'une seule fois.
  </Step>
  <Step title="Effectuer votre première requête de recherche">
    Envoyez une requête `POST` à `/_api/search` sur le sous-domaine de votre documentation :

    ```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="Utiliser les résultats">
    La réponse retourne un tableau de passages correspondants avec des scores de pertinence et des métadonnées de page :

    ```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>

## Authentification

Toutes les requêtes nécessitent un token Bearer dans l'en-tête `Authorization`.

```http
Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a
```

### Génération des clés API

<Steps>
  <Step title="Ouvrir les paramètres du projet">
    Dans le dashboard Jamdesk, accédez à votre projet et cliquez sur **Paramètres**.
  </Step>
  <Step title="Accéder aux clés API">
    Sélectionnez l'onglet **Clés API**.
  </Step>
  <Step title="Créer une clé">
    Cliquez sur **Générer une clé**, saisissez un nom descriptif (ex. : "Chatbot Intercom") et cliquez sur **Créer**.
  </Step>
  <Step title="Copier la clé">
    Copiez la clé immédiatement. Elle commence par `jd_live_` suivi de 32 caractères hexadécimaux et n'est affichée **qu'une seule fois**. Stockez-la dans votre gestionnaire de secrets ou vos variables d'environnement.
  </Step>
</Steps>

### Gestion des clés

<Info>
Les clés API sont limitées à un seul projet. Une clé pour `acme.jamdesk.app` ne peut pas interroger la documentation d'un autre projet.
</Info>

| Règle | Détail |
|------|--------|
| **Format** | `jd_live_<32 caractères hex>` (40 caractères au total, n'expire jamais) |
| **Périmètre** | Une clé par projet (ne peut pas accéder à d'autres projets) |
| **Rotation** | Révoquez et régénérez à tout moment depuis les paramètres du projet |
| **Stockage** | Stockez dans des variables d'environnement ou un gestionnaire de secrets ; ne jamais valider dans le contrôle de source |

### Révocation des clés

Pour révoquer une clé, accédez à **Paramètres du projet → Clés API**, trouvez la clé par son nom et cliquez sur **Révoquer**. Les clés révoquées cessent de fonctionner immédiatement. Générez une nouvelle clé pour la remplacer.

## Limites de débit

Les requêtes sont limitées par clé API.

| Plan | Limite |
|------|-------|
| **Pro** | 60 requêtes / minute |
| **Enterprise** | Personnalisée ; contactez le [support](mailto:support@jamdesk.com) |

Lorsque vous dépassez la limite, l'API retourne `429 Too Many Requests` avec un en-tête `Retry-After: 60` et `{"error": "Rate limit exceeded"}` dans le corps.

<Warning>
Si vous avez besoin de limites de débit plus élevées pour une intégration en production, [contactez-nous](mailto:support@jamdesk.com) pour discuter des options Enterprise.
</Warning>

## Limites de requête

Chaque requête accepte un paramètre `limit` contrôlant le nombre de résultats à retourner. Le maximum est **20**, la valeur par défaut est **5** et le minimum est **1**. Il n'y a pas de pagination ; tous les résultats correspondants sont retournés dans une seule réponse. Si vous avez besoin de plus de contexte, essayez une requête plus spécifique plutôt qu'augmenter la limite.

Une requête sans correspondance retourne HTTP 200 avec un tableau de résultats vide :

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

## Filtrage par langue

Si votre site de documentation prend en charge plusieurs langues, l'API filtre les résultats pour ne retourner qu'une seule langue par requête. Passez `language` dans le corps de la requête avec un code BCP-47 (par exemple `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"}'
```

| Règle | Détail |
|-------|--------|
| **Par défaut** | `en` (anglais). Omettez le champ, ou passez `null`, pour utiliser la valeur par défaut. |
| **Format** | BCP-47 (`^[a-zA-Z]{2,3}([-_][a-zA-Z]{2,4})?$`). Exemples : `en`, `es`, `fr`, `pt-BR`, `zh-Hans`. |
| **Validation** | Une valeur mal formée retourne `400` avec `{"error": "Invalid language code"}`. |
| **Codes à 3 segments** | Non supportés actuellement. Les codes comme `zh-Hant-HK` ou `sr-Latn-RS` retournent `400`. [Contactez le support](mailto:support@jamdesk.com) si vous en avez besoin. |
| **Projets multilingues** | Le filtre est strict — seuls les passages étiquetés dans la langue demandée sont retournés. Une requête pour `de` sur un projet qui n'a que de l'anglais et du français renvoie une liste vide, pas un `400`. |
| **Projets monolingues** | Le filtre est ignoré ; vous obtenez toujours l'ensemble complet des résultats. Envoyer `language` est sans effet, pas une erreur. |
| **Renvoyé dans la réponse** | Chaque réponse réussie inclut un champ `language` avec la valeur résolue par le serveur (valeur de la requête, ou `en` par défaut). |

<Info>
Un projet est multilingue lorsque son `docs.json` contient un tableau `navigation.languages` avec deux entrées ou plus. Pour vérifier, ouvrez l'onglet **Settings → Languages** dans le dashboard, ou consultez `docs.json` directement.
</Info>

<Warning>
La valeur par défaut « anglais » s'applique même si votre projet n'a pas de version anglaise. Si votre projet multilingue est par exemple uniquement français et espagnol, appeler l'endpoint sans `language` filtrera pour `en` et renverra un résultat vide. Passez toujours un `language` explicite depuis des sites sans version anglaise.
</Warning>

## Gestion des erreurs

Toutes les réponses d'erreur incluent un champ `error` lisible par machine sur lequel vous pouvez vous appuyer de façon programmatique.

| Statut | Valeur `error` | Signification | Action |
|--------|---------------|---------|--------|
| **400** | `Missing or empty "query" field` | Le corps de la requête est absent ou ne contient pas de `query` | Ajoutez une chaîne `query` non vide |
| **400** | `Invalid language code` | Le champ `language` n'est pas une chaîne ou ne correspond pas au motif BCP-47 (`null` est accepté ; chaînes vides/blanches et codes à 3 segments non) | Utilisez un code à 1 ou 2 segments valide comme `en`, `es`, `fr` ou `pt-BR` |
| **401** | `invalid_key_format` | L'en-tête `Authorization` est absent ou la clé ne correspond pas à `jd_live_<32 hex>` | Vérifiez le format de l'en-tête ; il doit être `Bearer jd_live_...` |
| **401** | `invalid_key` | La clé n'est pas reconnue ou a été révoquée | Générez une nouvelle clé dans le dashboard |
| **403** | `wrong_project` | La clé est valide mais a été générée pour un autre projet | Utilisez une clé correspondant au slug du projet dans l'URL |
| **429** | `Rate limit exceeded` | Dépassement de 60 requêtes par minute | Attendez le nombre de secondes indiqué dans l'en-tête `Retry-After` |
| **502** | `Search temporarily unavailable` | Le backend de recherche vectorielle est indisponible | Réessayez après un court délai |
| **503** | `lookup_failed` ou `redis_unavailable` | Le backend de vérification des clés est inaccessible | Réessayez après un court délai |

<Info>
Les erreurs 401 et 403 sont des échecs permanents. Réessayer avec la même clé ne servira à rien. Les erreurs 429, 502 et 503 sont transitoires ; réessayez avec un backoff exponentiel.
</Info>

## CORS

Le CORS est activé sur tous les endpoints. Les clients basés sur un navigateur (applications monopage, extensions de navigateur, sites statiques) peuvent appeler `/_api/search` directement sans proxy backend. Toutes les origines sont autorisées.

## SDK

Il n'existe pas de SDK officiels pour les langages à ce stade. Utilisez l'API REST directement via `fetch`, `requests`, `curl` ou tout client HTTP. La [collection Postman](#collection-postman) ci-dessous fournit des exemples prêts à être dupliqués.

## Versionnage

L'API est actuellement à la version **v1.0.0**. Les changements incompatibles (renommages de champs, endpoints supprimés, authentification modifiée) seront annoncés via le [blog Jamdesk](https://www.jamdesk.com/blog) et un avis de dépréciation dans l'en-tête de réponse `X-Deprecation` au moins 90 jours avant la suppression.

## Spécification OpenAPI

La spécification OpenAPI 3.1 complète est disponible en YAML. Importez-la dans votre outil de génération de code, client API ou pipeline de tests de contrat.

<Columns cols={2}>
  <Card title="Télécharger le YAML 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, toujours synchronisé avec la dernière version publiée.
  </Card>
  <Card title="Consulter sur GitHub" icon="github" href="https://github.com/jamdesk/jamdesk-docs/blob/main/openapi/docs-search-api.yaml">
    Lisez la source de la spécification, signalez des problèmes ou surveillez les modifications.
  </Card>
</Columns>

## Collection Postman

Nous publions un espace de travail Postman officiel avec la spécification OpenAPI complète et une collection prête à dupliquer pour tester les requêtes dans l'interface Postman sans écrire de code.

<Columns cols={2}>
  <Card title="Espace de travail Jamdesk Docs API" icon="rocket" href="https://www.postman.com/jamdesk/jamdesk-docs-api">
    Dupliquez la collection et exécutez des requêtes dans Postman. Inclut un dossier de démarrage et des exemples fonctionnels.
  </Card>
  <Card title="Toutes les API Jamdesk" icon="layer-group" href="https://www.postman.com/jamdesk">
    Parcourez tous les espaces de travail Jamdesk API publics et restez informé des nouvelles API publiées.
  </Card>
</Columns>

<Warning>
Après avoir dupliqué la collection, vous **devez** mettre à jour deux variables de collection avant qu'une requête fonctionne :

- **`baseUrl`** : définissez votre propre site de documentation Jamdesk. Pour la plupart des clients, c'est `https://your-project.jamdesk.app` (remplacez `your-project` par votre slug de projet). Les clients avec un domaine personnalisé utilisent leur propre hôte. Les clients servant la documentation sous un sous-chemin incluent le chemin complet (ex. : `https://example.com/docs`).
- **`apiKey`** : remplacez le placeholder par une vraie clé générée dans **Dashboard → Paramètres du projet → Clés API**.
</Warning>

## Étapes suivantes

<Columns cols={2}>
  <Card title="Endpoint de recherche" icon="magnifying-glass" href="/fr/jamdesk-api/search">
    Référence complète avec les schémas de requête/réponse et le playground interactif
  </Card>
  <Card title="Guides d'intégration" icon="plug" href="/fr/jamdesk-api/integrations">
    Guides étape par étape pour Intercom, Zendesk, les bots Slack et les chatbots personnalisés
  </Card>
</Columns>