REST API

The QuantSearch REST API allows you to build custom integrations, ingest content programmatically, and create your own search interfaces. API access is available on Pro and Enterprise plans.

Base URLs

Authentication

Authenticated API requests require an API key in the Authorization header:

curl https://www.quantsearch.ai/api/sites \
  -H "Authorization: Bearer YOUR_API_KEY"

Generate API keys in your Dashboard → API Keys.

Public Endpoints

These endpoints don't require authentication but need to be enabled in your site's public access settings:

Search

# GET request (cacheable via CDN)
curl "https://cdn.quantsearch.ai/v1/public/sites/{siteId}/search?q=how+to+reset+password"

# POST request (for complex queries)
curl -X POST https://cdn.quantsearch.ai/v1/public/sites/{siteId}/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how to reset password",
    "limit": 10,
    "minScore": 0.3
  }'

Response:

{
  "query": "how to reset password",
  "results": [
    {
      "url": "https://example.com/help/reset-password",
      "title": "Password Reset Guide",
      "snippet": "To reset your password, click the 'Forgot Password' link...",
      "score": 0.89
    }
  ],
  "totalResults": 5,
  "timingMs": 45
}

Chat

curl -X POST https://cdn.quantsearch.ai/v1/public/sites/{siteId}/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "how do I reset my password?",
    "sessionId": "optional-session-id"
  }'

Response:

{
  "response": "To reset your password, go to the login page and click 'Forgot Password'. Enter your email address and we'll send you a reset link. The link expires after 24 hours.",
  "sources": [
    {
      "url": "https://example.com/help/reset-password",
      "title": "Password Reset Guide",
      "relevance": 0.89
    }
  ],
  "sessionId": "sess_abc123"
}

Group Search (Federated)

Search across multiple sites in a group (Pro+ feature):

# Search across all sites in a group
curl "https://cdn.quantsearch.ai/v1/public/groups/{groupId}/search?q=password+reset"

Authenticated Endpoints — Sites

List Sites

GET /api/sites — return every site in your organization.

curl https://www.quantsearch.ai/api/sites \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Site

GET /api/sites/{siteId} — return one site's full configuration.

curl https://www.quantsearch.ai/api/sites/{siteId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Site

POST /api/sites — create a new site to crawl or ingest.

curl -X POST https://www.quantsearch.ai/api/sites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Documentation",
    "baseUrl": "https://docs.example.com",
    "crawlerConfig": {
      "maxPages": 1000,
      "maxDepth": 5
    }
  }'

Update Site

PUT /api/sites/{siteId} — update site metadata, crawler config, public access rules, or relevance boosts. Pass only the fields you want to change; others are left as-is. Returns { "success": true }.

curl -X PUT https://www.quantsearch.ai/api/sites/{siteId} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Documentation",
    "description": "Help center for our docs site",
    "crawlerConfig": {
      "maxPages": 2000,
      "maxDepth": 6,
      "javascriptEnabled": true
    },
    "publicAccess": {
      "allowedDomains": ["docs.example.com", "help.example.com"],
      "searchEnabled": true,
      "chatEnabled": true
    }
  }'

Delete Site

DELETE /api/sites/{siteId} — permanently delete a site and all its indexed content. Returns 200 with { "success": true }. Owner role required.

curl -X DELETE https://www.quantsearch.ai/api/sites/{siteId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Authenticated Endpoints — Crawler

Start Crawl

POST /api/sites/{siteId}/crawl — kick off a crawl for the site. Returns the new job. Returns 409 if a crawl is already running for this site.

curl -X POST https://www.quantsearch.ai/api/sites/{siteId}/crawl \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "jobId": "10b71a36-5298-477a-b60b-cbbb1877d3ad",
  "message": "Crawl started successfully"
}

Get Job

GET /api/jobs/{jobId} — check the status of a crawl job. Statuses: pending, running, completed, failed, cancelled. Note the response uses jobId as the identifier (not id) to match the crawl-start response.

curl https://www.quantsearch.ai/api/jobs/{jobId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "jobId": "10b71a36-5298-477a-b60b-cbbb1877d3ad",
  "siteId": "<siteId>",
  "status": "running",
  "startedAt": 1715168400,
  "completedAt": null,
  "createdAt": 1715168400,
  "pagesDiscovered": 200,
  "pagesCrawled": 84,
  "pagesProcessed": 84,
  "pagesSkipped": 0,
  "pagesErrored": 0,
  "errors": 0,
  "currentUrl": "https://example.com/page-being-crawled"
}

Cancel Job

DELETE /api/jobs/{jobId} — cancel a running crawl. The underlying ECS task is stopped.

curl -X DELETE https://www.quantsearch.ai/api/jobs/{jobId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Authenticated Endpoints — Content

Ingest Content

POST /api/sites/{siteId}/pages — push content directly, bypassing the crawler. Useful for static-site generators, headless CMSs, and any source the crawler can't reach. Pro/Enterprise only — free-tier organizations receive 403 "API access requires Pro or Enterprise plan".

curl -X POST https://www.quantsearch.ai/api/sites/{siteId}/pages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pages": [
      {
        "url": "https://example.com/page1",
        "title": "Page Title",
        "content": "Full page content here...",
        "summary": "Optional summary",
        "tags": ["tag1", "tag2"]
      }
    ]
  }'

List Pages

