TunnelMind Data API

P75 registry aggregation: the cross-lens join applied to agent identity. Incumbent providers each consult only their own registry; this endpoint checks every registry TunnelMind can reach and labels each answer with an explicit state, so a gap can never be mistaken for a clean result: - `observed` — the subject IS in this registry (record attached) - `not_present` — checked, and it isn't (an observation, not a gap) - `not_applicable` — the registry doesn't key on this subject type - `degraded` — the check failed (timeout, upstream error) - `unavailable` — the registry is not publicly consultable (closed / platform-scoped); stated in-band because silence would read as clean Registries (v0): `crawler_ranges` (operator-published IP feeds — Googlebot, GPTBot, PerplexityBot…), `wba_directory` (RFC 9421 Signature-Agent JWKS at the subject domain), `mcp_registry` (registry.modelcontextprotocol.io), `tunnelmind_known_agents` (curated verifiable/claim-only set), plus honest `unavailable` rows for Visa TAP, Mastercard Agent Pay, and Cloudflare Verified Bots. Use this tool when: - You are deciding whether an agent, bot, or MCP server is registered anywhere that vouches for it — in one call instead of five. - You need the blind spots stated: which registries could NOT be consulted for this subject, and why. Inputs: subject — an IP (registry membership by published ranges), a domain (WBA directory + MCP registry), or an agent name/UA fragment (e.g. `gptbot`, `claudebot`). `?receipt=true` attaches a signed Receipt v1.0 committed to the transparency log. Latency: remote registry checks are KV-cached for 1h; a warm call is edge-fast, a cold one bounded by 5s per-registry timeouts.

P73 fast attributes endpoint (PIP-PLAN P3): a full `POST /v1/verify` resolve fans out across four lenses (~2s) — fine for preflight, fatal inside a per-request authorization loop. This endpoint serves the last-known signed bundle from a single KV read, with the P69 freshness contract deciding how much to trust it. Use this tool when: - A policy decision point (OPA, Cerbos, Cedar) needs node attributes on its hot path and can tolerate `valid_until`-bounded staleness. - An agent re-checks a node it (or anyone) verified recently. Inputs: - `node` (path, required): IPv4 address, domain, ASN (`AS64500`), or entity_slug — same grammar as /v1/verify. Returns: - The exact verify bundle last cached for the node (lens blocks, `cross_lens` verdict, `coverage` with `valid_until` / `stale_if_error`, signed `receipt`), plus `attributes_meta`: `cached_at` and `freshness` — `fresh` (inside `valid_until`) or `stale` (past it, still inside the `stale_if_error` window; the contract says a consumer may use it rather than fail closed). - `404` when nothing is cached — the node was never verified, or its bundle aged past `stale_if_error`. POST /v1/verify to (re)observe. - The short-lived `sigil_token` from the original verify is never included: bearer capabilities are not re-served. Cost: - Counts as one request against the daily rate limit. Latency: - Typical: <100ms (one KV read, no lens fan-out).

Returns NDJSON (one JSON object per line) of audit log entries. Each entry records the operation called, the identity, hashes of the request and response, duration, and an Ed25519 signature over the canonical entry JSON. Entries are hash-chained: each entry's `prev_entry_hash` is SHA-256 of the previous entry's signature, making deletion of any entry detectable offline. Authenticated callers receive only their own entries (`identity_sub` match). Admin key holders receive all entries. Use this tool when: - You want a tamper-evident record of your own API calls. - You are auditing a sequence of requests for compliance or debugging. - You want to verify the audit chain integrity offline. Do NOT use this tool when: - You are anonymous — authentication is required. - You want task status — use `get_task` instead. Inputs: - `from` (query, optional): ISO 8601 start datetime. Default: 7 days ago. - `to` (query, optional): ISO 8601 end datetime. Default: now. - `limit` (query, optional): Max entries. 1–5000, default 1000. Returns: - NDJSON stream, one `AuditEntry` per line. - `X-Total-Count` response header with entry count. - `X-Took-Ms` response header. Verify the chain offline: - For each consecutive pair (A, B): `SHA-256(A.signature) == B.prev_entry_hash`. - For each entry: verify Ed25519 signature against public key in `/.well-known/atap.json`. Cost: - Counts as one request against the daily limit. Latency: - Typical: <300ms for 1000 entries, p99: <1s.

Marks the task as `cancelled`. If the task is already in a terminal state (`complete`, `failed`, `expired`), returns 409 Conflict. Only the identity that created the task may cancel it. Use this tool when: - You submitted a probe with `?async=true` and no longer need the result. - You want to free up a pending task before it expires. Do NOT use this tool when: - The task is already complete — cancellation is not possible. Inputs: - `task_id` (path, required): 26-char ULID. Returns: - `task_id` and `status: cancelled`. Cost: - Free. Latency: - Typical: <150ms.

Single-item revocation lookup per Receipt Format v1.0 §8.2. Verifiers that do not want to maintain a local mirror of `/.well-known/receipt-revocations.json` call this endpoint instead. The response includes `feed_version` for cache coherence. Use this tool when: - You are verifying a receipt and need to confirm its `signature.key_id` is still trusted. - You are verifying a receipt and need to confirm the specific `receipt_id` was not retracted by its issuer. - You hold receipts long-term and want to recheck trust before acting on them. Do NOT use this tool when: - You want the full revocation set — fetch `/.well-known/receipt-revocations.json` directly. - You want to *publish* a revocation — that is operator-controlled and not exposed via this API. Inputs: - `key_id` (query, optional): Receipt-format key_id (e.g., `tm-receipt-2026-05`). Provide one of `key_id` or `id`. - `id` (query, optional): UUIDv7 of a specific receipt. Provide one of `key_id` or `id`. Returns: - `revoked`: boolean. - When revoked: `revoked_at` (ISO 8601), `reason` (human-readable), `replacement_key_id` (for keys). - Always: `checked_at` (ISO 8601), `feed_version` (integer). Cost: - Free; rate-limited like the rest of the data API. Edge-cached 60s. Latency: - Typical <100ms (warm cache); p99 <500ms (cold fetch from well-known).

