Skip to main content

Server API

GET /health​

The health check lives at /health, outside /api/v1. It never requires authentication and is not rate limited.

curl -s localhost:3100/health
{"data": {"status": "healthy", "version": "dev"}}

A server that answers is healthy; status is always healthy. version is the version of the binary, dev for a build from source.

GET /metrics​

Prometheus text metrics, outside /api/v1 and without authentication. Besides the Go runtime and process metrics, LynxDB exports:

MetricLabelsDescription
lynxdb_query_duration_secondsresult_typeHistogram of query durations
lynxdb_query_errors_totaltypeFailed queries by error code
lynxdb_ingest_events_totalEvents ingested
lynxdb_ingest_batches_totalIngest batches
lynxdb_ingest_bytes_totalBytes of NDJSON ingested
lynxdb_ingest_errors_totalFailed ingest batches
lynxdb_ingest_es_bulk_requests_totalresultElasticsearch bulk requests: success, partial, error
lynxdb_ingest_es_bulk_items_totalaction, resultElasticsearch bulk items: ok, rejected
lynxdb_ingest_es_bulk_duration_secondsHistogram of bulk request times
lynxdb_ingest_es_handshake_totalkindElasticsearch handshake and setup probes
lynxdb_ingest_otlp_requests_totalsignal, encoding, resultOTLP requests
lynxdb_ingest_otlp_records_totalsignal, resultOTLP log records accepted or dropped
lynxdb_ingest_otlp_request_bytesHistogram of decoded OTLP body sizes
lynxdb_ingest_dropped_records_totalsource, reasonRecords dropped at ingest
lynxdb_ingest_decompression_rejected_totalstage, encodingBodies rejected by the compressed or decompressed size limit
lynxdb_ingest_listener_uplistener1 while the es, otlp_http or otlp_grpc listener is bound
lynxdb_syslog_messages_received_total, lynxdb_syslog_messages_dropped_total, lynxdb_syslog_parse_errors_total, lynxdb_syslog_active_connectionsSyslog receiver, when it runs

See Monitoring.

GET /api/v1/status​

A compact snapshot of the server:

curl -s localhost:3100/api/v1/status
{
"data": {
"version": "dev",
"uptime_seconds": 137,
"health": "healthy",
"storage": {"used_bytes": 53424},
"events": {"total": 1060},
"queries": {"active": 0},
"retention": {"oldest_event": "2025-01-15T08:00:00Z"}
}
}
FieldDescription
storage.used_bytesSize of the files of every index
events.totalEvents stored
queries.activeJobs running
retention.policyThe retention setting, when events expire
retention.oldest_eventTime of the oldest event, when there is one

GET /api/v1/stats​

The indexes, their totals and the jobs, as used by lynxdb status:

curl -s localhost:3100/api/v1/stats
{
"data": {
"uptime_seconds": 137,
"storage_bytes": 53424,
"filter_bytes": 9216,
"total_events": 1060,
"index_count": 3,
"part_count": 4,
"merges_running": 0,
"runs_to_merge": 0,
"oldest_event": "2025-01-15T08:00:00Z",
"newest_event": "2026-11-17T15:43:40Z",
"indexes": [
{"name": "backend", "events": 26, "bytes": 3978, "parts": 1, "merges_running": 0, "runs_to_merge": 0, "first_event": "2026-02-10T08:12:03.045Z", "last_event": "2026-02-10T10:45:00.5Z", "sort_key": [], "time_fields": ["_time", "timestamp", "@timestamp", "time", "ts"], "partition": "1d"},
{"name": "main", "events": 1000, "bytes": 46638, "parts": 2, "merges_running": 0, "runs_to_merge": 0, "first_event": "2025-01-15T08:00:00.105Z", "last_event": "2026-11-17T15:43:40.839562Z", "sort_key": [], "time_fields": ["_time", "timestamp", "@timestamp", "time", "ts"], "partition": "1d"},
{"name": "nginx", "events": 34, "bytes": 2808, "parts": 1, "merges_running": 0, "runs_to_merge": 0, "first_event": "2026-11-17T15:43:40.867817Z", "last_event": "2026-11-17T15:43:40.867817Z", "sort_key": [], "time_fields": ["_time", "timestamp", "@timestamp", "time", "ts"], "partition": "1d"}
],
"jobs": {"running": 0, "done": 8, "error": 0, "canceled": 0}
}
}
FieldDescription
storage_bytes, total_events, part_countTotals over the indexes
merges_running, runs_to_mergeMerges under way and sorted runs still to be merged, over the indexes; the store is quiet when both are 0. POST /api/v1/indexes/{index}/compact merges an index at once
filter_bytesThe part of storage_bytes that the token filters take; each index entry has it too
oldest_event, newest_eventTimes of the oldest and newest event, in whole seconds; absent without events
indexesOne entry per index, as in GET /api/v1/indexes
jobsJobs the server keeps, by state

