Admin, Health, and Stats

May 19, 2026 · View on GitHub

This document covers administrative operations, health monitoring, and server statistics for Fluree deployments.

Health Endpoints

GET /health

Basic health check:

curl http://localhost:8090/health

Response (200 OK):

{
  "status": "ok",
  "version": "0.1.0"
}

Use this endpoint for:

  • Load balancer health checks
  • Container orchestration (Kubernetes liveness/readiness probes)
  • Monitoring systems

Kubernetes Example:

livenessProbe:
  httpGet:
    path: /health
    port: 8090
  initialDelaySeconds: 5
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /health
    port: 8090
  initialDelaySeconds: 5
  periodSeconds: 5

Statistics Endpoints

GET /v1/fluree/stats

Server statistics:

curl http://localhost:8090/v1/fluree/stats

Response:

{
  "uptime_secs": 3600,
  "storage_type": "file",
  "indexing_enabled": true,
  "cached_ledgers": 3,
  "version": "0.1.0"
}
FieldDescription
uptime_secsServer uptime in seconds
storage_typeStorage mode (memory or file)
indexing_enabledWhether background indexing is enabled
cached_ledgersNumber of ledgers currently cached
versionServer version

Diagnostic endpoints

GET /v1/fluree/whoami

Diagnostic endpoint for debugging Bearer tokens.

  • If no token is present, returns token_present=false.
  • If a token is present, attempts to cryptographically verify it using the same verification logic as authenticated endpoints (embedded-JWK Ed25519 and JWKS/OIDC when enabled/configured).
  • On verification failure, returns verified=false and includes an error string. Some unverified decoded fields may be included for debugging.
curl http://localhost:8090/v1/fluree/whoami \
  -H "Authorization: Bearer eyJ..."

CLI discovery

GET /.well-known/fluree.json

Discovery document used by the CLI when adding a remote (fluree remote add) or when running fluree auth login with no configured auth type.

Standalone fluree-server returns:

  • {"version":1,"api_base_url":"/v1/fluree"} when no auth is enabled
  • {"version":1,"api_base_url":"/v1/fluree","auth":{"type":"token"}} when any server auth mode is enabled (data/events/admin)

OIDC-capable implementations can return auth.type="oidc_device" plus issuer, client_id, and exchange_url. The CLI treats oidc_device as "OIDC interactive login": it uses device-code when the IdP supports it, otherwise authorization-code + PKCE (localhost callback).

Implementations MAY also return api_base_url to tell the CLI where the Fluree API is mounted (for example, when the API is hosted under /v1/fluree or on a separate data subdomain).

See Auth contract (CLI ↔ Server) for the full schema and behavior.

GET /v1/fluree/info/<ledger...>

Get detailed ledger metadata:

curl "http://localhost:8090/v1/fluree/info/mydb:main"

Minimum fields used by the Fluree CLI:

  • t (required)
  • commitId (required for fluree push when t > 0)

Optional query params:

  • By default, ledger-info returns the full novelty-aware stats view, including real-time datatype details and class ref edges.
  • realtime_property_details=false: switch ledger-info to the lighter fast novelty-aware stats layer that keeps counts current but skips lookup-backed class/ref enrichment.
  • include_property_datatypes=false: omit stats.properties[*].datatypes when you want a smaller payload.
  • include_property_estimates=true: include index-derived ndv-values, ndv-subjects, and selectivity fields under stats.properties[*].

Example:

curl "http://localhost:8090/v1/fluree/info/mydb:main"

Response:

{
  "ledger": "mydb:main",
  "t": 150,
  "commitId": "bafybeig...commitT150",
  "indexId": "bafybeig...indexRootT145",
  "commit": {
    "commit_id": "bafybeig...commitT150",
    "t": 150
  },
  "index": {
    "id": "bafybeig...indexRootT145",
    "t": 145
  },
  "stats": {
    "flakes": 12345,
    "size": 1048576,
    "indexed": 145,
    "properties": {
      "ex:name": {
        "count": 3,
        "last-modified-t": 150
      }
    },
    "classes": {
      "ex:Person": {
        "count": 2,
        "properties": {
          "ex:worksFor": {
            "count": 2,
            "refs": { "ex:Organization": 2 },
            "ref-classes": { "ex:Organization": 2 }
          },
          "ex:name": {}
        },
        "property-list": ["ex:name", "ex:worksFor"]
      }
    }
  }
}

Stats freshness (real-time vs indexed)

  • Real-time (includes novelty):

    • commit and top-level t reflect the latest committed head.
    • stats.flakes and stats.size are derived from the current ledger stats view (indexed + novelty deltas).
    • stats.classes[*].properties / property-list will include properties introduced in novelty, even when the update does not restate @type.
    • stats.properties[*].datatypes is real-time by default.
    • stats.classes[*].properties[*].refs is real-time by default.

  • As-of last index:

    • stats.indexed is the last index (t). If commit.t > indexed, the index is behind the head.
    • NDV-related fields in stats.properties[*] (ndv-values, ndv-subjects) and selectivity derived from them are only as current as the last index refresh, so they are omitted by default and only included when include_property_estimates=true.
    • stats.properties[*].datatypes are omitted only when include_property_datatypes=false is requested.
    • Class property ref-edge counts (stats.classes[*].properties[*].refs) fall back to the lighter indexed/fast path only when realtime_property_details=false is requested.

