ShadowGraph API

Quick start

Three calls answer most questions. No sign-up, no key.

1. Find the service. Search by name, domain, provider or cloud region. Every service result carries a slug and its live state.
   Copy

   curl -s "https://shadowalpha.online/_api/search?q=stripe&quick=1"

2. Ask whether it is down. The status page returns the live state per endpoint, since when it fails, the last outage and what it runs on.
   Copy

   curl -s "https://shadowalpha.online/_api/status/page?slug=stripe-api"

3. Check whether it is only regional. Failures are re-checked from six continents every 30 minutes.
   Copy

   curl -s "https://shadowalpha.online/_api/radar/global" | jq '.regionalOutages'

Authentication

Almost everything is public. Two endpoints need credentials; the website never asks you for an account to read data.

Machine payments (HTTP 402)

Paid intelligence uses the open Machine Payments Protocol with Stripe as the payment method. Prices are $0.50 to $5.00 per call. Nothing is charged unless your client presents a valid credential for a challenge we issued.

1. 1
   Call without credentials. The response is 402 Payment Required with a WWW-Authenticate: Payment header (method stripe, intent charge, the amount in cents in the base64url request parameter) and an RFC 9457 problem body.
2. 2
   Pay the challenge. Your agent's wallet creates a Stripe shared payment token for exactly that amount and builds the credential.
3. 3
   Retry the identical request with Authorization: Payment <base64url credential>. On success you get 200, the result and a Payment-Receipt header. A failed payment returns a fresh challenge.

Over MCP the same flow uses JSON-RPC: an unpaid tools/call returns error -32042 with error.data.challenges; retry with the credential in params._meta["org.paymentauth/credential"]; the receipt arrives in result._meta["org.paymentauth/receipt"]. Error -32043 means the payment could not be verified.

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="…", realm="shadowgraph-live.floot.app", method="stripe", intent="charge", request="eyJhbW91bnQiOiI1MCIsImN1cnJlbmN5IjoidXNkIn0", expires="…"
Content-Type: application/problem+json

{ "type": "https://paymentauth.org/problems/payment-required", "title": "Payment Required", "status": 402 }

Rate limits & caching

• Data changes every 5 minutes. Please poll an endpoint at most once per minute.
• Responses are cached at the edge for 20 seconds to 5 minutes; read Cache-Control. Repeated calls inside that window are cheap and return the same data.
• Live domain scans in search: 30 per client per hour (quick=1 never scans). Vendor scans: 4 per client per hour, 40 per hour in total.
• The full radar is about 1.3 MB of JSON; send Accept-Encoding: gzip (about 90 KB on the wire).
• Exceeding a limit returns 429 with a JSON error. There is no penalty beyond that.

Errors

Errors are JSON objects with one human-readable field: { "error": "…" }. Payment errors use application/problem+json.

Data semantics

up

Answered the latest check with HTTP below 500. 401, 403 and 404 count as reachable: the service is there, it just wants a key or another path.

degraded

Failed the latest check only. Often a blip; we do not call it an outage yet.

down

Failed the latest two checks in a row (about 10 minutes).

unknown

Not checked in the last 30 minutes.

Provider incident

Several independent services in the same hosting provider, cloud region, CDN or DNS provider down at the same time. When more than half of all probes fail at once, our node is suspect and no incidents are opened.

Vantage point

One measurement node in AWS us-east-1 (N. Virginia), plus six worldwide probes every 30 minutes. A service can be down for you and up for us, or the other way round.

inferred / statistical

Hypotheses, not proof. Official facts (SEC filings, published IP ranges) are labelled official.