Skip to main content

Security and Operations Examples

Send authenticated requests​

hlquery accepts an API key header or a bearer token:

curl -H "X-API-Key: $HLQUERY_API_KEY" \
  http://localhost:9200/collections

curl -H "Authorization: Bearer $HLQUERY_API_KEY" \
  http://localhost:9200/collections

Avoid placing keys in URLs, committed scripts, shell history, or screenshots.

Create a read-only, tenant-scoped key​

Use the administrator token only for key management:

curl --fail-with-body -X POST http://localhost:9200/keys \
  -H "X-API-Key: $HLQUERY_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Tenant 42 storefront search",
    "rate_limit_per_minute": 120,
    "scopes": {
      "products": {
        "actions": ["search"],
        "embedded_filters": "tenant_id:=42 && is_public:true"
      }
    }
  }'

The key value returned at creation time is a secret. Store it in a secret manager and give applications only the least-privileged key they need.

Kubernetes-style probes​

Use liveness and readiness for different questions:

curl --fail --silent --show-error http://localhost:9200/health
curl --fail --silent --show-error http://localhost:9200/ready

/health checks that the service responds; /ready is the better gate before sending traffic during startup.

Inspect server state​

curl http://localhost:9200/status
curl http://localhost:9200/stats
curl http://localhost:9200/metrics.json
curl http://localhost:9200/connections
curl http://localhost:9200/cache
curl http://localhost:9200/config-files
curl http://localhost:9200/debug/counters

Some deployments require an administrator key for diagnostic routes. Prefer /metrics when a Prometheus-compatible text response is needed and /metrics.json for scripts.

Check storage before maintenance​

curl -H "X-API-Key: $HLQUERY_ADMIN_KEY" \
  http://localhost:9200/admin/storage_status

curl -X POST -H "X-API-Key: $HLQUERY_ADMIN_KEY" \
  http://localhost:9200/flush

/flush changes server state. Restrict it to administrative automation and do not use it as a routine health probe.

Make curl failures visible​

Use --fail-with-body so HTTP errors return a non-zero exit status while still printing the response body:

response_file=$(mktemp)
if ! curl --silent --show-error --fail-with-body \
  --output "$response_file" \
  http://localhost:9200/collections/products; then
  echo "hlquery request failed" >&2
  cat "$response_file" >&2
  rm -f "$response_file"
  exit 1
fi
cat "$response_file"
rm -f "$response_file"

Application clients should also set a timeout, log the response status and a request identifier when available, and retry only idempotent operations unless the write uses a stable document ID.

curl http://localhost:9200/links
curl http://localhost:9200/links/ping
curl http://localhost:9200/collections/distributed

To compare execution modes for a query:

curl -i \
  "http://localhost:9200/collections/products/documents/search?q=keyboard&distributed=off"
curl -i \
  "http://localhost:9200/collections/products/documents/search?q=keyboard&distributed=on"

Inspect X-HLQ-Execution-Mode in the response headers. See System Endpoints for maintenance and cluster-link request bodies.