Endpoints

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

Append ?verbose for detailed output.

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.

Use /observe for interactive API docs. For machine-readable status, use /observe/status.

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