Docs.
1 Matrix Systems Innovations Ltd, Cardiff CF10
Abstract
An operational reference for engineers integrating with WebMatrix. We document the onboarding path, the OTLP-compatible endpoint, the policy specification language, the API surface and the deprecation discipline. The reference is written for the engineer doing the integration, not for the person deciding whether to do it; that conversation belongs on the engineering call.
Four hours to first edge response.
A normal onboarding completes in about four hours. The route the customer's traffic takes is conventional: anycast PoP, BGP-announced from one of fourteen sites; TLS terminated against the customer's certificate held in the customer's HSM-backed key store; cache-key derived from the request envelope; origin selected by the operator's routing policy. The four hours are not in our infrastructure; they are in the customer's DNS propagation, certificate handoff, and the cache warm-up window. The platform itself accepts traffic the moment the routing policy is signed.
Configuration is data.
Every WebMatrix setting is a configuration record. There is no UI-only setting that is not also expressible as a signed YAML record committed to your repository. The control-plane UI is, by deliberate design, a renderer over the same records. The records are version-controlled, signed against the release tag, and auditable from the same data model the rest of the platform reads.
OTLP endpoint.
Point your OpenTelemetry collector at otlp.webmatrix.systems:4317 (gRPC) or :4318 (HTTP). Authentication uses an OAuth 2.0 bearer token issued from the control plane and rotated automatically every 24 hours. The endpoint is OTLP-compatible at the wire level; what differs is the schema extension, documented inline, that lets MatrixObserve recognise the request envelope, the policy hit and the edge decision when they appear in the trace.
| Signal | Endpoint | Schema | Notes |
|---|---|---|---|
| Traces | otlp.webmatrix.systems:4317 | OTLP 1.1 + wm.v1 ext | route/region attrs required |
| Logs | otlp.webmatrix.systems:4317 | OTLP logs · wm.v1 | trace context required if available |
| RUM beacons | rum.webmatrix.systems/v1 | wm.v1.rum | script tag, signed |
| Synthetic checks | synth.webmatrix.systems/v1 | wm.v1.synth | config as data |
Table 1 Telemetry endpoints. All four feed the same graph and join structurally, not heuristically.
Policy DSL.
MatrixGuard accepts a policy as a natural-language specification embedded in a thin DSL frame. The DSL exists because English is bad at rate windows, set membership and cryptographic predicates; the rest of the policy is English. The compiler is deterministic; the simulator runs against the last 30 days of production traffic; the promotion gate is the simulator output. There is no exception path that lets a policy enter production having failed the gate.
Read-only access to the WebMatrix graph.
The control-plane API is the single integration surface. Authentication is OAuth 2.0 with hardware tokens required for any write path. The OpenAPI 3.1 specification is published per release, signed against the release tag, and version-controlled in the public repository. The deprecation policy is twelve months of parallel availability between any two adjacent API versions; we have, in two years of operation, made zero unannounced breaking changes.
| Endpoint | Verb | Purpose | Auth |
|---|---|---|---|
/v1/routes | GET / PUT | List or upsert route records | OAuth · HW for write |
/v1/policies | GET / PUT | Manage MatrixGuard specs | OAuth · HW for write |
/v1/incidents | GET | Read incident paragraphs and graph | OAuth · read |
/v1/decisions | GET | Read edge decisions (auto-tune deltas) | OAuth · read |
Table 2 Four endpoints, one API surface. The control plane is small on purpose.
When the docs are not enough.
The documentation is sufficient for engineers who have read OTLP specifications before. When the documentation runs out — usually at the seam between WebMatrix and an idiosyncratic legacy system on the customer's side — open an engineering call. Forty-five minutes, written note same day, no obligation to continue.