Set the customizable knob: which regulatory regime your auditor maps to, how long to retain decision content, and which export formats to offer. Body: { enabled?, regime?, retention_days?, export_formats? }. retention_days is 1..3650; regime is one of the catalog ids; export_formats is a non-empty subset of [signed_json, csv, eat, stix]. No bespoke engineering — you pick, the ledger adapts.

Generates a signed export bundle of your ledger over an optional time window, mapped to your regime's field names and citation, with a manifest + chain-integrity proof + the latest signed checkpoint. Choose the format with ?format= (signed_json | csv | eat | stix; defaults to your profile's first) and override the regime with ?regime=. The response is a downloadable artifact your auditor can verify independently against the spec.

Returns your hash-chained decision records — one per verdict-bearing call (/v1/verify, /v1/explain, /v1/preflight, /v1/profile) made while compliance is enabled. Each entry carries its node, verdict, scores, receipt_id, the full decision record, and the chain hashes (prev_hash, entry_hash). Filter with from/to (ISO8601) and page with cursor (a seq) + limit (≤1000).

Returns your current compliance configuration (regime, retention_days, export_formats, enabled) and the catalog of supported regimes (EU AI Act Art.12, DORA, NYDFS 500, HIPAA, PCI DSS, SOC 2, generic) and export formats (signed_json, csv, eat, stix). Authenticated. The compliance ledger is a tamper-evident, retained record of every verdict you make — configure it once, then it self-maintains.

Recomputes your entire hash chain server-side and reports integrity ({ intact, entry_count, chain_head_hash } — plus reason + first_break_seq if a record was altered or deleted), alongside the most recent Ed25519 checkpoint signed with the TunnelMind receipt key. This is the auditor's "prove it" button — and even TunnelMind cannot rewrite history before a signed checkpoint without detection.

Self-serve free tier — the rung between anonymous access and paid blocks. One email in, one API key out, shown exactly once. Use this tool when: - You are calling anonymously and hitting the anonymous rate limit. - You want your calls identified so usage survives IP changes. Limits: - 50 requests/day (same endpoints as anonymous, higher ceiling). - One active free key per email; 3 signups per IP per day. - The raw key is returned once and stored only as a SHA-256 hash — it cannot be recovered, only revoked and reissued. Cost: free. No card, no account — the email is the revocation handle, nothing more.

Subscribe to a node (ip, domain, asn, or entity slug). On a recurring sweep (~20 min) TunnelMind re-runs the fused `POST /v1/verify` verdict and, when the *material* result changes — the verdict label flips, the trust score crosses a band, or the signal set changes — POSTs a signed event to your `callback_url`. Webhook authenticity: every delivery carries an `X-TunnelMind-Signature: sha256=<hex>` header, an HMAC-SHA256 over the raw request body keyed by the `signing_key` returned ONCE at creation. Recompute and compare to trust it. Delivery body: `{ subscription_id, node, event: "verdict_change", previous, current, delivered_ms }` where `previous`/`current` are compact verdict summaries `{ verdict, trust_score, signals }`. Inputs (JSON body): - `node` (required): the node to watch. - `callback_url` (required): an https URL to receive deliveries. - `events` (optional): reserved; defaults to `["verdict_change"]`. Requires an API key. The baseline verdict is captured at creation, so the first webhook fires on the first genuine change, not the initial state.

Returns all three lens views for a single node key without computing a fused verdict. Use this when you want raw transparency — the Tracker catalog presence, Scry attacker observations, and Sigil supply-graph position — and intend to make your own decision. For an opinionated verdict, call `cross_lens_verify` instead. For an agent-side allow/caution/deny gate plus signed consultation receipt, call `preflight_should_i_act`. Coverage block exposes which lenses responded so agents can reason about partial-data verdicts. `issued_by` carries the OAI of the answering witness so the response is attributable.

A2 — the cross-lens join. TunnelMind owns multiple halves of the open-web graph: Scry sees who is on every IP (attacker intelligence, actor class, Augur threat-intel overlap); Sigil sees the supply graph (publishers, SSPs, DSPs, ads.txt + sellers.json + SupplyChain Object); GhostRoute sees routing integrity & sovereignty (RPKI origin validity, BGP prefix, claimed sovereign zone, sanctions, AI-infrastructure ownership, certificate CA). This endpoint fuses them into one verdict on a single node key. Streaming mode (P56): send `Accept: application/x-ndjson` and the same verdict computation streams as one JSON object per line — a `{"t":"lens",...,"state":"start"}` line when each lens query is dispatched, a `"state":"result"` line as each lens actually resolves (real completion order, never reordered or paced), then the final `{"t":"verdict",...}` line with the fused verdict, trust score, and attestation tier. The default single-JSON response is unchanged and the two modes return the identical verdict for the same node. The response leads with a base record, then the lens views: - `ip_intel` — the BASE: the commodity IP-intelligence + WHOIS record (geo/ASN/company/WHOIS/routing/cert), every field provenance-tagged `{value, tier, source}` (verified/derived/trusted) with a behaviour axis from Scry. The lens blocks below are augmentation beside it. Committed in the receipt payload. See `docs/IP-INTEL-RECORD.md`. - `scry` — the single-lens Scry view (transparency). - `sigil` — the single-lens Sigil view (transparency). - `ghostroute` — the single-lens GhostRoute view (transparency). - `cross_lens` — the fused verdict (the moat). Fusion math: weighted-mean over evaluated components plus a `co_observation_bonus` when both lenses independently flag the node. GhostRoute adds a routing-integrity component with two hard safety floors that cannot be averaged away: an RPKI-INVALID origin (a BGP hijack signal) caps its trust at 0.15, and a sanctions match zeroes it. Weights and thresholds are per-request overridable. Lens unavailability is reported in-band: each lens fails independently and the cross_lens block reflects degraded confidence when fewer lenses have data (0.55 one lens / 0.80 two / 0.94 three). GhostRoute has no routing surface for a bare entity_slug, so it drops out and the remaining weights re-normalise. Returns 503 only when ALL lenses are unavailable. v1 lens coverage matrix: - IP node — Scry: full; Sigil: not_indexed (v2 will reverse-DNS); GhostRoute: full. - Domain node — Scry: deferred; Sigil: full (publisher/ssp/dsp + entity); GhostRoute: full (resolves to IP). - entity_slug node — Scry: n/a; Sigil: full (entity + sell/buy presence); GhostRoute: n/a (no routing surface). - ASN node — Scry: deferred (v2); Sigil: not_indexed; GhostRoute: origin-AS lookup.

