01 · START

Quickstart

Audience: operators driving XERJ's native REST API on port 8080. This page creates indices with explicit field mappings and ingests through turbo-ingest — the low-level path. It is not the agent onramp, and it deliberately does not cover xerj autoindex.

AI agents start here instead: /llms.txt (install → run → index → query, written for a machine) or the agent quickstart — both use the Elasticsearch-compatible surface on 9200.
Just want a folder to become searchable? xerj autoindex <folder> writes the mappings for you — the zero-config indexing recipe.

Start the server, create an index, ingest some data, run a query. Sixty seconds if you already have a binary.

1 · Start the server

XERJ is a single static binary and needs no config file to start. Run it in dev mode — --insecure turns off TLS and API-key auth, which is what lets the bare curls in the rest of this page work:

$ xerj --insecure --data-dir ./data

Auth is on by default. Any node started without --insecure — including one started from a config file, and including the config in the install guide — mints an admin key on first boot, prints it, and writes it to <data_dir>/admin.key. Every client then has to send it, the CLI included:

$ xerj --config xerj.toml            # see /docs/config for the keys
$ export XERJ_API_KEY="$(cat ./data/admin.key)"    # data_dir defaults to ./data
$ curl -s -H "Authorization: ApiKey $XERJ_API_KEY" http://localhost:8080/v1/health
$ xerj autoindex ~/my-project        # picks up XERJ_API_KEY, or take --api-key

2 · Create an index

Indices are created explicitly with a field mapping so encoders can be chosen at write time.

$ curl -sX PUT http://localhost:8080/v1/indices/logs \
     -H 'Content-Type: application/json' \
     -d '{
       "fields": {
         "@timestamp": "date",
         "service":    "keyword",
         "level":      "keyword",
         "host":       "keyword",
         "message":    "text"
       }
     }'

3 · Ingest at line rate

Two ingest paths. turbo-ingest takes NDJSON and parallel-tokenizes across cores.

$ curl -sX POST http://localhost:8080/v1/indices/logs/turbo-ingest \
     -H 'Content-Type: application/x-ndjson' \
     --data-binary @nginx.jsonl

4 · Query

Unified search endpoint — full-text, term, range, KNN, hybrid. Everything shares one planner.

$ curl -sX POST http://localhost:8080/v1/indices/logs/search \
     -H 'Content-Type: application/json' \
     -d '{
       "query": {
         "bool": {
           "filter": [
             { "term":  { "level": "error" } },
             { "range": { "@timestamp": { "gte": "now-1h" } } }
           ]
         }
       },
       "aggs": {
         "by_service": { "terms": { "field": "service", "size": 10 } }
       }
     }'

5 · Scrape metrics

Prometheus text format. Scrape-friendly. No sidecar.

$ curl -s http://localhost:8080/v1/metrics | head

Source · engine/README.md · engine/crates/xerj-api/src/router.rs

◀ PREVOverview

NEXT ▶Install