API di ricerca Docs

L'API di ricerca Docs ti offre accesso programmatico ai contenuti della documentazione tramite ricerca semantica. Un solo endpoint (POST /_api/search) accetta una query in linguaggio naturale e restituisce i passaggi più pertinenti della tua 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'intestazione Authorization.

Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a

Generare chiavi API

Gestione delle chiavi

Revocare le chiavi

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

Limiti di frequenza

Le richieste sono limitate per chiave API.

Sui siti protetti da login, le richieste MCP, .md e llms.txt effettuate con la stessa chiave condividono un limite separato di 120 richieste al minuto. Non contano sul limite dell'API di ricerca, e le richieste all'API di ricerca non contano sul loro.

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

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 c'è paginazione: tutti i risultati corrispondenti tornano in un'unica risposta. Per più contesto, prova una query più specifica invece di un limite più alto.

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

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

Filtrare per lingua

Su un sito multilingue, l'API filtra i risultati per una sola lingua per richiesta. Passa language nel corpo della richiesta con un codice BCP-47 (ad es. 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 dalla macchina su cui puoi basare la logica del programma.

CORS

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

SDK

Al momento non esistono SDK ufficiali per i linguaggi. Usa direttamente l'API REST tramite fetch, requests, curl o qualsiasi client HTTP. La collezione Postman qui sotto fornisce esempi pronti da usare.

Controllo delle versioni

L'API è attualmente alla versione v1.0.0. Le modifiche incompatibili (rinomina di campi, endpoint rimossi, autenticazione modificata) saranno annunciate sul blog Jamdesk e tramite un avviso di deprecazione nell'intestazione di risposta X-Deprecation, almeno 90 giorni prima della rimozione.

Specifica OpenAPI

La specifica OpenAPI 3.1 completa è disponibile in YAML. Importala nel tuo 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 collezione pronta da forkare. Testa le richieste nell'interfaccia Postman senza scrivere codice.

Passaggi successivi