Skip to main content

OpenAPI Spec Index

Zen Mesh publishes OpenAPI 3.0.3 specifications covering the public and app-facing API surfaces.

Status: PUBLIC_CONTRACT_DRAFT. OpenAPI specs are maintained alongside docs but may trail the current runtime. See per-spec status below.

Available specs​

SpecFileLinesCoverageStatusIn Docusaurus
KubeZen Back APIapi-specifications/zen-back.v1.yaml1,265Backend public API (targets/endpoints/flows/deliveries)DRAFT — wired in openapi-docs pluginYes
Zen Mesh User APIstatic/openapi/zen-mesh-user-api.v1.yaml2,021Same surface with code samples (curl, Python, JS)DRAFT — static file only, not plugin-renderedNo (static)
BFF APIsrc/saas/bff/openapi/zen-bff.v1.yaml—Dashboard BFF surfaceINTERNAL_ONLY — outside docs repoNo

Coverage table​

Endpoint groupDocumented pageOpenAPI (zen-back)OpenAPI (user)Implementation routeHTTP methodsStatus
Health—YesYes/health, /readyGETWIRED_SANDBOX
Tenants—YesYes/tenants/{tid}GETWIRED_SANDBOX
Clusters/Planes—YesYes/tenants/{tid}/clustersGET, POSTWIRED_SANDBOX
Targets (destinations)Targets APIYesYes/tenants/{tid}/destinationsGET, POST, PATCH, DELETEWIRED_SANDBOX
Endpoints (ingesters)Endpoints APIYesYes/tenants/{tid}/ingestersGET, POST, PUT, DELETEWIRED_SANDBOX
Flows (delivery-flows)Flows APIYesYes/tenants/{tid}/delivery-flowsGET, POST, PUT, DELETEWIRED_SANDBOX
Delivery AttemptsDelivery Attempts APIPartialPartial/tenants/{tid}/deliveriesGETWIRED_SANDBOX
DLQDLQ API——/deliveries?status=failedGETWIRED_SANDBOX
RetryRetry API——/events/{eid}/retry, /retry/batchPOSTWIRED_SANDBOX
ReplayReplay APIPartialPartial/deliveries/{did}/replayPOSTWIRED_SANDBOX
TracesTraces API——/deliveries?event_id=GETWIRED_SANDBOX
Saved PayloadsSaved Payloads API——/saved-payloadsGET, POST, PUT, DELETEWIRED_SANDBOX
EvidenceEvidence APIPartialPartial/evidence/..., /sources/.../evidenceGETWIRED_SANDBOX
API KeysAuthenticationPartialPartial/api-keysGET, POST, DELETEWIRED_SANDBOX
Webhook endpoints———/webhooks/{provider}POSTWIRED_SANDBOX
Integrations——Yes/integrationsGET, POSTWIRED_SANDBOX
Channels (bridge)—YesYes/bridge/.../channelsGETWIRED_SANDBOX

Spec coverage gaps​

The following documented endpoints are not covered by any published OpenAPI spec:

Endpoint groupMissing from both specs
DLQUses deliveries shared endpoint — no separate spec entry
RetryNot covered
TracesShared deliveries endpoint — no separate spec entry
Saved PayloadsNot covered
Fabric AdaptersBFF-only (not in this repo)

How to validate a spec​

# Validate with spectral
npx spectral lint api-specifications/zen-back.v1.yaml

# Compare spec against docs routes
curl -s https://raw.githubusercontent.com/zenmesh/zen-platform-hermes/main/api-specifications/zen-back.v1.yaml \
  | grep -E '^\s+/' | head -40

# Generate spec diff
npx oasdiff changelog api-specifications/zen-back.v1.yaml <previous-version>.yaml

How to compare spec with route inventory​

  1. Fetch the current spec: curl https://raw.githubusercontent.com/zenmesh/zen-platform-hermes/main/api-specifications/zen-back.v1.yaml
  2. Compare against documented routes in API Overview or the API Reference.
  3. Generate diff using oasdiff or similar tool.

Non-claims​

  • OpenAPI specs are maintained alongside docs but may trail the current runtime.
  • The User API spec (static/openapi/) is provided as a static reference but is not rendered via the Docusaurus OpenAPI plugin.
  • The BFF spec is NOT in this repository; it is internal to the dashboard app.
  • Specs are DRAFT status unless explicitly marked PUBLIC_CONTRACT_STABLE.
  • Several endpoint groups (Retry, Saved Payloads, Traces, DLQ) are not covered by any published spec.
  • Coverage varies by HTTP method even within covered groups.