Cancel a subscription.

Call this when you need to ACT ON a verdict and prove why. It returns the exact verdict `/v1/verify/{node}` computes (same fusion, same weights) PLUS a traced evidence chain: every claim is attributed to where it came from — the attested sensor fleet (with attestation tier), a named Augur threat feed, sellers.json/ads.txt supply-graph presence, the cross-lens co-observation join, the DDG/IAB tracker corpus — and how much each item moved the verdict (`weight`; null = supplementary, not scored). The response is committed to by a P38 signed receipt via `evidence_digest` (a hash of the exact evidence array), so an agent can act on the verdict and leave behind a cryptographically verifiable trail of the reasoning in the same request. Empty/`none` evidence is the honest "no corpus presence", never a fabricated reason. `node` is an IPv4/IPv6, ASN, domain, or entity_slug — the same key space as `/v1/verify`.

Looks up each submitted domain in the TunnelMind tracker database, aggregates risk metrics (avg score, max score, fingerprinters, high-risk domains, entity ownership), and issues a signed surveillance receipt. The receipt is stored in the public registry and can be verified at `/verify/{receipt_id}`. Use this tool when: - You want a verifiable record of which trackers were observed in a context (page, app, session). - You need a signed evidence artifact for a privacy audit or compliance report. - You want to know the overall surveillance exposure level for a set of domains. - You are generating a receipt to share with a user as evidence of tracker presence. Do NOT use this tool when: - You want full tracker details per domain — use `get_domain` instead. - You want to look up an existing receipt — use `get_receipt` instead. - You need live probes (HTTP headers, stack detection) — use `/v1/intel/*` instead. Inputs: - `domains` (body, required): Array of 1–50 fully qualified domain names. Duplicates are deduplicated. URLs are stripped to host component. - `domain` (body, alternative): Single domain string (shorthand for `domains: [domain]`). Returns: - `receipt_id`: Unique receipt ID (e.g. `rcpt_01JXYZ...`). - `receipt`: Full receipt document including domains submitted, tracker findings, high-risk domains, fingerprinters, unique entities, and exposure metrics. - `content_hash`: SHA-256 of the canonical receipt JSON. - `signature`: Base64 Ed25519 signature (empty string if signing key not configured). - `signed`: Boolean — true if the receipt is cryptographically signed. - `verify_url`: Path to retrieve this receipt from the public registry. Exposure levels: `minimal` / `moderate` / `high` / `critical` Based on average tracker score and proportion of high-risk domains (score ≥ 70). Cost: - Counts as one request against the daily limit regardless of domain count. Latency: - Typical: <100ms (pure D1 lookup, no outbound probing). p99: <300ms.

Returns the TunnelMind analyst config bundle. Configures any LLM (Claude, GPT, Gemini, local) to behave as a TunnelMind analyst that knows the data graph, follows the 5-call golden path, and surfaces attestation_tier on every claim. The bundle is signed inline (Ed25519, key_id from /.well-known/receipt-signing-key.json). Add `?receipt=true` to wrap the response in a Receipt v1.0 envelope for end-to-end audit. Use this tool when: - You want to configure a new LLM runtime to act as a TunnelMind analyst - You want to verify the system prompt you're running matches what TunnelMind serves - You're building a BYOM (bring-your-own-model) deployment and need the canonical config Do NOT use this tool when: - You want to call individual TunnelMind data tools — use the tools directly - You want to verify a specific receipt — use check_receipt_revoked or @tunnelmindai/receipt-verify Inputs (all optional): - `surface` (query): "data" (default, full surface), "scry", or "sigil" - `version` (query): pin a specific bundle version (e.g. "1.0.0" or "1" for latest 1.x.y) - `receipt` (query): "true" to wrap the response in a signed Receipt v1.0 envelope Content negotiation (via Accept header): - `application/json` (default) — full bundle JSON - `text/markdown` — system prompt only (Anthropic flavor) - `application/vnd.anthropic.config+json` — Anthropic-shaped subset - `application/vnd.openai.config+json` — OpenAI-shaped subset Returns: - `version`, `schema`, `issuer`, `surface`, `surface_label` - `system_prompts.{anthropic,openai,generic}` — three encodings of the same semantic prompt - `tools.surface_subset` — array of operationIds for this surface (null = all) - `response_format` — JSON Schema the analyst's verdicts must conform to - `attestation_tiers` — the 4-tier vocabulary (self_asserted → silicon_root) - `graph_state` — live corpus counts at serve time (best-effort, any may be absent: `observations_total` from the scry stats cache, with `observations_as_of` = the ISO time that cached scry block was fetched, which may lag `as_of_ms` by up to the KV TTL (~30 days); `tracker_entities_total`, `sells_through_total`, `oai_registry_total` from Supabase estimated counts) - `references` — URLs to the rest of the open-protocol layer - `bundle_signature` — inline Ed25519 signature for offline verification - `pin_recommended` — stable supply-chain identifier (survives hourly graph_state updates) Headers: `X-Bundle-Version`, `X-Pin-Recommended`, `ETag`, `X-RateLimit-*`. Cost: - Free, anonymous-accessible. Rate-limited on a SEPARATE counter from data-API calls (`cfg:ip:<ip>` identity) so a config refetch loop can't burn your data quota. Latency: - Typical <100ms (cached); cold fetch <500ms (live Supabase counts).