GET /api/sites/{siteId}/pages — list pages currently in the index. Supports cursor pagination (cursor query param, URL of the last item) and a search filter on title/URL.

curl "https://www.quantsearch.ai/api/sites/{siteId}/pages?limit=50&search=docs" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "items": [
    {
      "url": "https://example.com/help/reset-password",
      "title": "Password Reset Guide",
      "summary": "How to reset your password",
      "indexedAt": 1715168000,
      "tags": ["help", "auth"]
    }
  ],
  "nextCursor": "https://example.com/help/reset-password",
  "hasMore": true
}

Delete Pages

DELETE /api/sites/{siteId}/pages — delete specific pages by exact URL or by glob/regex pattern. Pro/Enterprise only.

curl -X DELETE https://www.quantsearch.ai/api/sites/{siteId}/pages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/page-to-delete"]
  }'

Purge Site Index

POST /api/sites/{siteId}/purge — wipe every page from the index for one site. The site itself is preserved — only the indexed content is removed.

curl -X POST https://www.quantsearch.ai/api/sites/{siteId}/purge \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "deletedCount": 142
}

Authenticated Endpoints — Search Groups

Search groups federate search across multiple sites in your organization. Enterprise plan only — Pro/Free organizations receive 403 "Search Groups require an Enterprise plan".

List Groups

GET /api/groups — return every search group.

curl https://www.quantsearch.ai/api/groups \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Group

POST /api/groups — create a new federated group from one or more existing site IDs. Returns 402 if your plan doesn't include groups.

curl -X POST https://www.quantsearch.ai/api/groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Public Docs",
    "description": "Federated search across all our public documentation sites",
    "siteIds": ["<siteId1>", "<siteId2>"]
  }'

Update Group

PUT /api/groups/{groupId} — change a group's name, description, or member sites.

curl -X PUT https://www.quantsearch.ai/api/groups/{groupId} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "siteIds": ["<siteId1>", "<siteId2>", "<siteId3>"]
  }'

Delete Group

DELETE /api/groups/{groupId} — delete a group. Returns 204 No Content. The member sites are unaffected.

curl -X DELETE https://www.quantsearch.ai/api/groups/{groupId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Authenticated Endpoints — Analytics

Analytics endpoints surface search-query, chat, and indexed-content usage at both the org and per-site level. Figures may lag real-time activity by a few minutes since they're sourced from upstream telemetry.

Org Analytics

GET /api/analytics?range=30d&siteId=… — aggregated rollup across the whole organization, or scoped to one site if siteId is supplied. Includes total search/chat counts, top queries, per-site breakdown, and a daily time-series.

curl "https://www.quantsearch.ai/api/analytics?range=30d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "totalSearches": 1247,
  "totalChats": 312,
  "totalPagesIndexed": 1820,
  "topQueries": [
    {"query": "how to reset password", "count": 89},
    {"query": "pricing", "count": 67}
  ],
  "siteBreakdown": [
    {
      "id": "<siteId>",
      "name": "Documentation",
      "pagesIndexed": 1820,
      "searches": 1247,
      "chats": 312
    }
  ],
  "dailyUsage": [
    {"date": "2026-04-08", "searches": 41, "chats": 12},
    {"date": "2026-04-09", "searches": 38, "chats": 8}
  ]
}

Org Usage (Billing)

GET /api/usage?month=YYYY-MM — monthly usage figures used for billing and quota tracking. Returns AI token consumption split between ingest and chat, vector-DB stats, and locally-tracked search/chat counts. Use this for billing dashboards; use /api/analytics for product analytics.

curl "https://www.quantsearch.ai/api/usage?month=2026-05" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "month": "2026-05",
  "ai": {
    "totalRequests": 1559,
    "totalInputTokens": 412000,
    "totalOutputTokens": 87000,
    "totalTokens": 499000,
    "estimatedCost": 4.23,
    "ingest": {"requests": 1247, "tokens": 380000},
    "chat": {"requests": 312, "tokens": 119000}
  },
  "vectorDb": {
    "totalCollections": 1,
    "totalDocuments": 1820
  },
  "searches": {
    "total": 1247,
    "chat": 312
  }
}

Site Usage

GET /api/sites/{siteId}/usage?range=30d — search and chat counts for a single site over the requested range, plus a daily series. Always returns a stable shape — if upstream telemetry is unavailable, all counts return as 0 rather than erroring.

curl "https://www.quantsearch.ai/api/sites/{siteId}/usage?range=30d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "siteId": "<siteId>",
  "range": "30d",
  "searches": 1247,
  "chats": 312,
  "totalTokens": 499000,
  "daily": [
    {"date": "2026-04-08", "searches": 41, "chats": 12}
  ]
}

Site Top Queries

GET /api/sites/{siteId}/top-queries?range=30d&limit=20 — most-searched queries for one site, sorted descending. limit defaults to 20 and is capped at 100.

curl "https://www.quantsearch.ai/api/sites/{siteId}/top-queries?range=30d&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "siteId": "<siteId>",
  "range": "30d",
  "topQueries": [
    {"query": "how to reset password", "count": 89},
    {"query": "pricing", "count": 67},
    {"query": "api documentation", "count": 54}
  ]
}

Rate Limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1702500000

Errors

The API returns standard HTTP status codes:

Error responses include a JSON body:

{
  "error": "Rate limit exceeded",
  "retryAfter": 30
}

OpenAPI Specification

Download the full OpenAPI specification for code generation and API exploration.