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.
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.
curl -s https://metricvaultai.com/api/v1/tools \
-H "Authorization: Bearer $MV_API_KEY"{
"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
}
]
}| Field | Meaning |
|---|---|
tool | The string to send as tool on a run. Stable; treat it as the identifier |
label | The tool's name as the dashboard shows it |
description | One line on what it produces |
input | Which kind of value input must be: domain, keyword, brand, topic or url |
credits | What 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.
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#
| Field | Required | Meaning |
|---|---|---|
tool | yes | A tool value from the catalog |
input | yes | The single value that tool takes, of the kind its input names |
country | no | Two-letter market code, where the tool supports one |
device | no | desktop or mobile |
range | no | Time window, where the tool supports one |
intent | no | Search 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#
| Field | Meaning |
|---|---|
ok | true on a delivered run |
tool | The tool that ran |
label | Its name |
input | The input it ran on, trimmed |
credits | What this run cost |
result | The 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.
| Status | code | Cause |
|---|---|---|
| 401 | no_key | No Authorization: Bearer header |
| 401 | bad_key | The key is unknown or revoked. The two are deliberately not distinguished |
| 403 | upgrade_required | The key owner's plan does not include API access |
| 400 | unknown_tool | No such tool. The response points at the catalog |
| 400 | no_input | input was missing. The response names the kind of input wanted |
| 403 | account_suspended | The 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.
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?
Thanks — feedback noted for the docs team.