GET /v1/fluree/exists/<ledger...>

Check if a ledger exists:

curl "http://localhost:8090/v1/fluree/exists/mydb:main"

Response:

{
  "ledger": "mydb:main",
  "exists": true
}

This is a lightweight check that only queries the nameservice without loading the ledger.

Administrative Operations

POST /v1/fluree/create

Create a new ledger:

curl -X POST http://localhost:8090/v1/fluree/create \
  -H "Content-Type: application/json" \
  -d '{"ledger": "mydb:main"}'

Response (201 Created):

{
  "ledger": "mydb:main",
  "t": 0,
  "tx-id": "fluree:tx:sha256:abc123...",
  "commit": {
    "commit_id": "bafybeig...commitT0"
  }
}

Authentication: When --admin-auth-mode=required, requires Bearer token from a trusted issuer.

See Admin Authentication for details.

POST /v1/fluree/drop

Drop an entire ledger (every branch under the name, plus @shared/dicts/ in hard mode) or, as a fallback, a graph source with the same name:

# Soft drop the whole "mydb" ledger (retract every branch)
curl -X POST http://localhost:8090/v1/fluree/drop \
  -H "Content-Type: application/json" \
  -d '{"ledger": "mydb"}'

# Hard drop (delete every branch's artifacts + @shared/dicts - IRREVERSIBLE)
curl -X POST http://localhost:8090/v1/fluree/drop \
  -H "Content-Type: application/json" \
  -d '{"ledger": "mydb", "hard": true}'

ledger accepts the bare ledger name. Any branch-qualified form (including "mydb:main") is rejected — use POST /drop-branch to drop a single branch.

Response:

{
  "ledger_id": "mydb",
  "status": "dropped",
  "files_deleted": 73,
  "branches_dropped": ["mydb:feature-x", "mydb:dev", "mydb:main"]
}
StatusDescription
droppedSuccessfully dropped (aggregate across branches)
already_retractedEvery branch was previously retracted
not_foundNo nameservice record exists for the name

Authentication: When --admin-auth-mode=required, requires Bearer token from a trusted issuer.

Drop Modes:

  • Soft (default): Marks every branch retracted in the nameservice; artifacts remain and aliases stay reserved.
  • Hard: Deletes per-branch storage artifacts and @shared/dicts/, then purges the nameservice records so the ledger name can be reused. Branches are dropped leaf-first; on a per-branch nameservice failure the operation aborts with 500 before touching parents or shared cleanup (retry is safe — each step is idempotent).

If no nameservice record is found for the name, the endpoint tries the same name as a graph source on branch main. Truly orphaned storage with no nameservice pointer is not swept by /drop.

See Dropping Ledgers and POST /drop for the full reference.

API Specification

GET /swagger.json

OpenAPI specification:

curl http://localhost:8090/swagger.json

Returns the OpenAPI 3.0 specification for the server API.

Monitoring Best Practices

1. Use Health Checks

Configure your infrastructure to poll /health:

# Simple monitoring script
while true; do
  curl -sf http://localhost:8090/health > /dev/null || echo "ALERT: Server unhealthy"
  sleep 10
done

2. Track Server Stats

Periodically collect statistics:

curl http://localhost:8090/v1/fluree/stats | jq .

Key metrics to track:

  • uptime_secs: Detect restarts
  • cached_ledgers: Cache efficiency

3. Monitor Ledger Health

For each critical ledger:

curl "http://localhost:8090/v1/fluree/info/mydb:main" | jq .

Watch for:

  • Index lag (commit.t vs index.t)
  • Unexpected state changes

4. Set Up Alerts

Alert conditions:

  • Health check failures
  • Server restarts (low uptime)
  • High index lag

5. Log Analysis

Enable structured logging:

fluree-server --log-level info 2>&1 | jq .

Search for:

  • level: "error" - Errors
  • level: "warn" - Warnings
  • Slow query patterns

Security Considerations

Protect Admin Endpoints

In production, enable admin authentication:

fluree-server \
  --admin-auth-mode required \
  --admin-auth-trusted-issuer did:key:z6Mk...

This protects /v1/fluree/create, /v1/fluree/drop, and other admin-protected API routes from unauthorized access.

Limit Endpoint Exposure

Consider network-level restrictions:

  • Health endpoint: Available to load balancers
  • Stats endpoint: Internal monitoring only
  • Admin endpoints: Restricted access

Audit Logging

Admin operations are logged. Monitor for:

  • Ledger creation
  • Ledger drops
  • Authentication failures