API overview

Summary#

Metric Vault exposes one public REST endpoint, POST /api/v1/analyze, which returns a structured competitive analysis for a domain. It is authenticated with a long-lived API key that begins with mv_live_, and it is gated to the Enterprise plan: the plan is re-checked on every single call, not just when the key is created. Each call costs 6 credits from the owning account's monthly allowance.

Everything else at /api/* on metricvaultai.com exists to serve the web application and the browser extension. Those routes are documented in All endpoints so that developers and support engineers can reason about them, but they are not a supported integration surface and their shapes can change without notice.

Purpose#

Most work in Metric Vault assumes a person at a keyboard, running a tool and reading the result. The API exists for the cases where that shape is wrong: pulling a domain analysis into a client-facing dashboard, refreshing a portfolio of sites on a nightly schedule, or feeding results into a reporting warehouse that already holds the rest of your data.

Because a key acts on behalf of a paying account and spends its credits, the design is deliberately narrow rather than broad. One endpoint, no scopes, a hard cap of five active keys, a plan check on every request, and an instant revoke. That narrowness is the point: a credential that can do exactly one thing is a credential you can hand to a pipeline without auditing what else it might reach.

Overview#

The Enterprise gate#

A call from an account that is not on Enterprise returns HTTP 403 with:

{
  "error": "This feature requires the Enterprise plan. Your account is on Pro. Upgrade to unlock it.",
  "code": "upgrade_required",
  "current_plan": "pro",
  "required_plan": "enterprise",
  "upgrade_url": "https://metricvaultai.com/pricing"
}

See Enterprise and custom agreements for what else the plan includes, and Full plan comparison for how the tiers differ.

Base URL and transport#

There is no separate API host, no sandbox host, and no test-mode key. A key of the form mv_live_ is the only key type, and calls run against live data and spend live credits.

Versioning#

The version lives in the path: /api/v1/. There is currently one version. New capabilities will be added as new paths under /api/v1/ where they are additive, and a breaking change would arrive as /api/v2/ rather than as a silent change to v1. There is no version header and no date-pinning mechanism.

What the API does today#

POST /api/v1/analyze accepts a domain and returns a single JSON object covering authority and SEO scores, estimated traffic, brand sentiment, market position, a content-gap score, a threat level, top keywords, competitors, opportunities, weaknesses, and a short written summary. The complete field list is in POST /api/v1/analyze.

What the API does not do#

Being clear about this saves an afternoon:

• There is no endpoint for the other tools. The ~70 dashboard tools are not exposed publicly. A key cannot run a Site Audit, a Gap Finder or an Article Writer run.
• There is no read API for your data. A key cannot list your saved results, your monitored competitors, your team, your usage or your billing.
• There are no scopes and no per-key limits. Every key does the same one thing with the same account credits behind it.
• There are no outbound webhooks for API calls. The endpoint is synchronous: you get the analysis in the response. The only outbound webhooks in the platform belong to Competitor Monitor and rank alerts, described in Webhooks.
• There is no bulk endpoint. To analyze forty domains you make forty calls.
• There is no official SDK. Code examples gives you working curl, JavaScript and Python.
• There is no key-management screen in the dashboard. Keys are created and revoked through the endpoints in Authentication.

How it works#

The request path#

Every request to metricvaultai.com reaches a single Cloudflare Pages Worker before anything else. The Worker matches the path against an ordered chain of route checks and answers /api/* itself; anything it does not recognize falls through to the static site. POST /api/v1/analyze is one branch of that chain.

Inside the handler, four things happen in order, and the request stops at the first one that fails:

1. Credential check. The Authorization header is parsed for a bearer token. The key is looked up and must exist and not be revoked.
2. Plan check. The key's owning email is resolved to its current plan and must be Enterprise.
3. Quota check. The account's credit usage for the current UTC month is compared against its plan allowance, with the 6-credit cost of this call included. Suspended accounts are refused here.
4. Analysis. Only now does the upstream model call run. On success, usage is incremented, the key's last_used_at timestamp is updated, and the analysis is returned.

Because metering happens after the gates and before the response, a call that returns 200 has always been charged, and a call that returns 401 or 403 has never been charged.

Identity and metering#

A key is bound to one email address, the account that created it. That account's plan, credits and suspension state govern the key. Usage from the API appears in the same monthly figures as work done in the app, recorded against the tool name domain_overview, so the Account screen's usage tile includes it. See Tracking your usage.

Failure behavior#

The gates are deliberately conservative. If the plan lookup or the quota lookup cannot complete, the request is refused with 503 and a plan_check_failed or quota_check_failed code rather than being let through unmetered. Retry those; they are transient. Every response code is enumerated in Error codes.

Where to go next#

• Authentication to get a key.
• Make your first API call to make the first call.
• POST /api/v1/analyze for the full endpoint contract.
• Rate limits and quotas before you put a call inside a loop.