Health and HTTP API

The complete current native API is published as an OpenAPI document generated from the same website build. Use the problem-code field guide to interpret RFC 9457 failures and retry guidance.

Browse the same contract as an operation-by-operation Native API reference.

For a runnable sequence covering scoped token creation, cursor pagination, TUS upload, idempotency, If-Match, and RFC 9457 problems, use the Native API quickstart.

Health probes

Request	Use	Dependency work
GET /api/v1/health/live	Supervisor liveness	Does not consult database or blob storage
GET /api/v1/health/ready	Startup/load-balancer readiness	Checks required core dependencies
GET /api/v1/health	Compatibility representation	Prefer /live or /ready for new probes
POST /api/v1/health/integrity	Interactive authenticated operator diagnostic	Bounded database, blob, and maintenance summary

Do not schedule the integrity endpoint as a probe. It is single-flight, accepts no body, requires an authorized same-origin operator session, and can return HTTP 200 with a degraded or unhealthy diagnostic result.

API usage rules

• Browser operations use the same-origin session and origin protections.
• Scripts use a narrowly scoped, expiring personal access token.
• Never place credentials in URLs.
• Retain the X-Request-Id response header in client logs without recording credentials. On an RFC 9457 failure, ProblemDetails.requestId carries the same correlation value.
• Every operation can return 421 when the request authority or direct peer is outside Jiandu's configured ingress boundary; fix the deployment path instead of retrying unchanged.
• Respect idempotency requirements and the difference between durable acceptance and completed processing.
• Generate clients from the exact OpenAPI document shipped with the release; do not assume main matches an older server.