Make your first API call

Summary#

This page takes you from nothing to a parsed analysis response. You will confirm the account is on the Enterprise plan, mint an API key, call POST /api/v1/analyze for a domain, read the response, and check that the call was metered. Budget about five minutes and 6 credits.

Purpose#

The API has few moving parts but three of them fail silently if you skip a step: the plan gate, the one-time key display, and the credit cost. Working through this page once means the next integration is a copy-paste.

Requirements#

• An account on the Enterprise plan.
• At least 6 credits remaining in the current month's allowance.
• curl and a JSON viewer such as jq. Any HTTP client works.
• A signed-in browser session, to read a session token once.

Permissions#

You must be the account owner, or hold that account's credentials. Team members cannot create keys for a workspace owner. See Authentication for the full permission model.

Navigation Path#

Dashboard → Account to confirm the plan and watch credits, then the terminal for everything else.

Step-by-Step Guide#

Step 1: Confirm the plan#

Open Dashboard → Account. The Plan tile in the hero must read Enterprise. If it does not, the key endpoints will refuse you with an upgrade_required message naming Enterprise. See Enterprise and custom agreements.

Note the Usage tile as well. It shows used / quota for the current month. Enterprise includes 10,000 credits a month; your first call will cost 6.

Step 2: Read a session token#

In the browser console on the dashboard:

const k = Object.keys(localStorage).find(k => /^sb-.*-auth-token$/.test(k));
copy(JSON.parse(localStorage.getItem(k)).access_token);

The token is now on your clipboard. It is short-lived and account-wide, so use it for the next step and then discard it.

Step 3: Create an API key#

export MV_SESSION="PASTE_YOUR_SESSION_TOKEN"

curl -sS -X POST https://metricvaultai.com/api/keys/create \
  -H "Content-Type: application/json" \
  -d "{\"token\": \"$MV_SESSION\", \"name\": \"quickstart\"}"

{
  "ok": true,
  "key": "mv_live_3f9a1c7d4b28e05a6f13c9d720b48e1a5c6d7f0293a4b1c8",
  "name": "quickstart"
}

Copy key now. It is never shown again. Put it somewhere your shell can reach it:

export MV_API_KEY="mv_live_3f9a1c7d4b28e05a6f13c9d720b48e1a5c6d7f0293a4b1c8"

Step 4: Make the call#

curl -sS -X POST https://metricvaultai.com/api/v1/analyze \
  -H "Authorization: Bearer $MV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "stripe.com"}' | jq .

The call is synchronous and typically takes several seconds, because a model call happens inside it. Do not set an aggressive client timeout on your first attempt.

Step 5: Read the response#

{
  "ok": true,
  "url": "stripe.com",
  "analysis": {
    "domainAuthority": 92,
    "seoScore": 88,
    "estimatedTraffic": "14.6M/mo",
    "brandSentiment": "Very Positive",
    "sentimentScore": 91,
    "marketPosition": "Category leader in developer-first payments infrastructure",
    "contentGapScore": 34,
    "threatLevel": "Low",
    "topKeywords": [
      "payment processing",
      "online payments api",
      "subscription billing",
      "payment gateway",
      "checkout integration"
    ],
    "competitors": ["adyen.com", "paypal.com", "squareup.com"],
    "opportunities": [
      "Expand comparison content against regional processors",
      "Deepen localized documentation for EU markets"
    ],
    "weaknesses": [
      "Thin coverage of small-business pricing queries",
      "Few pages targeting migration intent"
    ],
    "summary": "Stripe holds a dominant position in developer-oriented payments search, with high authority and broad branded demand. The clearest headroom is in comparison and migration content, where regional competitors currently rank."
  }
}

Every field is documented in POST /api/v1/analyze. ok and url are envelope fields; the payload you want is analysis.

Step 6: Confirm it was metered#

Reload Dashboard → Account. The Usage tile has advanced by 6. API calls are recorded against the tool name domain_overview and appear in the same monthly totals as work done in the app. See Tracking your usage.

Step 7: Clean up or keep going#

If this was a one-off test, revoke the key:

curl -sS -X POST https://metricvaultai.com/api/keys/list \
  -H "Content-Type: application/json" \
  -d "{\"token\": \"$MV_SESSION\"}" | jq '.keys[] | {id, name, masked}'

curl -sS -X POST https://metricvaultai.com/api/keys/revoke \
  -H "Content-Type: application/json" \
  -d "{\"token\": \"$MV_SESSION\", \"id\": 7}"

If you are building something real, move the key into your secret manager and read Rate limits and quotas before you put the call inside a loop.

Examples#

while read -r domain; do
  curl -sS -X POST https://metricvaultai.com/api/v1/analyze \
    -H "Authorization: Bearer $MV_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"url\": \"$domain\"}" \
    | jq -c '{url, score: .analysis.seoScore, threat: .analysis.threatLevel}'
  sleep 2
done < domains.txt

Troubleshooting#

FAQs#

How much does the first call cost? 6 credits, taken from the owning account's monthly allowance the moment the call succeeds. Failed calls that stop at a gate are not charged.

Can I try it without spending credits? No. There is no sandbox, no test key and no free tier for the API. If you want to see the product's output without spending, run a tool in the dashboard or use the public free tools described in Free tools.

What should I pass as url? A bare domain like example.com works, and so does a full URL. The value is passed through to the analysis as the subject.

Is the response cached? No. POST /api/v1/analyze runs a fresh analysis on every call and charges every call. The shared caching described in Result caching and freshness applies to dashboard tools, not to this endpoint.

Can I run several calls in parallel? Yes, but the hourly fair-use limit and your monthly quota still apply. See Rate limits and quotas.