API & MCP

The API exposes everything the dashboard shows and everything its settings screens change, over plain HTTPS + JSON: totals, time series and breakdowns for any site, every section of the dashboard as its own endpoint, and write endpoints for sites, settings, data sources, goals, funnels, segments, alerts, annotations, the team and API keys. All endpoints live under https://app.numative.com/api/v1/, and GET https://app.numative.com/api/v1 returns a machine-readable index of every one of them with its parameters.

The same surface is available to AI agents as an MCP server: one tool per endpoint, so an agent with a key can answer questions about your traffic or change a setting for you. The dashboard the WordPress plugin renders inside wp-admin is built entirely on these endpoints, so anything it shows can be rebuilt anywhere.

Create an API key

Go to Account > API, give the key a name, and pick a scope. The full key is shown once at creation; only its SHA-256 hash is stored, so copy it immediately. Keys look like nmv_live_... and can be revoked at any time from the same page.

• read (default): every reporting endpoint and every settings read. It can answer any question the dashboard can, and change nothing.
• write: everything a read key can do, plus every endpoint that changes something: adding and deleting sites, site settings, data sources, goals, funnels, segments, alerts, annotations, publish pings, server-side collection, the team and key revocation.

A key belongs to your organization and can access every site in it. The one thing no key can do is mint another key: new keys come from this page only, so a leaked key can always be revoked for good.

Authentication

Send the key in the Authorization header on every request:

Authorization: Bearer nmv_live_...

An x-api-key: nmv_live_... header is also accepted. For platforms that can only configure a fixed URL (log drains), a ?key= query parameter works too, but URLs may be logged by the platform, so only use it with a write-only ingest key, never a read key.

Errors are returned as JSON: {"error": "message"} with status 400 (bad input), 401 (missing/invalid key), 403 (scope), 404 (site not found for this key), or 429 (rate limited).

Connect an AI agent (MCP)

Numative is a Model Context Protocol server. Any MCP client that can send a bearer token (Claude Code, Codex, Cursor, Claude Desktop and claude.ai, your own agent) can connect to it with an API key and gets one tool per endpoint on this page: a read key gives the reporting and settings-read tools, a write key adds every tool that changes something. The agent sees only the tools its key allows, and every tool call is the corresponding API call, with the same checks and the same rate limit.

Claude Code

claude mcp add --transport http numative https://app.numative.com/api/mcp --header "Authorization: Bearer nmv_live_..."

Or in .mcp.json (project) or your user settings, with the key read from an environment variable so it is never committed:

{
  "mcpServers": {
    "numative": {
      "type": "http",
      "url": "https://app.numative.com/api/mcp",
      "headers": { "Authorization": "Bearer ${NUMATIVE_API_KEY}" }
    }
  }
}

Codex

Codex reads the token from an environment variable rather than the config file. Export NUMATIVE_API_KEY, then either run:

codex mcp add numative --url https://app.numative.com/api/mcp --bearer-token-env-var NUMATIVE_API_KEY

or add the server to ~/.codex/config.toml (shared by the CLI and the IDE extension):

[mcp_servers.numative]
url = "https://app.numative.com/api/mcp"
bearer_token_env_var = "NUMATIVE_API_KEY"

Cursor

In ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project). Cursor resolves ${env:NAME} in url and headers, so the key can stay out of the file:

{
  "mcpServers": {
    "numative": {
      "url": "https://app.numative.com/api/mcp",
      "headers": { "Authorization": "Bearer ${env:NUMATIVE_API_KEY}" }
    }
  }
}

Claude Desktop and claude.ai

Remote servers are added as a custom connector, not through a config file. Go to Customize > Connectors > Add custom connector (Team and Enterprise owners: Organization settings > Connectors > Add > Custom), enter the server URL, set Authentication to None, and under Request headers add Authorization with the value Bearer nmv_live_..., including the word Bearer and the space. Request headers are currently in beta for a limited set of organizations; if the section is not in your dialog, use the bridge below in Claude Desktop's config file instead.

