Skip to main content

REST API Overview

The HTTP API listens on http://localhost:3100 by default. Most endpoints live under /api/v1; the exceptions are:

  • GET /health and GET /metrics
  • the Elasticsearch compatibility routes at the root (/, /_bulk, /{index}/_bulk, ...)
  • the Splunk HEC routes under /services/collector

The CLI in server mode and every integration use this API. Queries are written in PPL.

Response envelope​

Successful JSON responses wrap the payload in data, with a meta object when there is something to report:

{
"data": {"type": "aggregate", "columns": ["n", "level"], "rows": [[5, "ERROR"], [15, "INFO"], [6, "WARN"]], "total_rows": 3, "has_more": false},
"meta": {"took_ms": 0.232, "query_id": "qry_c691abc2c45c5cfa", "rows": 3}
}
meta fieldDescription
took_msTime the request or the query took, in milliseconds
query_idID of the query job, also sent as the X-Query-ID header
rowsNumber of rows the query produced

Errors use an error envelope with a machine-readable code, a message and, when there is one, a suggestion. Query compile errors add position and expected:

{
"error": {
"code": "SYNTAX_ERROR",
"message": "syntax error at line 1, column 29: expected an expression",
"position": {"line": 1, "column": 29},
"expected": ["expression"]
}
}

Compatibility endpoints answer in the format of the protocol they implement (Elasticsearch, Splunk HEC, OTLP); their pages say so.

Error codes​

CodeHTTPMeaning
SYNTAX_ERROR, SEMANTIC_ERROR, TYPE_ERROR400The query does not compile. See Query errors
PLANNING_ERROR400The query parsed but no plan could be built for it
UNSUPPORTED_COMMAND, UNSUPPORTED_FUNCTION, UNSUPPORTED_FEATURE422The query uses PPL that LynxDB does not run
EXECUTION_ERROR500The query failed while running
QUERY_TOO_LARGE400The query text is longer than query.max_query_length
TOO_MANY_REQUESTS429query.max_concurrent queries are running, or the per-IP rate limit was hit; see Retry-After
VALIDATION_ERROR400A required parameter is missing or a value is invalid
INVALID_JSON400The body is not valid JSON
INVALID_REQUEST400, 413, 415The body could not be read, is too large, or has an unsupported media type
AUTH_REQUIRED, INVALID_TOKEN401No credentials, or credentials that do not match a key
FORBIDDEN403The key lacks the scope the endpoint needs
NOT_FOUND404No such job or key, or authentication is off on an /auth route
LAST_ROOT_KEY409Revoking the only root key; rotate it instead
SHUTTING_DOWN503The server is stopping; see Retry-After
INTERNAL_ERROR500An unexpected server failure

Authentication and scopes​

Authentication is off by default (lynxdb server --auth turns it on). When it is on, every route under /api/ needs credentials. GET /health, GET /metrics and the routes outside /api/ are not checked by the API key middleware.

Accepted Authorization schemes:

  • Bearer <token>
  • ApiKey <base64(id:token)>, the format Filebeat and other Elasticsearch clients send
  • Basic <base64(user:token)>; the user name is ignored

Clients that cannot set headers, such as a browser EventSource following a job stream, can pass the token as the _token query parameter. The server removes it from the URL before the request is logged.

Keys have one of four scopes: ingest, query, admin, full. Root keys and full keys pass every check.

EndpointsRequired
POST /ingest, /ingest/raw, /ingest/hec, /es/_bulk, /es/_data_stream/{name}/_bulk, /es/{index}/_docingest
POST and GET /query, POST /query/stream, GET /query/jobs, GET /query/jobs/{id}, GET /query/jobs/{id}/streamquery
DELETE /query/jobs/{id}, GET /configadmin
PATCH /config, /auth/...a root key
Everything else under /api/any valid key

The Elasticsearch bulk routes at the root (/_bulk, /{index}/_bulk, /_data_stream/{name}/_bulk) also check for an ingest key, but the middleware does not read credentials outside /api/, so with authentication on they answer 401. Point shippers at /api/v1/es instead. The Splunk HEC routes under /services/collector check their own Authorization: Splunk <token> header.

