Skip to content
Metric VaultHelp Center
Open app

Tool endpoints

The catalog and runner endpoints, which let one API key run any of the tools that take a single input, with the same cost and metering as running them by hand.

Last updated 2026-10-29

Summary#

Two endpoints let one API key reach the tools that take a single input. GET /api/v1/tools returns the catalog, and POST /api/v1/run runs one of them. Both are authenticated by an mv_live_ key, both re-check the key owner's plan on every call, and a run costs exactly what the identical run costs in the dashboard and is metered, logged and saved the same way.

They exist because POST /api/v1/analyze is a single fixed report. Anything else a script wanted, keyword research most of all, was not reachable at all.

Overview#

Why only some tools#

Not every tool can be driven without a person. The catalog is the set whose entries take exactly one value, which is what makes it safe to fill in from a sentence: there is no second field to guess wrong. There are 48 of them. Tools that compare two things or need a set of options are deliberately absent, among them Gap Finder, Competitor Battle, Backlink Gap, Content Optimizer and SEO Compare. Those are still available in the dashboard.

This is the same list the in-app Specialist uses, so the API cannot drift away from it. A tool added there becomes callable here the same day.

What a caller has to know#

Three things, all of them in the catalog response: the string to send as tool, which kind of input it wants, and what it costs. Nothing on this page requires reading source to find.

Authentication#

Send the key as a bearer token. See Authentication.

text
Authorization: Bearer mv_live_...

The key belongs to one account. It is never shared with a teammate, and the plan is re-checked on every call rather than trusted from the moment the key was created, so a cancelled or downgraded account stops working immediately. Creating and revoking keys is covered in API keys.

An API key is accepted only on /api/v1/ routes. Presenting one anywhere else in the product authenticates nothing, which is what keeps a key limited to the capability it is documented to have.

GET /api/v1/tools#

Returns every tool this key can run. No body, no cost.

bash
curl -s https://metricvaultai.com/api/v1/tools \
  -H "Authorization: Bearer $MV_API_KEY"
json
{
  "ok": true,
  "count": 48,
  "tools": [
    {
      "tool": "keyword_overview",
      "label": "Keyword Overview",
      "description": "Volume, difficulty, intent, SERP and questions for one keyword",
      "input": "keyword",
      "credits": 3
    }
  ]
}
FieldMeaning
toolThe string to send as tool on a run. Stable; treat it as the identifier
labelThe tool's name as the dashboard shows it
descriptionOne line on what it produces
inputWhich kind of value input must be: domain, keyword, brand, topic or url
creditsWhat one run costs this account, including any admin override

The credits figure is read live from the same source the dashboard quotes, so it reflects an override rather than a published table that has gone stale.

POST /api/v1/run#

Runs one tool and returns its result.

bash
curl -s https://metricvaultai.com/api/v1/run \
  -H "Authorization: Bearer $MV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"keyword_overview","input":"seo software"}'

Request#

FieldRequiredMeaning
toolyesA tool value from the catalog
inputyesThe single value that tool takes, of the kind its input names
countrynoTwo-letter market code, where the tool supports one
devicenodesktop or mobile
rangenoTime window, where the tool supports one
intentnoSearch intent filter, where the tool supports one

Any other field is ignored rather than passed on, so a caller cannot reach behaviour the endpoint does not document.

Response#

FieldMeaning
oktrue on a delivered run
toolThe tool that ran
labelIts name
inputThe input it ran on, trimmed
creditsWhat this run cost
resultThe tool's own payload. Its shape is the tool's, and differs between tools

Errors#

A refusal is returned with its real HTTP status and reason rather than a summary, so a script can tell one cause from another. See Error codes for the shared error shape.

StatuscodeCause
401no_keyNo Authorization: Bearer header
401bad_keyThe key is unknown or revoked. The two are deliberately not distinguished
403upgrade_requiredThe key owner's plan does not include API access
400unknown_toolNo such tool. The response points at the catalog
400no_inputinput was missing. The response names the kind of input wanted
403account_suspendedThe account is suspended
503—The tool is switched off, or a provider is unreachable

A run that is refused costs nothing. A run that fails partway gives its reservation back rather than holding credits.

Cost and metering#

A call spends credits from the key owner's monthly allowance exactly as if the same run had been started in the dashboard, at the price in the catalog. The free technical tools cost nothing. Every run appears in that account's usage, so API spend is visible beside app spend rather than tracked separately. See Credit cost table.

Using it from an agent#

Fetch the catalog once and hand it over. An agent that can read tool, input and description can pick the right tool and fill it in without being told the names in advance, which is the reason the catalog endpoint exists rather than a list in this article that would go stale.

bash
export MV_API_KEY=mv_live_...
node scripts/mv-api.mjs tools
node scripts/mv-api.mjs run keyword_overview "seo software"

scripts/mv-api.mjs is a thin wrapper over the two endpoints, included so an agent working in the repository has a command to call rather than a URL to assemble.

See also

Was this article helpful?