API Reference

The Zen Mesh API provides REST, MCP, and WebSocket surfaces for the Configuration Contract. This page indexes all publicly documented API surfaces.

Status: PUBLIC_CONTRACT_DRAFT. Individual API groups carry their own maturity status. See API Status Matrix for per-group details.

API Overview

• API Overview — Canonical API taxonomy: surface groups, maturity legend, public-contract boundary, terminology mapping, non-claims
• API Status Matrix — Per-group maturity, audience, base path, auth model, read/write support, OpenAPI coverage, UI mapping, and non-claims
• Authentication and API Keys — Auth models: Bearer JWT, API key, HMAC, session, MCP auth, tenant scoping, scopes, write enablement
• Errors and Problem Details — RFC 9457 Problem Details format, status codes, validation, scope denial, idempotency conflict
• Pagination and Filtering — Cursor-based and offset-based pagination, query filters, defaults, limits
• Idempotency — Idempotency-Key header, deduplication window, safe retry, endpoint coverage
• Write Safety Model — Authorization, scopes, object permissions, idempotency, audit, fail-closed, MCP write safety
• API Versioning and Compatibility — URL-based versioning, compatibility policy, spec maintenance

Runtime APIs

• Targets API — Delivery destinations (internal model: destinations). Status: WIRED_SANDBOX
• Endpoints API — Webhook source receivers (internal model: ingesters). Status: WIRED_SANDBOX
• Flows API — Declarative delivery contracts connecting endpoints to targets. Status: WIRED_SANDBOX
• Delivery Attempts API — One delivery execution with status values. Status: WIRED_SANDBOX
• DLQ API — Failed delivery attempts with retry relationship. Status: WIRED_SANDBOX
• Retry API — Single and batch retry for failed deliveries. Status: WIRED_SANDBOX
• Replay API — Event replay from retained payload/context. Status: WIRED_SANDBOX
• Traces / Evidence Spine API — Delivery trace spine. Not full distributed tracing. Status: WIRED_SANDBOX
• Saved Payloads API — Test/template payloads. Not production retained payloads. Status: WIRED_SANDBOX
• Evidence API — Cryptographic delivery proofs, integrity inclusion verification. Status: WIRED_SANDBOX
• Logs API — Structured platform logs with pagination and filtering. Status: WIRED_SANDBOX
• Rate Limits and Operational Limits — Plan-based limits per tier. Status: PUBLIC_CONTRACT_DRAFT
• Fabric Adapters API — List, disable, enable adapters per tenant/cluster. Status: WIRED_SANDBOX (BFF surface)

Workflow Recipes

• Create a Webhook Endpoint
• Create a Target
• Create a Flow
• List Planes and Inspect Adapters
• Validate, Test, and Publish Drafts
• Handle Errors and Rate Limits

MCP

• MCP Overview — Model Context Protocol server, tool surface, read/write model, non-claims. Status: PUBLIC_CONTRACT_DRAFT
• MCP Tools Reference — MCP tool surface (read/write, default-off per tool group)
• MCP Authentication and mTLS — MCP API key format, scopes, TLS requirements
• MCP Safety and Boundaries — Auth model, tool execution, gating, data isolation
• MCP Draft System — AI drafts infrastructure; human-only apply with governance model

Customer API

• Customer API — Planned programmable interface for reading operational truth and managing authorized Zen Mesh resources. Not read-only globally; endpoint groups carry individual read/write status. Status: PLANNED.

OpenAPI

• OpenAPI Spec Index — Canonical spec file, coverage table, endpoint groups, validation commands

Delivery Reference

• Delivery Status Reference — Webhook delivery state machine: status values, transitions, retry policy, DLQ
• Webhook Delivery Evidence — Delivery receipts, audit trail, integrity verification
• Webhook FAQ — 12 frequently asked questions about webhook delivery

Changelog

• API Changelog — Version history, migration notes, planned OpenAPI integration

Non-claims

• API documentation is not proof of production availability.
• Local/sandbox proof is not production-live proof.
• Billing live is not claimed unless explicitly marked.
• Some endpoints are app-facing only and not a public customer contract.
• Endpoint groups marked WIRED_SANDBOX are validated in sandbox/local runtime only.