Returns the tier, label, masked owner email, creation date, last-used timestamp, today's request count, and daily request limit for the API key used in this request. Useful for agents that need to monitor their own quota consumption. Use this tool when: - You want to check how many requests your key has used today. - You need to know your current tier or daily limit. - You want to confirm that your API key is active. Do NOT use this tool when: - You want to manage multiple keys — this endpoint only reflects the calling key. - You need tracker data — use the tracker endpoints instead. Inputs: - No body or query parameters. Auth is from the `Authorization: Bearer` header. Returns: - `tier`: free, supporter, pro, or enterprise. - `requests_today`: integer count from KV (best-effort; resets at UTC midnight). - `limit_per_day`: null for enterprise (unlimited). - `last_used`: ISO 8601 timestamp, may be null if never used. Cost: - Free. Does not count against the daily request limit. Latency: - Typical: <150ms, p99: <400ms.

Returns the routing anomalies the bgp-monitor has observed against TunnelMind's BGP watchlist — the witnessability layer's routing dimension. The monitor polls RIPEstat (RIPE NCC) on a cron, self-baselines each watched prefix's origin set on first sight, then records an event whenever a later poll deviates from that baseline. Use this to check whether a prefix or ASN you depend on (an SSP's egress, a publisher's network, your own infrastructure) has shown a hijack-shaped routing event. `event_type` is one of: - `origin_change` — an origin AS not in the baseline is announcing the prefix (severity `critical` if that announcement also fails RPKI, else `high`). - `rpki_invalid` — a current announcement fails RPKI ROA validation. - `withdrawn` — a previously-announced prefix is no longer visible. - `new_more_specific` / `visibility_drop` — reserved for a later monitor pass. `prev_origins` is the baseline the event deviated from. `count` is the full filtered set; `events` is bounded by `limit`, newest first. An empty `events` array means no anomalies in the window — the honest "all clear".

The change ledger, read back: what TunnelMind itself changed in the window, newest first, as one Ed25519-signed document. Use this tool when: - you need to know what changed in TunnelMind's site, prices, tools or operations, and want it signed rather than asserted. - you are checking whether a tool or price you rely on moved recently. Items come from receipts with lens `config`: the four recorded kinds plus `toolset_change` (derived from the tool registry; its `agent`, `class`, `reversible` and `revert_ref` are null). `truncated` is true when more rows exist than `limit`; `skipped` counts rows with an unreadable payload. If the ledger store is unavailable the response is still 200 with `available: false` and a `reason`, never an empty list passed off as clean. Cached 5 minutes (`X-Changes-Cache: hit|miss`); unavailable responses are never cached.

Weekly public aggregate of demand: what callers asked this API for that it did not have or rejected (ghost routes, rejected arguments, ghost MCP tools, tools/list counts). One ISO week, Monday 00:00 UTC to the next Monday 00:00 UTC (`?week=` picks the week containing a date; default is the current week). Aggregate rows only: a row is published only when at least `n_threshold` (3) distinct actors produced it in the window. Rows below that are omitted, and their count is published in `suppressed` ({rows, events}). No actor identifier, IP, raw path, query string, timestamp or per-row user agent is ever returned. `name` and `path_shape` are caller-supplied request text, marked `caller_supplied: true`; they are not TunnelMind statements. `valid_until` equals `window_end`. Add `?receipt=true` for a signed Receipt v1.0 over the same payload. Totals cover published rows only. `ghost_tool_per_list_ratio` is ghost tool asks per tools/list, because only unknown-tool calls are recorded.

Returns the complete surveillance intelligence record for a domain name. If the domain is in TunnelMind's tracker database (80,000+ entries), the response includes tracker category, risk score, fingerprinting data, cookie persistence, IAB TCF purposes, and the owning corporate entity. If the domain is not in the database, a live probe is automatically run: RDAP registration data, DNS records (MX, SPF, TXT verification tokens), HTTP headers, and CSP third-party actors are fetched fresh from the edge and returned. Use this tool when: - You need to know whether a specific domain tracks users, and how aggressively. - You are researching who owns a domain and what corporate entity controls it. - You want to check HTTP security headers and third-party services embedded in a site. - You are building a risk score for a domain before routing traffic through it. Do NOT use this tool when: - You want to search by keyword or category — use `search` instead. - You want all domains for an entity — use `get_entity` instead. Inputs: - `domain` (path, required): Domain name. Strip `www.` prefix — it is removed automatically. Subdomains are resolved to the parent: `ads.doubleclick.net` → `doubleclick.net`. Examples: `doubleclick.net`, `google-analytics.com`, `intercom.io`. Returns: - Full `DomainRecord`. Free tier returns the domain, category, score, prevalence, and entity name. Pro/enterprise additionally return `tcf_vendor_id`, `tcf_purposes`, `tcf_features`, and `disconnect_cats`. - If the domain is not in the tracker database, `live_lookup: true` is set and RDAP/DNS/HTTP probe results are returned instead of tracker fields. - 404 if the domain cannot be found via live probe either (unknown TLD, unreachable). Cost: - Free tier: included in 50 req/day limit. Pro/enterprise: included in plan. Latency: - Database hit: typical <100ms, p99 <300ms. - Live probe: typical 2-5s, p99 10s (external DNS/HTTP calls).

Returns an entity record for a surveillance company or data broker, including its industry, estimated annual data value per user (in USD), categories of personal data collected, and the full list of domains it controls. Free tier returns 5 domains, paid returns up to 200. Use this tool when: - You want to understand what corporate entity owns or controls a tracker domain. - You need to assess the total surveillance footprint of a company (e.g., Alphabet, Meta, Oracle). - You are building a corporate surveillance graph and need domain-to-entity mapping. Do NOT use this tool when: - You have a domain and need its category — use `get_domain` instead. - You want to browse entities by industry — use `list_entities` instead. - You are searching for an entity by name — use `search` instead. Inputs: - `slug` (path, required): URL-safe entity identifier (lowercase, hyphens). Examples: `alphabet`, `meta`, `oracle-data-cloud`, `the-trade-desk`. Returns: - Full `EntityRecord` with data categories, estimated data cost, and associated domains. - `domains`: array of top-scoring domains (5 for free tier, 200 for paid). - Pro/enterprise additionally return `website` and `description` fields. Cost: - Free tier: included in 50 req/day limit. Pro/enterprise: included in plan. Latency: - Typical: <150ms, p99: <400ms.