{
  "mcpServers": {
    "numative": {
      "command": "npx",
      "args": ["mcp-remote", "https://app.numative.com/api/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer nmv_live_..." }
    }
  }
}

The header is written without a space after the colon on purpose: some clients mangle spaces inside args, and the environment variable carries the value intact.

ChatGPT

ChatGPT's developer mode accepts remote MCP servers that use OAuth or no authentication, and cannot send a fixed API key. Numative's server authenticates with a key, so ChatGPT cannot connect to it today. Call the REST API from a ChatGPT action or your own code instead.

The tools are named after what they answer or change: whoami, list_sites, get_stats, get_breakdown, list_pages, get_page_detail, get_anomalies, list_changes, get_errors, get_vitals, get_search_console, get_backlinks, update_site_settings, create_goal, update_alert_settings, invite_member, and so on. Each tool's description and parameters are the endpoint's, so the rest of this page is the tool reference too. The full list, with parameters, is at GET https://app.numative.com/api/v1.

Rate limits

A view that needs several endpoints should fetch them in parallel and cache the result rather than polling: the dashboard's own numbers change at the speed of the underlying data, which for everything except realtime is minutes at best.

Common query parameters

The three read endpoints share these parameters. The requested site must belong to the key's organization.

The response bucket size (interval) is derived from the range (minute for realtime, hour for today/yesterday, day and up for longer windows) and echoed in every response's range object.

range=realtime spans two windows, and every response says which one it used. stats and breakdown count the last 5 minutes, the visitors on the site right now. timeseries returns the last 30 minutes, minute by minute, so the recent traffic has a shape to read.

Filters

A filter is an object with dimension, operator, and value keys, where value is an array of strings and operator is one of is, is_not, contains, or matches. Dimensions: path, entry_page, exit_page, source, channel, referrer, utm_source, utm_medium, utm_campaign, utm_term, utm_content, country, region, city, browser, os, device, screen_class, hostname, event, plus prop:<key> for custom properties. Reading first-party data adds goal, link, outbound, affiliate, button, dead_click, form, bot_kind and collection_source; GA4 has no field behind those, so its reader rejects rather than silently ignoring them.

[{"dimension":"country","operator":"is","value":["US","CA"]}]

Live visitor badge

One endpoint takes no key at all: a visitor count, for showing "12 reading now" or "48,120 visitors this year" on your own site. Turn it on per site under Site settings > Visibility > Public visitor counts, which is also where the snippet below is generated with your site id, period and metric already in it.

Beside the switch is a dial: anyone may ask for. It is the one thing that bounds what the endpoint will answer, and it is not the same as the period on your badge. Your site id is in your page's markup and the period is a URL parameter, so a badge set to "last 30 days" withholds nothing from someone who edits the URL. The dial does.

A window past the dial answers exactly as an unpublished site does, and that includes custom ranges: the limit is measured on the window itself, never on the range's name.

<span data-numative-live="YOUR_SITE_ID">–</span> reading now

<span data-numative-live="YOUR_SITE_ID" data-numative-range="30d">–</span> visitors in the last 30 days

<span data-numative-live="YOUR_SITE_ID" data-numative-range="all"
      data-numative-metric="pageviews">–</span> pageviews all time

<script async src="https://app.numative.com/live.js"></script>

Each element's text becomes its count, formatted with thousands separators, and refreshes every 15 seconds while the page is in front of someone. The script writes nothing else, imposes no styling, and sets no cookie or storage: it reads a public number, it does not track your readers. Badges asking the same question share one request, so a page can carry as many as it likes.

Badge attributes

If you have a custom tracking domain, load live.js from it and the badge polls that domain too, so an ad blocker cannot leave a dash on your home page.

GET /api/public/live

The badge is a convenience over one endpoint. Call it yourself if you want your own markup, a server-rendered count, or a number in something that is not a web page.