See TLS & Authentication for setup and lynxdb auth for key management from the CLI.

Headers​

Request​

HeaderDescription
Content-TypeBody format; JSON endpoints read application/json
Content-Encodinggzip, zstd or snappy bodies are decoded on every route; any other encoding answers 400
AuthorizationBearer, ApiKey or Basic credentials
X-Request-IDCorrelation ID; echoed back, generated when absent
X-IndexTarget index of POST /ingest and POST /ingest/raw
X-Source, X-Source-Type, X-HostLabels of the text lines of POST /ingest/raw

Response​

HeaderDescription
X-Request-IDCorrelation ID of the request
X-Query-IDID of the query job, on query and job responses
Retry-AfterSeconds to wait, on 429 and 503
ETag, Cache-ControlOn GET /api/v1/catalog

Request size limits​

SettingDefaultApplies to
ingest.max_body_size100 MBEvery request body as sent; for POST /ingest and POST /ingest/raw also after Content-Encoding decoding
ingest.limits.max_compressed_body_bytes32 MBBody as sent, on every route other than POST /ingest and POST /ingest/raw
ingest.limits.max_decompressed_body_bytes256 MBBody after Content-Encoding decoding, on the same routes
ingest.max_line_bytes1 MiBOne line of an Elasticsearch bulk or Splunk HEC body
query.max_query_length1 MiBQuery text

A body over the compressed or decompressed limit, or with an encoding the server cannot decode, answers in the Elasticsearch error format:

{"error": {"type": "invalid_request", "reason": "unsupported content encoding \"br\""}, "status": 400}

The type is request_body_too_large with status 413 for a body over a limit, and the reason names the setting that applies:

{"error": {"type": "request_body_too_large", "reason": "compressed body exceeds limit 2048 set by ingest.limits.max_compressed_body_bytes"}, "status": 413}

Endpoint map​

Paths below are relative to /api/v1 unless they start with /health, /metrics, /_, /{index} or /services.

MethodPathDescriptionPage
POST/queryRun a PPL query: sync, async or hybridQuery
GET/queryRun a PPL query from query-string parametersQuery
POST/query/streamRun a query and stream NDJSON rowsQuery
GET/query/explainCompile a query and return its plansQuery
GET/catalogPPL commands and functions with support levelsQuery
GET/query/jobsList jobsQuery
GET/query/jobs/{id}Job status and resultQuery
DELETE/query/jobs/{id}Cancel a jobQuery
GET/query/jobs/{id}/streamJob state and result over SSEQuery
GET/histogramEvent counts per time bucketHistogram
GET/fieldsField catalogFields
GET/fields/{name}/valuesTop values of a fieldFields
POST/ingestIngest NDJSON eventsIngest
POST/ingest/rawIngest log textIngest
POST/ingest/hecIngest Splunk HEC eventsIngest
GET/indexesList indexesIngest
POST/es/_bulk, /_bulk, /{index}/_bulkElasticsearch bulk ingestCompatibility
POST/es/{index}/_docElasticsearch single-document ingestCompatibility
GET/, /es, /es/Elasticsearch handshakeCompatibility
POST/services/collector, /services/collector/event, /services/collector/rawSplunk HEC ingestCompatibility
POST/services/collector/ackSplunk HEC acknowledgementsCompatibility
GET/services/collector/healthSplunk HEC healthCompatibility
POST/otlp/v1/logsOTLP/HTTP JSON logsCompatibility
GET/healthHealth checkServer
GET/metricsPrometheus metricsServer
GET/statusServer snapshotServer
GET/statsIndexes, storage and job countersServer
GET/configRuntime configurationServer
PATCH/configChange runtime configurationServer
POST, GET/auth/keysCreate or list API keysServer
DELETE/auth/keys/{id}Revoke an API keyServer
POST/auth/rotate-rootRotate the root keyServer
GET/debug/pprof/...Go runtime profilesServer

The OpenAPI description of these endpoints is at /api/swagger.yaml.