SignalBraid API

SignalBraid connects the platforms a business runs on and lets you read from them in one place — over REST, and from an AI client over MCP.

This documentation distinguishes implemented behavior from live verification. The controlled pilot is deliberately narrower than the intended product.

What exists today

One metric, end to end, from Google Analytics 4:

• ga4.sessions by date, for one GA4 property per connection, up to 31 days per request, in the property’s own reporting timezone.
• REST — read the published result with its full provenance, and trigger the extraction runs that publish it.
• MCP — the same query as a read-only tool, so an AI client returns the same numbers as the API rather than its own interpretation of them.
• Controlled pilot automation, implemented and locally tested — authenticated schedule configuration, bounded retries, and delivery to an app-created native Google Sheet. New live scheduled delivery and controlled failure/recovery acceptance remain pending; see Pilot automation.

Verified on staging on 7 September 2026: an operator compared the published result against the same window fetched from Google, and all five daily values and the 129-session total matched. That is evidence about one snapshot, not a standing guarantee — see Trusting the numbers.

What does not exist yet

Being explicit, because a documentation site that quietly omits this is misleading:

• No public endpoint. The gateway is deployed privately, with no workers.dev subdomain and no public route. It is reachable only over a Cloudflare service binding from inside the account.
• No self-serve anything. No signup, no OAuth connection flow, no key management UI. Keys and connections are provisioned by an operator.
• One connector, one metric. No Google Ads, Meta, Shopify, HubSpot, Stripe or anything else, and no metric other than ga4.sessions.
• No general export service, no API rate limits, no billing enforcement, no deletion or retention operations.

Trusting the numbers

The reason to use a data hub rather than a spreadsheet of exports is that you can tell where a number came from. Every successful query carries:

• the metric definition that produced it, so a value can be compared with something else on a like-for-like basis;
• the exact snapshot each day came from — run id, extraction sequence, when it was extracted and when it was published;
• freshness, including whether the oldest snapshot in the window has passed the 30-hour staleness threshold;
• the limitations that still apply, as flags.

Two flags are on every result today and are worth understanding before you build on the data:

provider_may_revise_recent_data — GA4 restates recent days. A value you read today can legitimately differ from the same day read tomorrow. This is a property of the source, not a defect.

not_independently_reconciled — The product does not re-derive these numbers from a second source. An operator did that once, by hand, for one staging window. Until reconciliation is automated and continuous, the product does not claim it.

A window is answered only when every requested day has a complete published snapshot. A partial window is an error that names the missing dates — never a short answer that looks complete. Missing, unavailable and genuinely-zero are three different states here, and the API keeps them apart.

Where to start

• Authentication — keys, scopes, and how revocation behaves.
• Reading data — POST /v1/query and how to read provenance.
• Syncing data — triggering extraction runs and their states.
• MCP — the read-only tool and what it does not expose.
• Errors — every public code, what it means, and whether to retry.
• Pilot automation — native Sheets setup, schedules, status and recovery.

The machine-readable description is the OpenAPI 3.1 document at packages/schema/openapi/signalbraid-v1.yaml. Under D59 and D62, document checks validate targeted structural and schema invariants while gateway conformance checks compare the contract with the shared live route, method and scope manifest and validate served cases. These checks are not a complete OpenAPI standards linter and do not induce every possible failure live. An interactive rendering of the contract is still deferred.