curl "https://app.numative.com/api/public/live?site=YOUR_SITE_ID"
curl "https://app.numative.com/api/public/live?site=YOUR_SITE_ID&range=30d"
curl "https://app.numative.com/api/public/live?site=YOUR_SITE_ID&range=custom&from=2026-01-01&to=2026-06-30"

{
  "site": "YOUR_SITE_ID",
  "range": "5m",
  "from": "2026-08-20T22:47:00.000Z",
  "to": "2026-08-20T22:52:00.000Z",
  "visitors": 12,
  "visits": 14,
  "pageviews": 23,
  "halfHour": 47
}

Without a range, visitors counts the last 5 minutes (the same number the dashboard shows live, and the same one /api/v1/realtime returns as now) and halfHour counts the last 30. With one, the counts cover that period and halfHour is absent. range takes the same values as the keyed API, plus 5m and 30m for the live windows; custom needs from and to as YYYY-MM-DD. Every count is humans only, read from the site's primary source.

Responses send Access-Control-Allow-Origin: * and are cacheable for 10 seconds live, 60 for a period. Unlike the rest of the API a bad range is a 400 rather than a quiet fallback: a public caller asking for one window must never be handed another without being told.

GET /api/v1/stats

Headline totals for the window.

curl "https://app.numative.com/api/v1/stats?site_id=SITE_ID&range=30d" \
  -H "Authorization: Bearer nmv_live_..."

{
  "range": { "from": "2026-06-02T14:00:00.000Z", "to": "2026-07-02T14:00:00.000Z", "interval": "day" },
  "totals": {
    "visitors": 4210,
    "visits": 5124,
    "pageviews": 9876,
    "bounceRate": 0.41,
    "avgDuration": 74.2,
    "viewsPerVisit": 1.93,
    "events": 312
  }
}

bounceRate is a fraction (0 to 1), avgDuration is seconds, and events counts custom (non-pageview) events.

GET /api/v1/timeseries

Visitors, visits, and pageviews bucketed over time.

curl "https://app.numative.com/api/v1/timeseries?site_id=SITE_ID&range=7d" \
  -H "Authorization: Bearer nmv_live_..."

{
  "range": { "from": "2026-06-25T14:00:00.000Z", "to": "2026-07-02T14:00:00.000Z", "interval": "day" },
  "series": [
    { "timestamp": "2026-06-25T00:00:00.000Z", "visitors": 512, "visits": 590, "pageviews": 1204 },
    { "timestamp": "2026-06-26T00:00:00.000Z", "visitors": 486, "visits": 553, "pageviews": 1131 }
  ]
}

GET /api/v1/breakdown

Ranked rows for one dimension. Takes the common parameters plus:

property=goal ranks the site's goals rather than a stored field: each row is a goal, visitors is its unique converters and events is how many times it fired, repeated as conversions. A goal entry in filters is visit-scoped, narrowing every endpoint to the visits that converted it. Both are collector-only, so a source=ga4 read returns no goal rows.

curl "https://app.numative.com/api/v1/breakdown?site_id=SITE_ID&property=source&range=30d&limit=5" \
  -H "Authorization: Bearer nmv_live_..."

{
  "range": { "from": "2026-06-02T14:00:00.000Z", "to": "2026-07-02T14:00:00.000Z", "interval": "day" },
  "property": "source",
  "results": [
    { "value": "google.com", "visitors": 1810, "visits": 2011, "pageviews": 3902, "bounceRate": 0.38, "avgDuration": 81.5 },
    { "value": "news.ycombinator.com", "visitors": 640, "visits": 655, "pageviews": 1105, "bounceRate": 0.61, "avgDuration": 42.0 }
  ]
}

bounceRate and avgDuration describe the visits each row counts. Dimensions that don't measure visit engagement (custom events, goals, interactions, properties) omit both fields rather than reporting a fabricated 0.

GET /api/v1/realtime

Live visitors in both windows the app shows: now counts the last 5 minutes, halfHour the last 30. Also returns the 30-minute minute-grain series and the pages and sources currently active. The range is always realtime whatever you pass.

GET /api/v1/markers

