API Overview

The ZenSearch API provides programmatic access to search and chat for embedding ZenSearch into your own applications, websites, and documentation sites.

Two API surfaces

ZenSearch exposes two distinct API surfaces:

Surface	Base path	Auth	Use case
Public API	/v1/...	API key (X-ZenSearch-Key header)	Embedding search/chat in your own apps and docs sites
Dashboard API	/api/v1/...	JWT (Bearer, from your ZenSearch session)	Powers the ZenSearch web UI; team-scoped CRUD for collections, connectors, agents, and admin

This reference documents the public API. The dashboard API is internal and not stable for external integrations.

Base URL

https://your-domain.com/v1

Authentication

All public API requests require an API key in the X-ZenSearch-Key header:

curl -H "X-ZenSearch-Key: zsk_pk_xxx..." \
  https://your-domain.com/v1/docs/search

See Authentication for details.

Response Format

All responses use JSON format:

{
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Responses

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter: query",
    "details": { ... }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Endpoints

Search

Method	Endpoint	Description
POST	/v1/docs/search	Search documents (JSON body)
GET	/v1/docs/search	Search documents (query params)
GET	/v1/docs/autocomplete	Type-ahead suggestions
GET	/v1/docs/{doc_id}	Get a single document

Chat

Method	Endpoint	Description
POST	/v1/chat/stream	Streaming chat over Server-Sent Events

Analytics

Method	Endpoint	Description
POST	/v1/docs/analytics	Track a search / click / feedback event
GET	/v1/docs/analytics/overview	Aggregate metrics for an API key
GET	/v1/docs/analytics/top-queries	Top searched queries
GET	/v1/docs/analytics/top-clicked	Top clicked results
GET	/v1/docs/analytics/trends	Query volume over time
GET	/v1/docs/analytics/zero-results	Queries that returned no results

Collections, connectors, agents, documents

CRUD for collections, connectors, agents, and documents lives on the dashboard API (/api/v1/teams/:teamID/...) and uses your ZenSearch session JWT. These endpoints are not currently exposed under the public /v1/ API key surface — manage those resources through the dashboard.

Rate Limits

See Rate Limits for current limits.

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

SDKs

Official SDKs are available:

• JavaScript/TypeScript: npm install @zensearch/sdk
• Python: pip install zensearch
• Go: go get github.com/ZenousAI/zensearch-go

Next Steps

• Authentication - API key setup
• Search API - Search endpoints
• Chat API - Chat endpoints