Docs Search API

The Docs Search API gives you programmatic access to your documentation content via semantic search. One endpoint (POST /_api/search) takes a natural language query and returns the most relevant passages from your docs, ranked by relevance.

Use Cases

Quick Start

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
}

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer jd_live_c83003a54ae0a83123454c3f7ec82f0a

Generating API Keys

Key Management

Revoking Keys

Go to Project Settings → API Keys, find the key by name, and click Revoke. Revoked keys stop working immediately. Generate a new key to replace it.

Rate Limits

Requests are rate-limited per API key.

On a login-protected site, MCP, .md and llms.txt requests made with the same key share a separate limit of 120 requests per minute. They don't count against the Search API limit, and Search API requests don't count against theirs.

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After: 60 header and {"error": "Rate limit exceeded"} in the body.

Query Limits

Each request accepts a limit parameter controlling how many results to return. The maximum is 20, the default is 5, and the minimum is 1. There is no pagination. All matching results come back in one response. For more context, try a more specific query instead of a higher limit.

A query with no matches returns HTTP 200 with an empty results array:

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

Filtering by language

On a multi-language site, the API filters results to one language per request. Pass language in the request body with a BCP-47 code (e.g. 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"}'

Error Handling

All error responses include a machine-readable error field you can branch on programmatically.

CORS

CORS is enabled on all endpoints. Browser-based clients (single-page apps, browser extensions, static sites) can call /_api/search directly without a backend proxy. All origins are allowed.

SDKs

There are no official language SDKs at this time. Use the REST API directly via fetch, requests, curl, or any HTTP client. The Postman collection below provides ready-to-fork examples.

Versioning

The API is currently at v1.0.0. Breaking changes (field renames, removed endpoints, changed auth) will be announced via the Jamdesk blog and a deprecation notice in the X-Deprecation response header at least 90 days before removal.

OpenAPI Specification

The full OpenAPI 3.1 spec is available as YAML. Import it into your codegen tool, API client, or contract-testing pipeline.

Postman Collection

We publish an official Postman workspace with the full OpenAPI spec and a ready-to-fork collection. Test requests in the Postman UI without writing code.

Next Steps