Public read of the crowd-sourced outcome aggregate for a node — how callers reported their real-world results after acting on its verdict. Advisory signal, not a trust verdict. An empty aggregate returns cleanly with `total: 0` and `signal: none`. `signal` is derived: `none` (no reports), `insufficient` (<3), `positive` / `negative` (score past ±0.3), or `mixed`.

D4 — the freshness contract a PDP can gate on. For each lens (Scry / Sigil / Tracker / GhostRoute) this reports the newest observation timestamp in the corpus, the declared ingest cadence (taken from the ingester's own code and cron schedules, never asserted), the published SLO, the current corpus age in seconds, and whether the SLO holds. GhostRoute reports its three corpus workers (CT hourly, RPKI 6-hourly, ASN daily) individually. SLO rule: 2x the declared cadence — one fully missed ingest cycle trips it — except where an estate monitor already publishes a threshold, in which case the SLO matches the monitor. Every source is independently null-tolerant: a momentarily-unmeasurable lens reports `last_observation_at: null` and `slo_met: null` — never a fabricated timestamp, never a silent pass. Cached ~5 minutes (unlike the weekly /v1/stats snapshot — freshness that was itself a week stale would be self-refuting).

Spec 097 / ADR-035 Amendment C8. Returns the usage-tiered price schedule for paid calls. Prices are integer strings of USDC atomic units (6 decimals). Rows are `{tier, from, to, price_atomic}`; `to` is null for the open tier. `anonymous` is the price a call without an API key pays. The schedule is the compiled-in default unless a validated override is held in KV (one KV read, no database read); `schedule_source` says which. `band` is the floor and ceiling every tier price sits inside. `schedule_hash` is the sha256 hex of the RFC 8785 canonical schedule, so a consumer can tell when prices change. `counting_rule`: the tier is set by settled paid calls per API key in the current UTC calendar month; a call without a key pays the top-tier price; a call counts only after a successful settle; the 402 response quotes the price of the caller's next call. `consistency_note`: the count is kept in KV, which is eventually consistent, so a tier boundary can drift by a few calls. Freshness: `observed_at` is the response time, `valid_until` is 24 hours later, `stale_if_error` is 86400 seconds. Add `?receipt=true` for a signed Receipt v1.0 over the same payload.

Returns metadata for a TunnelMind surveillance receipt — a signed document proving that a specific user's surveillance exposure was observed, measured, and recorded at a specific time. Does NOT return the receipt's signature (anti-phishing protection). To verify a receipt's content integrity, use `verify_receipt` with the hash and signature from the receipt document itself. Use this tool when: - You have a receipt ID and want to confirm it was genuinely issued by TunnelMind. - You need the issuance timestamp and signing key ID for a receipt. - You want to check whether a receipt exists before attempting content verification. Do NOT use this tool when: - You have the full receipt document and want to verify it hasn't been tampered with — use `verify_receipt` instead. Inputs: - `receipt_id` (path, required): The receipt ID from the receipt document. Alphanumeric with hyphens, max 128 characters. Returns: - `status`: `FOUND` if the receipt is in the registry. - `generated_at`: ISO 8601 timestamp of receipt issuance. - `signing_key_id`: identifier of the Ed25519 key used to sign. - `schema_version`: receipt schema version. - `message`: human-readable summary with instructions for content verification. - 404 if the receipt ID is not in the registry. Cost: - Free. No API key required. Latency: - Typical: <100ms, p99: <300ms.

For a capability TunnelMind does not provide itself, returns the destination's endpoint and schema URL from a reviewed catalog, plus facts TunnelMind itself observed: when its own probe last reached the destination, whether the destination advertises x402 or Web Bot Auth, and the origin ASN and RPKI state of the host. Every fact carries `{value, tier, source}` and a coverage state. The response carries a signed Receipt v1.0. The signature attests what TunnelMind recorded, not that the destination's claims are true. TunnelMind never calls the destination on your behalf and never carries your traffic or data to it. Payment always goes to TunnelMind's own x402 address and nothing the destination says can change that. Priced per call in x402 USDC by the caller's monthly tier (anonymous callers pay the base price); the 402 challenge quotes the price for this call. Demo payments are refused. When the paid tools flag is off the route answers 503 and issues no challenge. Unknown capabilities answer 404 with no charge.

Weekly public aggregate of demand: what callers asked this API for that it did not have or rejected on paid referrals (kinds referral and ghost_referral only). One ISO week, Monday 00:00 UTC to the next Monday 00:00 UTC (`?week=` picks the week containing a date; default is the current week). Aggregate rows only: a row is published only when at least `n_threshold` (3) distinct actors produced it in the window. Rows below that are omitted, and their count is published in `suppressed` ({rows, events}). No actor identifier, IP, raw path, query string, timestamp or per-row user agent is ever returned. `name` and `path_shape` are caller-supplied request text, marked `caller_supplied: true`; they are not TunnelMind statements. `valid_until` equals `window_end`. Add `?receipt=true` for a signed Receipt v1.0 over the same payload. Referral rows carry `status`; 404 (unknown capability) and 503 (asked while off) are separate rows.

P83 Gate 1. The caller is the subject: every fact here comes from the TLS handshake and headers the caller has already sent, so there is no render, no browser, and nothing to authorize. Three surfaces: - `client` — user-agent, HTTP protocol, TLS version/cipher, ClientHello length, the pre-hashed JA3/JA4 input components, header order. - `state` — how many cookies were sent (never their values), Referer, DNT, Global Privacy Control. - `network` — address, ASN and operator, coarse geography, edge colo, and the four-lens verdict on the caller's own IP. Every field carries a coverage state from the same three-value vocabulary as `/v1/verify`: `observed_clean`, `never_observed`, `degraded`. There is no fourth state. Fields that run inside a page — localStorage, canvas fingerprinting, cookie values — are reported `never_observed` with reason `not_observable_server_side`, because they are outside a server's vantage rather than missing. `claim_vs_conduct` compares the claimed user-agent against the shape of the request itself and returns `consistent`, `mismatch`, or `unverifiable`, with the evidence listed. It is deliberately narrow: JA4 requires Cloudflare Enterprise + Bot Management, so there is no portable fingerprint to look up in a public corpus, and this check only reports contradictions it can demonstrate from the request in hand. `unverifiable` is the honest default and is never dressed up as a pass. Use this tool when: - You want to know what a server learns about your client without asking you anything. - You are checking whether a client's user-agent claim matches its conduct. Do NOT use this tool when: - You need facts about some OTHER host — that is `POST /v1/verify/{node}`. Must be called directly at `data.tunnelmind.ai`. Behind a proxy, the connection properties describe the proxy, not the caller. `?receipt=true` attaches a signed Receipt v1.0 committed to the transparency log.

One public "state of the corpus" readout — the whole graph in a single call. Distinct from the Scry-only sensor stats at api.tunnelmind.ai/v1/stats (which this reuses for the `scry` block): this spans Scry, Sigil, and Tracker plus the attestation and routing layers. Use it to cite live coverage — how many publishers / SSPs / DSPs / sell paths / sellers.json seats are in the Sigil supply graph, how many tracker entities and domains Tracker holds, how many ATAP witness events and OAIs the attestation layer carries, and how many BGP watchlist resources and routing events the monitor has recorded. Every count is independent and null-tolerant: a momentarily-unavailable lens reports `null`, never a silent zero. Cacheable for ~10 minutes.

Read one of your subscriptions (signing_key redacted).

Returns the current status of a task created by an `?async=true` intel request. Poll this endpoint until `status` is one of: `complete`, `failed`, `cancelled`, `expired`. On `complete`, the `result` field contains the same payload the sync endpoint would have returned. On `failed`, `error.message` explains the failure. Use this tool when: - You submitted an intel probe with `?async=true` and need to retrieve the result. - You want to check whether a background task finished without opening an SSE stream. Do NOT use this tool when: - You want real-time event streaming — use `stream_task` instead. - You have no task_id — submit a probe with `?async=true` first. Inputs: - `task_id` (path, required): 26-char ULID returned in the 202 response. Returns: - `status`: `pending` | `running` | `complete` | `failed` | `cancelled` | `expired`. - `result`: populated when status is `complete`. Null otherwise. - `error`: populated when status is `failed`. Null otherwise. - `expires_at`: tasks expire 1 hour after creation. Cost: - Free. Does not count against rate limits. Latency: - Typical: <100ms.

Spec 097 FR-010 / ADR-034. Returns the tool registry generated from openapi.yaml: one entry per operation with its version, status (active / deprecated / retired), lens and schema hash, plus the `registry_hash` over the whole set. Retired entries stay listed. No database read: the registry is compiled into the running Worker. Freshness: `observed_at` is the response time, `valid_until` is 24 hours later, `stale_if_error` is 86400 seconds. `deployed_at` is the Worker version timestamp, or null when the runtime does not expose it. Add `?receipt=true` for a signed Receipt v1.0 over the same payload.

The over-time layer behind the site's website map (the radar's evolution). Every domain verify appends the domain's machinery tuple — origin AS, RPKI state, announced prefix, network country, CDN, certificate authority, registrar, owning entity, and the per-lens coverage tri-states — to an append-only change-log, one row per observed change (plus a daily heartbeat row per looked-up domain). Honesty contract: `first_recorded` is when the observatory first looked at this domain — never presented as when the machinery came to exist. History accretes from real lookups starting 2026-08-04; a domain nobody has verified has zero rows, which is itself the honest answer.

