Risk Scoring

Scoring Through the API and MCP

You can read your ratings, and start a rating, from your own tools. There are two routes: the versioned HTTP API under /api/v1, and the MCP server for AI assistants. The Hunto command-line tool has no scoring commands today.

Before you start

  • Use an API key (or a signed-in session) from API Management. A key acts as its owner, inside the owner's organisation.
  • Reading needs no admin role. Starting a rating spends credits, so the key's owner needs permission to run discovery.
  • Keep keys short-lived and give each integration its own.

The /api/v1 endpoints

Method and path What it returns
GET /api/v1/ratings/methodology The published methodology: sections, weights, severity weights, grade bands
POST /api/v1/ratings with {"domain": "example.com"} Starts an Outside-in rating of a domain, or answers straight away if one can be reused
GET /api/v1/ratings/{domain} The standard rating of one domain
GET /api/v1/ratings/{domain}/findings What each section counts, with points and why
GET /api/v1/ratings/{domain}/history The domain's ratings over time
GET /api/v1/ratings/{domain}/runs The runs of that domain with their ratings
GET /api/v1/runs/{runId}/rating One run's rating
GET /api/v1/runs/{runId}/results Every result of a run and where it went: counted, context, or not a rating check
GET /api/v1/posture Your organisation's security score
GET /api/v1/posture/standard Your organisation's standard rating
GET /api/v1/posture/findings The findings behind your security score
GET /api/v1/posture/history Your security score over time

Useful query parameters: section and counting=true on findings (only counted findings), days on history, refresh=true to recompute before reading.

What the answers contain

A rating includes the grade, the score, whether it is provisional, when and from which run it was made, and each section with its state (measured, not measured, locked), its weight and what it costs. Every number can be re-derived from the sections and the methodology, so you can check a figure without trusting the total.

Status codes

/api/v1 answers with real HTTP status codes.

Code Meaning
200 Answer returned
202 A rating run was started. Poll GET /api/v1/ratings/{domain} until the grade appears
401 Missing, revoked or expired key
402 Not enough credits (INSUFFICIENT_CREDITS)
403 You may not do this
404 Nothing rated yet for that domain or run
422 The request was not valid
429 Too many requests

Rating a domain from the API

  1. POST /api/v1/ratings with the domain.
  2. If another organisation has shared a rating of the domain, you get it back immediately, free, with source set to shared. See Sharing, vendor view and domain verification.
  3. Otherwise a run is started for the price shown in the response (10 credits for an Outside-in rating; a run for the same domain in the last 24 hours is reused at no charge) and you get 202.
  4. Poll GET /api/v1/ratings/{domain}.

Note: for a domain read, the API returns the newer of your own rating and the shared outside-in rating, in the limited shape that sharing allows. Your own run details are not part of a shared answer.

MCP

The MCP server offers scoring tools under the score permission (score:read is enough). The assistant can call:

  • the scorecard tools: get a scorecard, its findings, the runs of a domain, the latest rating of up to 200 domains at once, its history, what changed between ratings, and the published methodology;
  • the older score tools for the current score, its history and score reports.

To start a rating, the assistant also needs discovery:write, which is what allows a run that spends credits. Grant read only if you want an assistant that only looks.

Tip: ask the assistant to run myAgentAccess to see which scoring tools it may use. See Connect an AI assistant to Hunto (MCP) for setup.

Command line

The Hunto CLI does not have scoring commands. Use the API above from a script, or the MCP mode of the CLI with the tools above.

Use cases and wiring tips

  • Gate vendor onboarding on grade: call POST /api/v1/ratings for the vendor's domain, poll until you get a grade, and block the onboarding step below your threshold (for example below C, or any provisional grade). Store the grade and date with the vendor record.
  • Alert when a grade drops: poll GET /api/v1/posture/standard daily and compare with yesterday's value, or read /api/v1/posture/history?days=30 and alert on a fall of one band. Post it to your chat tool. Do not rely on a built-in alert: see Use cases and wiring tips.
  • Feed a dashboard: read GET /api/v1/posture/history and .../findings?counting=true into your BI tool for a board trend and a top-issues list.
  • Ask an assistant: "Which counted issue costs the most points on our standard rating, and which asset is it on?" The assistant reads the findings and answers with points.
  • Rate all your domains in bulk: read GET /api/v1/ratings/{domain} for each, and POST /api/v1/ratings only for the ones with 404. Keep credits in mind: each new run costs 10 credits.