Docs-Such-API

Die Docs-Such-API ermöglicht dir über die semantische Suche programmgesteuerten Zugriff auf deine Dokumentationsinhalte. Ein Endpoint (POST /_api/search) nimmt eine Anfrage in natürlicher Sprache entgegen und gibt die relevantesten Passagen deiner Dokumentation nach Relevanz sortiert zurück.

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

Um einen Schlüssel zu widerrufen, gehe zu Project Settings → API Keys, suche den Schlüssel anhand seines Namens und klicke auf Revoke. Widerrufene Schlüssel funktionieren sofort nicht mehr. Generiere einen neuen Schlüssel als Ersatz.

Rate-Limits

Anfragen werden pro API-Schlüssel mit einem Rate-Limit versehen.

Wenn du das Limit überschreitest, gibt die API 429 Too Many Requests mit einem Retry-After: 60-Header und {"error": "Rate limit exceeded"} im Body zurück.

Abfragelimits

Jede Anfrage akzeptiert einen limit-Parameter, der steuert, wie viele Ergebnisse zurückgegeben werden. Das Maximum ist 20, der Standardwert ist 5 und das Minimum ist 1. Es gibt keine Paginierung; alle übereinstimmenden Ergebnisse werden in einer einzigen Antwort zurückgegeben. Wenn du mehr Kontext benötigst, versuche eine spezifischere Anfrage, statt das Limit zu erhöhen.

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

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

Nach Sprache filtern

Wenn deine Docs-Site mehrere Sprachen unterstützt, filtert die API die Ergebnisse pro Anfrage auf eine einzelne Sprache. Übergebe language im Anfragetext 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 error-Feld, anhand dessen du programmgesteuert verzweigen kannst.

CORS

CORS ist für alle Endpoints aktiviert. Browserbasierte Clients (Single-Page-Apps, Browsererweiterungen, statische Sites) können /_api/search direkt ohne Backend-Proxy aufrufen. Alle Origins sind zulässig.

SDKs

Derzeit gibt es keine offiziellen SDKs für Programmiersprachen. Verwende die REST-API direkt über fetch, requests, curl oder einen beliebigen HTTP-Client. Die Postman-Sammlung unten bietet sofort verwendbare Beispiele, die du forken kannst.

Versionierung

Die API befindet sich derzeit bei v1.0.0. Breaking Changes (Umbenennungen von Feldern, entfernte Endpoints, geänderte Authentifizierung) werden mindestens 90 Tage vor ihrer Entfernung über den Jamdesk-Blog und einen Hinweis zur Einstellung im X-Deprecation-Antwortheader angekündigt.

OpenAPI-Spezifikation

Die vollständige OpenAPI-3.1-Spezifikation ist als YAML verfügbar. Importiere sie in dein Codegen-Tool, deinen API-Client oder deine Pipeline für Vertragstests.

Postman-Sammlung

Wir veröffentlichen einen offiziellen Postman-Arbeitsbereich mit der vollständigen OpenAPI-Spezifikation und einer Sammlung, die du forken kannst, um Anfragen in der Postman-Oberfläche ohne eigenen Code zu testen.

Nächste Schritte