Checks whether a domain or ASN belongs to a known AI company's infrastructure and what sovereignty it CLAIMS (program, zone, HQ), the baseline GhostRoute scores routing reality against. Use this tool when: - You want to know "whose AI infrastructure is this, and what does it claim?" - You are enriching an endpoint before deciding whether to send it inference. Inputs: - `entity` (path, required): a domain or ASN (AS####). Returns: - `matched`, `match_basis` (domain|asn), `ai_company`, `ai_product`, `sovereign_ai_program`, `claimed_sovereign_zone`, `hq_country`, `verified_sovereign`. Latency: - Typical <300ms (cached corpus read).

Returns GhostRoute's ownership-graph record for an autonomous system: the registrant/parent organisation, its HQ country and sovereign zone, RIR, and cloud/AI-infrastructure flags. The long-term moat — who actually owns the network a route originates from. Use this tool when: - You have an origin ASN and need its corporate owner + jurisdiction. - You are assessing whether an ASN belongs to a cloud front or the real operator. Inputs: - `asn` (path, required): AS#### or a bare AS number. Returns: - `registrant_org`, `parent_org`, `parent_org_country`, `sovereign_zone`, `rir`, `is_cloud_provider`, `is_ai_infrastructure`, or `{matched:false}`. Latency: - Typical <300ms (cached corpus read, RDAP fallback on a miss).