Everything the dashboard flags on the traffic chart for the window, grouped by kind: detected page and site changes, Core Web Vitals regressions, backlink movement, algorithm updates, social mentions and your annotations. This is the differentiator as data, so an embedded chart can plant the same flags rather than drawing a bare line. Not source-scoped (a change is a fact about the site), but it honors the same range so the flags line up with the series you charted.

GET /api/v1/anomalies

Per-page movers for the window against the period before it: which pages rose, fell, appeared or went quiet, and by how much, each with the detected changes that might explain it. Defaults to the last 7 days. See Anomalies.

GET /api/v1/changes

The detected-change feed: page and site changes plus annotations, newest first, with per-type totals and a daily activity strip. Optional category, type, search and day filters.

GET /api/v1/changes/diff?change_id=<id> returns the word-level before and after behind one page change, computed from the stored crawl texts. Changes whose diffable flag is false predate the stored text and return 422.

GET /api/v1/goals

Conversions, conversion rate and revenue for each of the site's goals over the window. Collector-only, so a GA4-only site answers available: false.

GET /api/v1/funnels

The site's saved funnels, and the computed result for one of them: funnel_id picks which, else the first. Collector-only.

GET /api/v1/properties

The custom property keys seen in the window, and the value breakdown for one of them when property is given. Collector-only.

GET /api/v1/flow

The behavior-flow graph for the window, as nodes and links. Pass focus_path for the bidirectional path-explorer view or start_path to root a forward flow; depth sets how many steps. Collector-only.

GET /api/v1/journeys

Recent visitor journeys, newest first: one row per visitor per site-local day, with where they landed, where they left, how long they stayed and how much they did. Pass visitor=<id> for that visitor's full event stream. The id is a daily-rotating, non-reversible hash: it identifies a day's activity, not a person, and cannot be joined across days or sites. Collector-only.

GET /api/v1/activity

