API ricerca documentazione

L'API di ricerca della documentazione consente di accedere programmaticamente ai contenuti della documentazione tramite la ricerca semantica. Un endpoint (POST /_api/search) accetta una query in linguaggio naturale e restituisce i passaggi più pertinenti della documentazione, ordinati per rilevanza.

Casi d'uso

Avvio rapido

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
}

Autenticazione

Tutte le richieste richiedono un token Bearer nell'header Authorization.

Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a

Generare chiavi API

Gestione delle chiavi

Revocare le chiavi

Per revocare una chiave, vai a Project Settings → API Keys, trova la chiave tramite il nome e fai clic su Revoke. Le chiavi revocate smettono immediatamente di funzionare. Genera una nuova chiave per sostituirla.

Limiti di frequenza

Le richieste sono soggette a limiti per chiave API.

Quando superi il limite, l'API restituisce 429 Too Many Requests con un header Retry-After: 60 e {"error": "Rate limit exceeded"} nel corpo della risposta.

Limiti delle query

Ogni richiesta accetta un parametro limit che controlla quanti risultati restituire. Il massimo è 20, il valore predefinito è 5 e il minimo è 1. Non è prevista la paginazione: tutti i risultati corrispondenti vengono restituiti in un'unica risposta. Se ti serve più contesto, prova a usare una query più specifica invece di aumentare il limite.

Una query senza corrispondenze restituisce HTTP 200 con un array di risultati vuoto:

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

Filtrare per lingua

Se il sito della documentazione supporta più lingue, l'API filtra i risultati per una singola lingua per richiesta. Invia language nel corpo della richiesta con un codice BCP-47 (ad esempio 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"}'

Gestione degli errori

Tutte le risposte di errore includono un campo error leggibile dalle macchine, su cui puoi diramare la logica programmaticamente.

CORS

CORS è abilitato su tutti gli endpoint. I client basati su browser (app a pagina singola, estensioni del browser e siti statici) possono chiamare direttamente /_api/search senza un proxy backend. Sono consentite tutte le origini.

SDK

Al momento non esistono SDK ufficiali per linguaggi. Usa direttamente la REST API tramite fetch, requests, curl o qualsiasi client HTTP. La raccolta Postman riportata di seguito fornisce esempi pronti da duplicare.

Controllo delle versioni

L'API è attualmente alla versione v1.0.0. Le modifiche incompatibili (rinomina dei campi, rimozione di endpoint o modifiche all'autenticazione) saranno annunciate tramite il blog di Jamdesk e una notifica di deprecazione nell'header di risposta X-Deprecation almeno 90 giorni prima della rimozione.

Specifica OpenAPI

La specifica OpenAPI 3.1 completa è disponibile in formato YAML. Importala nello strumento di generazione del codice, nel client API o nella pipeline di test dei contratti.

Raccolta Postman

Pubblichiamo un workspace Postman ufficiale con la specifica OpenAPI completa e una raccolta pronta da duplicare, così puoi testare le richieste nell'interfaccia di Postman senza scrivere codice.

Passaggi successivi