Like a query, status and stats first write the events ingested so far, so the counts include them.

GET /api/v1/config​

Returns the running configuration. Needs admin scope when authentication is on.

curl -s localhost:3100/api/v1/config

The top-level keys of data are listen, data_dir, retention, log_level, storage, query, ingest, http, syslog, tls, auth and profiles. Durations in query (sync_timeout, job_ttl) and http are integer nanoseconds; the others are text such as 30d or 5m0s. See Configuration for each section.

PATCH /api/v1/config​

Merges a JSON object into the running configuration, validates the result and applies it the same way a SIGHUP reload does. Needs a root key when authentication is on.

Accepted top-level keys: retention, log_level, listen, query, ingest, storage, http, syslog. Nested objects merge member by member. Any other key, an empty patch, a value of the wrong type, or a config that fails validation answers 400 VALIDATION_ERROR.

curl -s -X PATCH localhost:3100/api/v1/config \
-H 'Content-Type: application/json' \
-d '{"log_level": "debug", "query": {"default_result_limit": 500}}'

The response holds the resulting configuration in data.config. When a changed setting takes effect only after a restart, data.restart_required names it: a patch of {"retention": "30d", "listen": "0.0.0.0:3100"} answers with "restart_required": ["listen", "retention"].

These settings take effect at once: log_level, query.sync_timeout, query.default_result_limit, query.max_result_limit, query.max_query_length, ingest.mode, ingest.max_batch_size, ingest.max_line_bytes, ingest.es_compat.enabled, ingest.splunk_hec.enabled, ingest.splunk_hec.require_token, http.shutdown_timeout, and the syslog index, sourcetype, default_timezone, default_hostname, batch_size and batch_timeout. ingest.limits.* and ingest.es_compat.advertised_version are accepted without a restart notice but take effect at the next start. Every other change is listed in restart_required.

The change lives only in the running process. Edit the config file as well to keep it after a restart.

API keys​

These endpoints exist only when authentication is on; otherwise they answer 404 NOT_FOUND. They all need a root key; any other key answers 403 FORBIDDEN.

POST /api/v1/auth/keys​

curl -s -X POST localhost:3100/api/v1/auth/keys \
-H 'Authorization: Bearer <root-token>' \
-H 'Content-Type: application/json' \
-d '{"name": "filebeat", "scope": "ingest", "expires_in": "90d", "description": "edge shipper"}'
FieldDescription
nameKey name (required)
scopeingest, query, admin or full (default full)
expires_inA Go duration (720h) or a count of days, weeks or years (30d, 4w, 1y); never or empty for no expiry
descriptionFree text

The response (201) holds the key and its plaintext token, which is shown only this once:

{
"data": {
"id": "ak_EQcWtLGOrPfq",
"name": "filebeat",
"prefix": "lynx_ak_oGOl",
"scope": "ingest",
"description": "edge shipper",
"expires_at": "2027-02-15T16:47:01.300723+01:00",
"is_root": false,
"created_at": "2026-11-17T15:47:01.326646Z",
"last_used_at": "0001-01-01T00:00:00Z",
"token": "lynx_ak_oGOlzEijPa2K594bYWZcLmkvVZaeEnuv",
"api_key": "ak_EQcWtLGOrPfq:lynx_ak_oGOlzEijPa2K594bYWZcLmkvVZaeEnuv"
}
}

api_key is id:token, the value to base64-encode for the ApiKey scheme. A key without expiry has expires_at 0001-01-01T00:00:00Z, and a key never used has that last_used_at. A missing name, an unknown scope or an unparsable expires_in answers 400 VALIDATION_ERROR.

GET /api/v1/auth/keys​

Lists keys as {"data": {"keys": [...]}} with the same fields minus token and api_key.

DELETE /api/v1/auth/keys/{id}​

Revokes a key and answers 204. An unknown ID answers 404 NOT_FOUND; revoking the last root key answers 409 LAST_ROOT_KEY.

POST /api/v1/auth/rotate-root​

Replaces the root key used to call it:

{
"data": {
"id": "rk_9EB9RHIWv61H",
"name": "root",
"prefix": "lynx_rk_rAQg",
"token": "lynx_rk_rAQg54faOY891uz4SE3hoLZXuvHQD7eb",
"is_root": true,
"created_at": "2026-11-17T15:47:21.381866Z",
"revoked_key_id": "rk_kZCEAKYUaACk"
}
}

The token of the replaced key stops working at once.

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

Profiling​

The Go runtime profiles are served under /api/v1/debug/pprof/: the index, profile, trace, heap, allocs, goroutine, mutex, block, threadcreate, cmdline and symbol. They follow API authentication like other /api/v1 routes; any valid key can read them.

go tool pprof http://localhost:3100/api/v1/debug/pprof/profile?seconds=30

mutex and block profiles hold samples only when the server runs with --profile-runtime.