Docs-Such-API

Die Docs Search API bietet Ihnen programmatischen Zugriff auf Ihre Dokumentationsinhalte über semantische Suche. Ein Endpunkt (POST /_api/search) nimmt eine Suchanfrage in natürlicher Sprache entgegen und gibt die relevantesten Passagen aus Ihrer Dokumentation zurück, sortiert nach Relevanz.

Anwendungsfälle

Schnellstart

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
}

Authentifizierung

Alle Anfragen benötigen ein Bearer-Token im Authorization-Header.

Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a

API-Schlüssel generieren

Schlüsselverwaltung

Schlüssel widerrufen

Gehen Sie zu Project Settings → API Keys, suchen Sie den Schlüssel nach Namen und klicken Sie auf Revoke. Widerrufene Schlüssel funktionieren sofort nicht mehr. Erstellen Sie einen neuen Schlüssel als Ersatz.

Rate-Limits

Anfragen sind pro API-Schlüssel ratenbegrenzt.

Auf einer login-geschützten Website teilen sich MCP-, .md- und llms.txt-Anfragen mit demselben Schlüssel ein separates Limit von 120 Anfragen pro Minute. Sie zählen nicht auf das Limit der Search API, und Search-API-Anfragen zählen nicht auf deren Limit.

Bei Überschreitung des Limits antwortet die API mit 429 Too Many Requests, einem Retry-After: 60-Header und {"error": "Rate limit exceeded"} im Body.

Abfragelimits

Jede Anfrage akzeptiert einen limit-Parameter, der die Anzahl der zurückgegebenen Ergebnisse steuert. Das Maximum beträgt 20, der Standardwert 5 und das Minimum 1. Es gibt keine Paginierung. Alle passenden Ergebnisse kommen in einer Antwort zurück. Für mehr Kontext versuchen Sie eine präzisere Suchanfrage statt eines höheren Limits.

Eine Abfrage ohne Treffer gibt HTTP 200 mit einem leeren Ergebnis-Array zurück:

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

Nach Sprache filtern

Auf einer mehrsprachigen Website filtert die API die Ergebnisse pro Anfrage auf eine Sprache. Übergeben Sie language im Request-Body mit einem BCP-47-Code (z. B. 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"}'

Fehlerbehandlung

Alle Fehlerantworten enthalten ein maschinenlesbares Feld error, nach dem Sie programmatisch verzweigen können.

CORS

CORS ist für alle Endpunkte aktiviert. Browserbasierte Clients (Single-Page-Apps, Browsererweiterungen, statische Websites) können /_api/search direkt aufrufen, ohne einen Backend-Proxy. Alle Ursprünge sind erlaubt.

SDKs

Derzeit gibt es keine offiziellen SDKs für Programmiersprachen. Nutzen Sie die REST-API direkt über fetch, requests, curl oder einen beliebigen HTTP-Client. Die Postman-Collection unten bietet sofort nutzbare Beispiele zum Forken.

Versionierung

Die API befindet sich derzeit in Version v1.0.0. Breaking Changes (umbenannte Felder, entfernte Endpunkte, geänderte Authentifizierung) werden über den Jamdesk-Blog und einen Deprecation-Hinweis im Antwort-Header X-Deprecation mindestens 90 Tage vor der Entfernung angekündigt.

OpenAPI-Spezifikation

Die vollständige OpenAPI-3.1-Spezifikation ist als YAML verfügbar. Importieren Sie sie in Ihr Codegen-Tool, Ihren API-Client oder Ihre Contract-Testing-Pipeline.

Postman-Sammlung

Wir veröffentlichen einen offiziellen Postman-Workspace mit der vollständigen OpenAPI-Spezifikation und einer sofort nutzbaren Collection zum Forken. Testen Sie Anfragen in der Postman-Oberfläche, ohne Code zu schreiben.

Nächste Schritte