Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/admbe/FluxOp/llms.txt

Use this file to discover all available pages before exploring further.

Flux exposes two lightweight endpoints for runtime diagnostics and principal introspection. /api/health requires no authentication and is safe to call from infrastructure probes. /api/session also requires no authentication — it always returns the caller’s current identity and data-currency state, making it the authoritative source for both unauthenticated login redirects and authenticated shell state.

​
GET /api/health

Returns the runtime status of the Flux API, its analytical store, and the operational back-end. No authentication is required — this endpoint is designed to be called by load-balancer health probes and uptime monitors. Authentication: None

​
Response fields

FieldTypeDescription
statusstringAlways "ok" when the process is serving.
servicestringAlways "flux-api".
versionstringFastAPI application version (e.g. "2.0.0").
databasestringAnalytical store engine — always "duckdb".
operationalDatabasestringControl-plane back-end ("postgresql", "duckdb", or empty if disabled).
authModestringActive authentication mode ("mock", "entra", or "none").
analyticsReadModestringWhether the instance reads from the live mutable store or a published snapshot ("direct" or "snapshot").
analyticsSnapshotVersionstring | nullPresent only when analyticsReadMode is "snapshot". The version token of the currently-loaded snapshot, or null if no snapshot has been adopted yet.

​
Example

curl https://your-flux-host/api/health

{
  "status": "ok",
  "service": "flux-api",
  "version": "2.0.0",
  "database": "duckdb",
  "operationalDatabase": "postgresql",
  "authMode": "entra",
  "analyticsReadMode": "snapshot",
  "analyticsSnapshotVersion": "20240610T0412Z"
}

​
GET /api/session

Returns the caller’s identity and the data-currency provenance block used by the shell. The endpoint always responds — it does not enforce authentication — making it safe to call before login to check whether the user is signed in. Authenticated callers receive a full identity payload; unauthenticated callers receive the same response shape with user set to null. Authentication: None — returns the caller’s current authentication state regardless of session validity.

​
Response fields

The response is a flat object. The identity fields are provided by App Service Authentication (X-MS-CLIENT-PRINCIPAL) and are mapped by Flux’s AuthService.
FieldTypeDescription
authenticatedbooleantrue when a valid principal was resolved; false for unauthenticated requests.
authModestringActive authentication mode ("mock", "entra", or "none").
userobject | nullnull when unauthenticated. Present when authenticated.
user.idstringObject ID of the authenticated user.
user.displayNamestringDisplay name from Entra ID.
user.emailstringPrincipal email address, if available from the claims payload.
user.rolesstring[]Flux roles assigned to the principal, e.g. ["reader"] or ["reader", "admin"].
permissions.canReadbooleantrue when the principal holds the reader or admin role.
permissions.canManageIntegrationsbooleantrue when the principal holds the admin role.
dataCurrency.modestringMatches analyticsReadMode from /api/health: "direct" or "snapshot".
dataCurrency.snapshotVersionstring | nullVersion token of the snapshot this instance is currently serving. Present only in snapshot mode.
dataCurrency.latestVersionstring | nullVersion token of the most-recently approved snapshot, read from the operational store. May differ from snapshotVersion if a newer snapshot has been approved but not yet adopted.
dataCurrency.generatedAtstring | nullISO 8601 timestamp at which the latest snapshot was generated.
dataCurrency is read from the operational store on a best-effort basis. If the operational store is unreachable the dataCurrency block will contain only mode and all other fields will be absent — the session response itself will still return 200.

​
Example

{
  "authenticated": true,
  "authMode": "entra",
  "user": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "displayName": "Alice Nguyen",
    "email": "alice@contoso.com",
    "roles": ["reader", "admin"]
  },
  "permissions": {
    "canRead": true,
    "canManageIntegrations": true,
    "canSyncIntegrations": true
  },
  "dataCurrency": {
    "mode": "snapshot",
    "snapshotVersion": "20240610T0412Z",
    "latestVersion": "20240610T0412Z",
    "generatedAt": "2024-06-10T04:12:00Z"
  }
}

​
Error responses

Both endpoints return standard FastAPI error shapes. If the analytical store is busy during a long-running writer operation, reads will receive: 
{
  "detail": "The analytical database is temporarily busy while a synchronization write completes. Retry shortly.",
  "waitedSeconds": 4.2
}
The HTTP status is 503 Service Unavailable with a Retry-After: 15 header.

Build docs developers (and LLMs) love

Get started for freeTalk to us