The live tape: one row per thing a visitor just did, newest first. Page loads, autocaptured clicks, custom events, the leave-time engagement report and captured errors, each carrying the visitor hash that did it and, as source, where that visitor entered from that day (their first pageview's referrer, empty for direct). window=5m|30m picks the realtime window (30m by default). Collector-only.

GET /api/v1/vitals

Real-user Core Web Vitals for the window: the p75 summary and experience score, the trend, and the same per-page/country/device/browser/OS tables the Speed section ranks. Pass attribution=1 for what is dragging the numbers down (LCP elements, layout-shift sources, blocking scripts), form_factor=phone|desktop to narrow to one device class, and percentile=50|75|90|99 to pick the aggregate. Measured by the snippet, so it is collector-only.

GET /api/v1/search

Search Console for the window: clicks, impressions, CTR and average position, plus top queries and pages. Returns connected: false when the site has no Search Console connection.

GET /api/v1/backlinks

The site's backlink profile in one call: stored counts, 30-day movement, top referring domains, top links, and the newest new/lost/regained events. Not source-scoped, since a site can have backlinks with no analytics. limit caps each list.

GET /api/v1/decay

Pages whose traffic is fading: peak versus current 28-day visits, the site-adjusted change, a diagnosis, and whether a refresh has been detected. Whole-site current state, so it takes no range.

GET /api/v1/site

The site's own facts, plus the billing and quota notices the app shows above the dashboard. An embedded dashboard that never learns the account is locked would otherwise show a frozen, silently stale view.

GET /api/v1/proxy-config

The site's first-party proxy parameters, for integrations that set the proxy up unattended. Requires a write-scoped key, because the response contains the proxy secret, which is exactly what a read key must never see. A site-bound ingest key resolves its own site; an org-wide write key passes ?site_id=.

GET /api/v1/errors

Client-side error groups over the window (see Error tracking): headline totals, the occurrence timeseries, and every distinct error with its stack trace. Add fingerprint=<id> for one group's expanded detail (per-page/browser/OS/device/country breakdowns and recent occurrences). Standalone-tracked sites only.

curl "https://app.numative.com/api/v1/errors?site_id=SITE_ID&range=7d" \
  -H "Authorization: Bearer nmv_live_..."

{
  "available": true,
  "summary": { "errors": 214, "groups": 6, "visitors": 102 },
  "groups": [
    {
      "fingerprint": "9f2c1a77b3e4d015",
      "kind": "error",
      "errorName": "TypeError",
      "message": "Cannot read properties of undefined (reading 'map')",
      "count": 121, "visitors": 64, "paths": 3,
      "topPath": "/pricing", "topBrowser": "Chrome",
      "firstSeen": "2026-07-14T09:12:44.000Z", "lastSeen": "2026-07-17T11:03:19.000Z"
    }
  ]
}

GET /api/v1/clicks

Autocaptured clicks over the window (see Click autocapture), grouped by the element they landed on. Honours filters and limit. Standalone-tracked sites only.

curl "https://app.numative.com/api/v1/clicks?site_id=SITE_ID&range=30d&limit=10" \
  -H "Authorization: Bearer nmv_live_..."

{
  "available": true,
  "summary": { "clicks": 5120, "visitors": 1288, "deadClicks": 96 },
  "clicks": [
    {
      "selector": "button.subscribe", "text": "Subscribe", "tag": "button",
      "url": "", "interactive": true,
      "count": 512, "visitors": 380, "topPath": "/blog", "paths": 12
    }
  ]
}

POST /api/v1/collect

Server-side collection of bot and AI-crawler visits, the requests a JavaScript tracker never sees. Requires a write-scoped key. Only bot traffic is stored; human and junk hits are dropped, so nothing is double-counted against the JS tracker. Stored bot events are never billed. The in-app setup card (your site's Settings, under AI crawler tracking) has ready-made snippets for WordPress, Cloudflare Workers, Vercel log drains, and Node built on this endpoint.

curl -X POST "https://app.numative.com/api/v1/collect" \
  -H "Authorization: Bearer nmv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "YOUR_SITE_ID",
    "events": [
      { "path": "/blog/post", "userAgent": "GPTBot/1.0", "ip": "20.15.240.64" }
    ]
  }'

{ "ingested": 1, "dropped": 0 }

POST /api/v1/ping

Instant single-page recrawl, for publish and deploy hooks. Requires a write-scoped key. The body is a single absolute url whose hostname must match one of your organization's sites (its domain, a subdomain, or an allowed host). See Change detection for where pings fit.

curl -X POST "https://app.numative.com/api/v1/ping" \
  -H "Authorization: Bearer nmv_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/blog/new-post"}'

{ "accepted": true, "path": "/blog/new-post" }

Returns 503 when the crawler is unavailable, so a hook can retry.

Annotations: /api/v1/annotations

Chart annotations (the emerald markers) can be managed from CI or a deploy pipeline. Listing works with any key; creating and deleting require a write-scoped key.

POST (create)

curl -X POST "https://app.numative.com/api/v1/annotations" \
  -H "Authorization: Bearer nmv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "kind": "deploy",
    "title": "v2.4.0 released",
    "url": "https://github.com/acme/site/releases/v2.4.0"
  }'

The created annotation row is returned as JSON.

GET (list)

GET /api/v1/annotations?siteId=<uuid> lists a site's annotations, newest first, up to 500. Optional from and to ISO 8601 timestamps bound the window. Note that this endpoint takes the site UUID, not the public snippet id.

DELETE

DELETE /api/v1/annotations?id=<uuid> removes one annotation and returns {"deleted": true}.

More reads

The rest of the dashboard, each as its own endpoint. All take the common parameters unless noted.

Sites and settings

Everything under a site's Settings, and the Sites list itself. Reads work with any key; writes need a write key, and adding or deleting a site needs an org-wide one (not a site-bound ingest key). Site ids in the path accept the UUID or the public snippet id.

curl -X PATCH "https://app.numative.com/api/v1/sites/SITE_ID" \
  -H "Authorization: Bearer nmv_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "includeBots": true, "isPublic": true, "shareLevel": "link" }'

Organization