Overview

Bounded, authenticated access to published business data with provenance.

SignalBraid API (0.1.0)

The original reference was derived from staging source at 1274bce. This historical baseline is retained separately from the 7 September 2026 stage 2 implementation update: source publication/calendar corrections and five pilot operations are implemented and locally tested. New live scheduled delivery and controlled failure/recovery acceptance remain pending.

This document is pinned to the gateway by a conformance test. packages/schema/test/openapi-document.test.mjs checks it against itself and workers/gateway/test/openapi-conformance.test.mjs checks it against the code that serves it. What those tests establish, exactly:

• every REST operation equals the frozen manifest used by live dispatch for its path, method and scope; a route left out on purpose is listed under x-undocumented-routes with its reason
• synchronization and pilot HTTP errors equal frozen route-specific gateway tables in both directions: every response schema admits exactly the codes for that operation and status, while the intentionally broader PilotStatusCode is used only for persisted schedule diagnostics
• failed synchronization polling uses a separate exact 35-code execution enum; bounded internal or scheduled ledger codes outside it are redacted
• every query error code is schema-pinned at its exact runtime status
• every code stated in an enum here exists in some gateway table
• the scope and authentication behavior each operation declares are observed by live probes through the same manifest the gateway enforces, including the health route’s required absence of authentication
• twenty-seven base requests are served against the real route table, each returning the exact status written down; additional generated probes exercise every runtime synchronization state and every classification in the frozen synchronization-service error tables. Every live operation probe validates its request body, effective path and header parameters, served JSON body, media type and documented response headers against the exact owning operation and status

Runtime contracts are exported as immutable snapshots rather than transcribed into tests, so additions or removals cannot drift silently. Both schema and live release are checked at exact operation/status/code granularity; a route cannot borrow another route’s classification. The conformance suite exercises public 409, 502 and other runtime error classifications by injecting an exact private-service response and sending it through the real public gateway boundary. It does NOT recreate every underlying provider failure, lease conflict, D1 race, credential failure or outage mechanism; those mechanics live in the owning service tests. Response descriptions are checked for naming the right codes, not for being accurate prose — read them as carefully-checked prose, and the code lists as a contract.

What exists is one metric — ga4.sessions by date, from one Google Analytics 4 property per connection — reachable over REST and over MCP. There is no public endpoint: the gateway is deployed privately with no workers.dev subdomain and no route, and API keys are issued by an operator. Self-serve signup, OAuth connection setup, additional connectors, additional metrics, general exports and API rate limits are not implemented. The controlled pilot supports one GA4 schedule per destination with native Sheets delivery. Its private queryForExport service-binding RPC is not an HTTP route or MCP tool and is not described as a public operation here.

The MCP route is not described here. It is not a REST operation, and two of its error codes differ from the REST codes below — see apps/docs/src/content/docs/mcp.md.

Provenance is part of every answer. A successful query returns the rows, the metric definition that produced them, the exact snapshot each day came from, how fresh those snapshots are, and the limitations that still apply. A result is returned only when every requested day has a complete published snapshot; a partial window is an error, never a silently short answer.

Two limitations apply to every result and are returned as flags rather than left to the reader: provider_may_revise_recent_data (GA4 restates recent days, so a value can change after publication) and not_independently_reconciled (the product does not re-derive the number from a second source).

• SignalBraid: https://signalbraid.com
• License: Proprietary
• OpenAPI version: 3.1.0

Authentication

bearerAuth

Authorization: Bearer <key>. Keys are verified with HMAC-SHA-256 against authoritative control-plane records on every request — revocation and expiry take effect immediately, including during an in-flight read.

Two scopes exist. query:read covers /v1/query, /v1/metrics/ga4.sessions, MCP and GET pilot schedule status; sync:write covers sync routes and all POST pilot operations. They are separate: a sync:write key cannot read data.

Keys are issued by an operator. There is no self-serve key management.

Security scheme type: http