Endpoints

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

Readiness is not strict sync/index completion. Use /observe/convergence when a script must wait for all initial ingest and required index work to finish.

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.

Use /observe for interactive API docs. For machine-readable status, use /observe/status. For deployment waits that require all long-running ingest and index work to finish, use /observe/convergence.

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" }
}

• channels.ldap.bindings[].actualPort — the runtime-assigned port (matters when configuredPort is 0)
• 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 all password fields replaced by <REDACTED>. Equivalent to the --printconfig CLI flag, but accessible at runtime.

# Plain text
curl -H "Authorization: Bearer <token>" -H "Accept: text/plain" http://localhost:8080/observe/config

Config is computed once on first request. Responses include Cache-Control: max-age=3600, private. 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.