Skip to content

Endpoints

  • Liveness

    Is the process alive?

  • Readiness

    Can the service accept traffic?

  • Diagnostics

    What needs operator attention?

Choose a health or diagnostic endpoint by the question it answers.

Find endpoint paths, access requirements and response fields below.

Next: Monitoring guide

All operational and health endpoints exposed by IdentityScribe. For guidance on using these in practice, see Health and Monitoring.

ANONYMOUS BY DEFAULTOBSERVE · SIGNED INOBSERVE · WRITE ACCESSOrchestratorKubernetes/readyz /livez/startedz /healthzPrometheus/metricsDeploy script/observe/convergenceingest + indexes doneOperator/observe/statusdoctor · channelsAdmin/observe/configfull exportprobesscrapeswaits forinvestigatesreads
ANONYMOUS BY DEFAULTOBSERVE · SIGNED INOBSERVE · WRITE ACCESSOrchestratorKubernetes/readyz /livez/startedz /healthzPrometheus/metricsDeploy script/observe/convergenceingest + indexes doneOperator/observe/statusdoctor · channelsAdmin/observe/configfull exportprobesscrapeswaits forinvestigatesreads
Use health probes for process and traffic checks, and authenticated Observe for operational detail and strict convergence.
PathDescription
/livezLiveness — is the process alive?
/readyzReadiness — can it safely receive traffic?
/startedzStartup — have services initialized?
/healthzCombined — all health checks

Readiness does not mean initial ingest and index work are complete; wait for /observe/convergence for that.

PathDescription
/observe/healthCombined health
/observe/health/liveLiveness probe
/observe/health/readyReadiness probe
/observe/health/startedStartup probe
/observe/health/check/{name}Individual check by name
PathDescription
/metricsPrometheus scrape endpoint (OpenTelemetry-backed)

The root path / no longer serves metrics — use /metrics explicitly.

These endpoints expose on-demand insights as cached JSON. They cover data that would explode metrics cardinality if exposed as Prometheus gauges. Observe JSON endpoints require an operator session or accepted credential by default; curl examples below use a bearer token.

PathDescription
/observeOpenAPI documentation (HTML UI + JSON/YAML spec)
/observe/statusBasic status
/observe/convergenceStrict initial ingest and required index convergence
/observe/channelsChannel and socket discovery with runtime bindings
/observe/configResolved configuration (secrets redacted; requires Observe write access)
/observe/doctorHealth report with threshold checks and recommendations
/observe/servicesService lifecycle status (state, uptime, failures)
/observe/pressureSaturation metrics (queue/task/memory pressure)
/observe/signalsGolden signals summary
/observe/indexesIndex build status
/observe/hintsPersisted query hints (redact=false requires Observe write access)
/observe/signaturesQuery signatures
/observe/stats/queriesSlow query analysis (requires pg_stat_statements)
/observe/stats/valuesValue size statistics per entry type and attribute
/observe/stats/entriesEntry blob size percentiles per entry type
/observe/stats/eventsEvent rate windows (dashboard-friendly buckets)
/observe/stats/ingestIngest lag and checkpoint positions
/observe/stats/historyRetained metric history for Observe panels
/observe/performance-insight/exportRedacted performance insight report for support handoff
/observe/performance-insight/export/fullFull performance insight report for trusted local investigation
/observe/mcpMCP server for AI assistants; follows Observe access rules; when it runs on its own socket, its own MCP access rules replace them if set (see MCP Channel)

Use /observe for interactive API docs and /observe/status for machine-readable status.

Stats history uses the same read access tier as the other Observe stats endpoints. The redacted performance insight export also requires authenticated Observe/API read access. The full performance insight export requires Observe write access because it includes trusted local investigation details.

Returns enabled channels, sockets, and runtime bindings. Useful for service discovery and debugging port assignments.

{
"channels": {
"ldap": {
"enabled": true,
"running": true,
"bindings": [
{ "host": "0.0.0.0", "configuredPort": 0, "actualPort": 10389, "ssl": false, "url": "ldap://0.0.0.0:10389" }
]
},
"rest": { "enabled": true, "sockets": ["@default"], "basePath": "/api" }
},
"sockets": {
"@default": { "host": "0.0.0.0", "configuredPort": 8080, "actualPort": 8080, "ssl": false, "url": "http://localhost:8080" }
},
"request": { "socket": "@default", "host": "localhost", "port": 8080, "scheme": "http" }
}

Each entry in channels.ldap.bindings[] and sockets reports both ports:

"configuredPort": 0, "actualPort": 10389
  • sockets.<name>.url — auto-generated base URL (proxy-aware for the current socket via X-Forwarded-* headers)
  • request — shows how the current request’s host and scheme were detected

Returns resolved configuration with secret values replaced by <REDACTED>. It requires Observe write access. The same redaction applies to the --printconfig CLI flag.

Accept HeaderResponse
application/json (default)JSON with config and timestamp fields
text/plainConfiguration as formatted JSON text
Terminal window
# Plain text
curl -H "Authorization: Bearer <token>" -H "Accept: text/plain" http://localhost:8080/observe/config

Config is computed once on first request. Responses are sent with Cache-Control: no-store. Comments from your configuration files are not included. The response excludes JVM internal paths (java.*, jdk.*, sun.*, org.graalvm.*).

Returns per-service status with uptime, startup duration, tags, and failure causes.

{
"services": [
{ "id": "Scribe.user", "name": "Scribe", "state": "running", "healthy": true, "uptime_seconds": 3600, "startup_seconds": 2.5 },
{ "id": "Database.System", "name": "Database.System", "state": "failed", "healthy": false, "failure": "Connection refused" }
],
"summary": { "total": 8, "healthy": 7, "unhealthy": 1, "restarts_5m": 3 }
}

Returns threshold-based health checks, per-service status, and actionable recommendations. The services.down check names which services are down by ID. The recommendations array contains prioritized hints.

Returns saturation metrics with per-entry-type breakdown. The query_permit_queue field counts threads waiting for query permits — non-zero values indicate contention. Omits metrics with non-finite values (e.g., task pressure before any tasks complete).

The /observe/stats/* endpoints execute direct database queries. They’re designed for investigation and dashboard population, not continuous scraping.

Caching: Two tiers protect the database:

  • In-process cache (30s TTL) for /values, /entries, /ingest
  • HTTP Cache-Control: max-age=30, private on all responses
  • /events uses client-side caching only (parameterized by since)

Row limits: Queries return at most 100 rows by default.

since parameter (/observe/stats/events):

  • ISO-8601 timestamps: 2026-01-01T00:00:00Z
  • Duration strings: 1h, 24h, 7d
  • Invalid input returns 400 (future timestamps, negative durations, unparseable values)

Precision: Numeric byte fields (avgBytes, p50Bytes, etc.) use double to preserve fractional values.