Skip to main content

REST API Overview

Most HTTP endpoints live under http://localhost:3100/api/v1. The main exceptions are:

  • GET /health for health checks
  • GET /metrics for Prometheus scraping

The same API powers the Web UI, the server-mode CLI, and external integrations.

Base path

Unless a path in this page starts with /health or /metrics, it is relative to /api/v1.

Response Envelope​

Successful JSON responses use a data envelope and optionally a meta object:

{
  "data": {},
  "meta": {
    "took_ms": 12
  }
}

Errors use an error envelope:

{
  "error": {
    "code": "INVALID_QUERY",
    "message": "Unknown command 'staats'.",
    "suggestion": "stats"
  }
}

Authentication and Scopes​

Authentication is off by default.

When enabled, the middleware protects all /api/... routes except for:

  • GET /health
  • GET /metrics
  • non-API Web UI and static asset paths

Accepted Authorization schemes:

  • Bearer <token>
  • ApiKey <base64(id:secret)>
  • Basic <base64(user:token)>

For browser SSE clients that cannot set headers, LynxDB also accepts _token as a query parameter and then redacts it from the request URL before downstream handling.

Some endpoints add scope requirements on top of authentication:

  • query endpoints require query scope
  • ingest endpoints require ingest scope
  • GET /api/v1/config requires admin scope
  • PATCH /api/v1/config requires a root key
  • auth key management endpoints require a root key

See TLS & Authentication for setup.

Common HTTP Status Codes​

CodeMeaning
200Success
201Resource created
202Accepted (async job started)
204Deleted (no content)
400Bad request
401Authentication required
403Authenticated but insufficient scope
404Resource not found
413Payload too large
422Validation error
429Rate limited
503Backpressure or shutting down

Common Headers​

Request Headers​

HeaderDescriptionDefault
Content-TypeRequest body formatapplication/json
AcceptResponse format (application/json or application/x-ndjson)application/json
AuthorizationBearer, ApiKey, or Basic auth--
X-SourceSource label for raw ingest--
X-Source-TypeSource type label for raw ingest--
X-IndexTarget index for raw ingestmain

Response Headers​

HeaderDescription
Content-TypeJSON, NDJSON, or SSE
Retry-AfterRetry hint on rate limiting or backpressure
X-Request-IDRequest correlation ID
X-Query-IDQuery correlation ID

Query Execution Modes​

POST /api/v1/query supports three execution modes through the wait field:

wait valueModeBehavior
omitted / nullSync windowWait until completion. If the query misses query.sync_timeout (default 30s), LynxDB detaches it and returns 202 Accepted with a job handle
0AsyncReturn a job handle immediately
positive numberHybridWait up to N seconds, then fall back to a job handle

POST /api/v1/query always returns the JSON response envelope. For NDJSON export, use POST /api/v1/query/stream.

See Query API for the exact request and response formats.

Endpoint Summary​

MethodEndpointDescriptionDocs
GET/healthHealth check outside /api/v1Server
GET/metricsPrometheus metrics outside /api/v1Server
POST/ingestIngest JSON event arraysIngest
POST/ingest/rawIngest newline-delimited raw textIngest
POST/ingest/hecSplunk HEC-compatible ingestIngest
POST/ingest/bulkElasticsearch bulk ingest alias (prefer /es/_bulk)Ingest
POST/queryExecute SPL2 queryQuery
GET/queryExecute query (GET convenience)Query
POST/query/streamNDJSON streaming exportQuery
GET/query/explainParse and explain queryQuery
GET/query/jobsList query jobsQuery
GET/query/jobs/{id}Get job status and resultsQuery
GET/query/jobs/{id}/streamSSE job progress streamQuery
DELETE/query/jobs/{id}Cancel a running jobQuery
GET/tailSSE live tailLive Tail & Histogram
GET/histogramTime-bucketed event countsLive Tail & Histogram
GET/fieldsField catalogFields
GET/fields/{name}/valuesTop values for a fieldFields
GET/sourcesSource catalogFields
GET/POST/queriesList/create saved queriesSaved Queries
PUT/DELETE/queries/{id}Update/delete saved querySaved Queries
GET/POST/viewsList/create materialized viewsViews
GET/PATCH/DELETE/views/{name}Get/update/delete viewViews
GET/POST/views/{name}/backfillInspect or start backfillViews
GET/statusOperational status snapshotServer
GET/statsStorage and ingest statisticsServer
GET/metricsJSON storage metricsServer
GET/configRuntime configurationServer
PATCH/configUpdate runtime configuration snapshotServer
GET/cluster/statusCluster status summaryServer
GET/compaction/historyRecent compaction manifestsServer
GET/cache/statsQuery cache statisticsServer
DELETE/cacheClear query cacheServer
GET/POST/DELETE/auth/...Auth key management, only when auth is enabledServer
POST/es/_bulkPreferred Elasticsearch bulk APICompatibility
POST/es/{index}/_docES single-doc ingestCompatibility
GET/es/ES cluster info handshakeCompatibility
POST/otlp/v1/logsOpenTelemetry OTLP logsCompatibility