API de recherche de la documentation

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

Cas d'usage

Démarrage rapide

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
}

Authentification

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

Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a

Générer des clés API

Gestion des clés

Révocation des clés

Pour révoquer une clé, allez dans Project Settings → API Keys, trouvez la clé par son nom et cliquez sur Revoke. 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 en débit par clé API.

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

Limites de requête

Chaque requête accepte un paramètre limit contrôlant le nombre de résultats à renvoyer. 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 renvoyés dans une seule réponse. Si vous avez besoin de plus de contexte, essayez une requête plus spécifique plutôt que d'augmenter la limite.

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

{"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 sur une seule langue par requête. Passez language dans le corps de la requête avec un code BCP-47 (par ex. 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"}'

Gestion des erreurs

Toutes les réponses d'erreur incluent un champ error lisible par machine sur lequel vous pouvez faire un branchement programmatique.

CORS

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

SDKs

Il n'existe actuellement aucun SDK officiel par langage. Utilisez l'API REST directement via fetch, requests, curl ou tout autre client HTTP. La collection Postman ci-dessous fournit des exemples prêts à forker.

Versioning

L'API est actuellement en v1.0.0. Les changements incompatibles (renommage de champs, endpoints supprimés, authentification modifiée) seront annoncés via le blog Jamdesk et un avis de dépréciation dans l'en-tête de réponse X-Deprecation au moins 90 jours avant leur suppression.

Spécification OpenAPI

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

Collection Postman

Nous publions un espace de travail Postman officiel avec la spécification OpenAPI complète et une collection prête à forker afin que vous puissiez tester des requêtes dans l'interface Postman sans écrire de code.

Étapes suivantes