API de recherche Docs

L'API de recherche Docs vous donne un accès programmatique à votre contenu de 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'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 token Bearer dans l'en-tête Authorization.

Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a

Générer des clés API

Gestion des clés

Révoquer 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 soumises à une limite de débit 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 que d'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}

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 (p. 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 vous brancher de manière programmatique.

CORS

Le CORS est activé sur tous les endpoints. Les clients basés sur le 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 pas de SDKs officiels pour les différents 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.

Versionnement

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 une notice 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 en YAML. Importez-la dans votre outil de génération de code, client API ou pipeline de test contractuel.

Collection Postman

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

Étapes suivantes