API de recherche de documentation

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

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}'

{
  "query": "How do I set up a custom domain?",
  "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 token Bearer dans l'en-tête Authorization.

Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a

Génération des clés API

Gestion des clés

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.

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.

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 :

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

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.

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 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 et un avis de dépréciation dans l'en-tête de réponse X-Deprecation au moins 90 jours avant la suppression.

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.

Étapes suivantes