GhostRoute is TunnelMind's fourth lens: routing-integrity / sovereignty verification. It answers "is this infrastructure where it claims to be, owned by who it claims, routing where it says — and does that match the sovereign jurisdiction it asserts?" It resolves the originating ASN owner, RPKI validity, the certificate-issuing CA's jurisdiction, and matches the subject against a curated AI-infrastructure corpus to recover any sovereignty CLAIM (e.g. an "EU-sovereign" AI service), then scores reality against claim. Use this tool when: - An agent is about to route data/inference to an endpoint that claims a jurisdiction (e.g. EU data residency, FedRAMP, sovereign-AI). - You want to detect a US-fronted (Cloudflare/AWS/GCP) endpoint masquerading as sovereign-EU infrastructure, an RPKI-invalid origin (possible hijack), or a sanctioned operator. Inputs: - `entity` (path, required): an IPv4/IPv6, domain, ASN (AS####), or cert SHA-1/256. - `receipt` (query, optional): when `true`, issues a signed, persisted GhostRoute receipt (GR-YYYY-NNNNNNN) instead of an ephemeral verdict. Returns: - `sovereign_tier`: VERIFIED | PLAUSIBLE | MISMATCH | CRITICAL_MISMATCH (or null if no claim). - `sovereign_integrity`: [0,1] score; `origin_as`, `rpki_status`, `cert_ca`, `claimed_sovereign_zone`, `is_ai_infrastructure`, `ai_owner`, `sanctions_match`. - `_meta.caveats` / `_meta.penalties`: what was and wasn't determinable. Latency: - Typical 300-900ms on a cold subject (live BGP/RPKI/cert lookups), faster when cached.

Returns the durable, deduplicated ledger of CT equivocation events the GhostRoute witness worker detects and pushes — a tree_size_rewind (an append-only log shrank), a root_fork (one tree_size witnessed with two different Merkle roots = a split-view log), or an sth_signature_invalid (a log's latest Signed Tree Head failed signature verification). Where `/v1/ghostroute/witness` shows live computed health, this is the immutable first-detection log: each entry's `detected_at` is when TunnelMind first raised the alarm. A healthy CT ecosystem returns an empty feed — any row here is a serious trust event. Use this tool when: - You want a chronological record of CT trust violations, not live state. - You're polling for new equivocation events (check `summary.last_detected_at`). Inputs: - `limit` (query, optional): max recent alerts, 1–200, default 50. Returns: - `summary`: `total`, `undelivered`, `rewinds`, `forks`, `bad_signatures`, `last_detected_at`. - `alerts[]`: each `kind`, `severity`, `log_url`, `log_operator`, `from_tree_size`, `to_tree_size`, `distinct_roots`, `event_observed_at`, `detected_at`, `delivered`. Latency: - Typical <200ms (KV-cached 1m).

Returns GhostRoute's per-cert inclusion proofs: each is a cryptographic demonstration that the exact certificate a host serves is included in an append-only CT log whose root TunnelMind signature-verified — upgrading "a monitor said this cert exists" to "proven in a log we witness". Failed attempts are included with a `reason`; a cert that suddenly cannot be proven is itself a signal. Use this tool when: - You want to know whether a specific AI host's live cert is provably logged (pass `domain`), or - You want the corpus-wide proof rollup across watched hosts (omit `domain`). Inputs: - `domain` (query, optional): a hostname to filter to; omit for corpus-wide. - `limit` (query, optional): max recent rows, 1–200, default 50. Returns: - `domain` (echo, null when corpus-wide). - `summary`: `total_attempts`, `proven`, `unproven`, `domains`, `last_observed_at`. - `recent[]`: recent attempts (`log_operator`, `leaf_index`, `tree_size`, `sth_root_hash`, `inclusion_proven`, `reason`, ...). - `by_domain[]`: per-host `attempts` / `proven` rollup. Latency: - Typical <300ms (KV-cached 5m).

Returns GhostRoute's first-party Certificate-Transparency witness state: the latest signature-verified Signed Tree Head (STH) for every trusted, non-Google CT log TunnelMind independently witnesses, plus a regression scan over our own append-only history. Proof the platform holds its own signature-checked roots rather than reselling crt.sh/certspotter. Use this tool when: - You want corpus-wide CT witness health, not one cert. - You need to know whether any CT log misbehaved (rewound, forked, or served an STH whose signature did not verify) — a serious trust event. Inputs: - none. Returns: - `summary`: `logs_witnessed`, `verified_logs`, `unverified_logs`, `all_verified`, `total_snapshots`, `regressions`, `last_observed_at`. - `logs[]`: per-log latest STH (`log_url`, `log_operator`, `tree_size`, `sth_timestamp`, `root_hash`, `signature_verified`, `snapshots`). - `regressions[]`: detected violations — `kind` is `tree_size_rewind`, `root_fork`, or `sth_signature_invalid` (empty array = healthy). Latency: - Typical <300ms (KV-cached 5m; the witness worker updates twice a day).

Retrieves a previously-issued, signed GhostRoute receipt by its GR-YYYY-NNNNNNN id, for independent audit of a past sovereignty verdict. Use this tool when: - You hold a GhostRoute receipt id and want to confirm its contents/signature. - You are reconciling an agent's action log against the attestation layer. Inputs: - `receipt_id` (path, required): GR-YYYY-NNNNNNN. Returns: - The full persisted receipt row (routing, cert, sovereignty fields + signature). Latency: - Typical <200ms (single indexed read).

Returns a minimal status object confirming the API is alive. Use this to verify connectivity before chaining other calls, or as a liveness check in a workflow. Use this tool when: - You need to verify the API is reachable before starting a multi-step investigation. - A prior call failed with a 503 or 504 and you want to confirm the service recovered. - You are debugging connectivity from a new environment. Do NOT use this tool when: - You want actual tracker data — use `get_domain` or `search` instead. - You want to check a specific domain — this returns nothing domain-specific. Inputs: - None. Returns: - `ok`: always true if the API is up. - `ts`: ISO 8601 timestamp of the server's current time. Cost: - Free. No API key required. Not rate-limited. Latency: - Typical: <50ms, p99: <200ms.

Probes a domain for known AI agent integration signals: `llms.txt`, `ai.txt`, `/.well-known/ai-plugin.json`, `openapi.json`, `swagger.json`, MCP manifest, MCP SSE endpoint. Returns a score based on the count of signals detected. Use this to assess whether a domain is ready for agent-to-agent interaction. Use this tool when: - You want to know whether a domain exposes an MCP server or OpenAPI spec for agents. - You are cataloguing the AI-agent-ready surface of a set of domains. - You need to decide whether to attempt programmatic API access to a domain. Do NOT use this tool when: - You need tracker/surveillance data about the domain — use `get_domain` instead. - You need the robots.txt AI crawler policy — use `intel_robots` instead. - You need HTTP security posture — use `intel_http` instead. Inputs: - `domain` (query, required): Domain to probe. Returns: - Boolean flags per signal (`llms_txt`, `ai_plugin`, `openapi`, `mcp_manifest`, `mcp_endpoint`, `mcp_sse`). - `agent_surface_score`: integer 0-8, count of signals detected. Cost: - Free. No API key required. Latency: - Typical: 2-5s (parallel probes), p99: 8s.

Makes a live HEAD request to the target domain from the Cloudflare edge, follows up to 5 redirects, and returns the full redirect chain, final HTTP status, key response headers, a security header score, and any third-party surveillance actors referenced in the Content-Security-Policy header. Use this tool when: - You want to verify whether a site enforces HTTPS and HSTS. - You need to inspect what third-party scripts a site loads via its CSP header. - You are assessing a domain's security posture before trusting it. - You want to detect surveillance actors embedded in a site's CSP. Do NOT use this tool when: - You need tracker database data (category, score, entity) — use `get_domain` instead. - You need the technology stack (CMS, framework) — use `intel_stack` instead. - You need robots.txt AI crawler policy — use `intel_robots` instead. Inputs: - `domain` (query, required): Domain to probe. Can include or omit `https://`. Examples: `nytimes.com`, `https://example.com`. Returns: - `reachable`: false if the domain did not respond within 6 seconds. - `redirect_chain`: each hop with URL, status code, and Location header. - `security_headers.score`: 0-100 based on presence of HSTS, CSP, X-Content-Type, X-Frame-Options, Referrer-Policy. - `security_headers.missing`: list of headers absent. - `csp_actors`: known surveillance actors detected in the CSP header. - `error`: set if the connection failed. Cost: - Free. No API key required. Latency: - Typical: 1-3s (outbound fetch), p99: 6s (timeout). Plan for async if chaining calls.

Fetches a domain's homepage and checks for content patterns that could constitute prompt injection attacks against AI agents that visit and ingest the page. Signals include hidden text, invisible divs, `<!-- AI: ignore -->` style comments, and known injection patterns. Use this tool when: - You are vetting a domain before feeding its content into an LLM context. - You want to assess the prompt injection risk of a URL before browsing it with an agent. - You are auditing a set of domains for adversarial AI content. Do NOT use this tool when: - You want tracker surveillance data — use `get_domain` instead. - You want AI training opt-out signals — use `intel_optout` instead. - You want the agent surface (MCP/OpenAPI) — use `intel_agent` instead. Inputs: - `domain` (query, required): Domain to scan. Returns: - `injection_signals`: list of signal types detected (e.g., `hidden_text`, `ai_instruction_comment`, `invisible_div`). - `risk_level`: `none`, `low`, `medium`, or `high` based on signal count and type. Cost: - Free. No API key required. Latency: - Typical: 2-4s (HTML fetch), p99: 7s.

Checks a domain for all known AI training data opt-out mechanisms beyond robots.txt: TDM (Text and Data Mining) reservation headers, `<meta name="ai">` tags, Creative Commons NonCommercial licenses, and other machine-readable opt-out signals. Use this tool when: - You need to determine whether a domain has opted out of AI training data collection. - You are checking compliance before using a domain's content in a training dataset. - You want a comprehensive opt-out status (robots.txt + TDM + meta tags combined). Do NOT use this tool when: - You only need robots.txt crawler policy — use `intel_robots` instead (faster). - You need tracker data — use `get_domain` instead. - You want injection risk assessment — use `intel_inject` instead. Inputs: - `domain` (query, required): Domain to probe. Returns: - `tdm_reservation`: true if the domain sends a `TDM-Reservation: 1` header. - `noai_meta`: true if the HTML contains `<meta name="robots" content="noai">`. - `license_detected`: string if a CC NonCommercial or similar license is detected, otherwise null. - `opted_out`: true if any opt-out signal is present. Cost: - Free. No API key required. Latency: - Typical: 2-4s, p99: 7s.

Retrieves the target domain's `robots.txt` file and parses it for AI crawler disallow rules. Specifically detects policies for known AI crawlers (GPTBot, ClaudeBot, CCBot, Bytespider, etc.) and returns a structured summary of the crawling policy. Use this tool when: - You need to know whether a domain has opted out of AI training data collection. - You want to check if a specific AI crawler is blocked before citing the domain. - You are building a dataset of AI-accessible vs AI-blocked domains. Do NOT use this tool when: - You want training opt-out signals beyond robots.txt (TDM reservation, noai meta) — use `intel_optout` instead. - You want the full technology stack — use `intel_stack` instead. - You need tracker database data — use `get_domain` instead. Inputs: - `domain` (query, required): Domain to probe. Returns: - `robots_txt_found`: false if the domain returned 404 or the file is empty. - `ai_crawlers_blocked`: list of AI crawler user-agent names that are disallowed. - `all_blocked`: true if `User-agent: *` with `Disallow: /` is present. - `raw`: first 4096 characters of the robots.txt file. Cost: - Free. No API key required. Latency: - Typical: 1-2s, p99: 6s.

Fetches up to 32KB of the domain's HTML and response headers from the edge, then fingerprints the content for known CMS platforms, JavaScript frameworks, CDN providers, and analytics tools. Detection is based on meta generator tags, script src patterns, response headers, and cookie names. Use this tool when: - You need to know what CMS (WordPress, Drupal, Shopify) a site runs. - You are assessing a domain's infrastructure before a security review. - You want to identify analytics or marketing tools a site embeds. Do NOT use this tool when: - You want HTTP headers and security posture — use `intel_http` instead. - You want tracker database classification — use `get_domain` instead. - You need robots.txt AI policy — use `intel_robots` instead. Inputs: - `domain` (query, required): Domain to fingerprint. Returns: - `cms`: detected content management system, or null. - `frameworks`: JavaScript/backend frameworks detected. - `cdn`: CDN provider detected, or null. - `analytics`: analytics and tracking tools detected. - `meta_generators`: raw meta generator tag values. Cost: - Free. No API key required. Latency: - Typical: 2-4s (HTML fetch), p99: 7s.