Verinode Developer

Verinode HQ — Network API

Read your network's aggregated intelligence, programmatically.

The Network API is the HQ counterpart to the IQ operator API. Where an IQ key (vn_live_…) reads one operator's own data, a group key (vn_group_live_…) reads the network layer a headquarters sees: aggregated network health, the member roster, and each member's compliance posture. It is built for multi-location enterprises, private-equity roll-ups, franchise headquarters, and associations that already run Verinode HQ.

The privacy boundary is the same one the HQ product enforces: a network sees aggregates and compliance, never a member's raw books. Members contribute data up from their own IQ accounts; the Network API can never read down into a member's individual jobs, vendors, or financial records. Cross-network and industry benchmarks are never exposed through the API.

#Group keys

Network keys carry a distinct prefix and are minted by a network administrator in the HQ dashboard under Settings › Developer (not through the API). The secret is shown exactly once.

Authorization: Bearer vn_group_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Group keys are separate from operator keys: they resolve to a group, carry group scopes, and are metered on their own quota. They require an active HQ subscription.

#Scopes

keys:manage can be selected when minting a group key, but no endpoint requires it today — it is reserved and grants nothing. Group keys are minted in the HQ dashboard, not through the API. GET /v1/network/ping requires no scope.

#Quickstart

KEY='vn_group_live_your_secret_here'

# 1. Verify the key and echo the network it resolves to
curl -H "Authorization: Bearer $KEY" https://api.verinode.ai/v1/network/ping

# 2. Read the network-health snapshot
curl -H "Authorization: Bearer $KEY" https://api.verinode.ai/v1/network/summary

# 3. Page the member roster
curl -H "Authorization: Bearer $KEY" "https://api.verinode.ai/v1/network/members?limit=50"

#Network health

GET /v1/network/summary returns the group's latest network snapshot: membership counts, compliance rate, reputation and action-rate composites, and network margin percentiles. Sensitive metrics are suppressed until enough members report to protect any single member — a suppressed metric comes back null, and the response carries a k_anon block explaining whether each cohort threshold was met. GET /v1/network/summary/history returns the same snapshot as a time-series (most recent first, each row gated the same way) — the endpoint for syncing network rollups into your own warehouse. Both require network:read.

#Network intelligence

Three read surfaces expose the pattern layer HQ sees in-app, all under network:read:

• GET /v1/network/signals — the network signal layer: how many members hit each signal (e.g. 12 of 30 on vendor cost drift), by severity and domain. Counts only, never member attribution.
• GET /v1/network/programs — program adoption rates (carrier / TPA / vendor): active vs adopted members and adoption percentage. Rates only, never which member declined.
• GET /v1/network/process — network-wide process-mining medians (jobs, recruiting, safety, supplements): stage-to-stage median / p25 / p75 days and sample size. The cross-network industry benchmark columns are stripped.

Every enum token (signal_type, domain, severity, program_type, process) ships a humanized _label sibling, and all three are cursor-paginated.

#Members and compliance

GET /v1/network/members returns the roster — location, owner, city, state, membership status, open and invite dates — cursor-paginated. GET /v1/network/compliance returns each member's certification type, status, expiration, and carrier-program eligibility, by name. Both expose roster and status only; neither exposes a member's raw business data, contact details, or operator linkage. Require members:read and compliance:read.

#Network export

GET /v1/network/export assembles the snapshot, the full roster, and the full compliance posture into one JSON bundle — the same serialization as the individual endpoints, so it can never say more than they do. Network data is bounded, so the export is synchronous. Requires exports:read.

curl -H "Authorization: Bearer $KEY" https://api.verinode.ai/v1/network/export
→ { "data": { "manifest": { "resource_counts": {...} },
    "resources": { "summary": {...}, "members": [...], "compliance": [...] } } }

See the full shapes in the API reference.