Discovery

Drive Discovery from the CLI, MCP and API

You can start, watch and read discoveries without the web page. Three routes are available. All of them use the same credits, permissions and results as the web page.

Route Best for
Hunto CLI Terminal use and shell scripts
MCP An AI assistant that reads and starts discoveries on your behalf
API Your own code, especially for domain ratings

Before you start

  • You need a Hunto account with access to Discovery.
  • Runs cost credits, exactly as in the web page. See Credits and limits for Discovery.
  • Use the address of your own region. A sign-in or key from one region does not work in the other.

Hunto CLI

Install and sign in as described in "Hunto CLI: install, sign in and everyday use". Commands follow the pattern hunto <module> <group> <verb> [flags]. Flag names are the parameter names in kebab case, for example --character-id.

Discovery commands

Command What it does Kind
hunto discovery run list List runs Read
hunto discovery run findings Read a run's findings Read
hunto discovery run progress See how far a run has got Read
hunto discovery run subtasks See the individual checks of a run Read
hunto discovery run start Start a schedule now. Add --bypass-cache to ignore cached results. Costs credits
hunto discovery run cancel Skip checks whose results have not yet been recorded Changes data
hunto discovery run halt Stop a schedule's execution. Takes the schedule id. Changes data
hunto discovery schedule list and get Read schedules Read
hunto discovery schedule create Create a schedule, for example --character-id DS-DET-00096 --frequency ONCE Costs credits
hunto discovery detective get Read a detective Read

Run hunto discovery --help to see the commands your version offers.

Note: There is no rating command in the CLI. To rate a domain from a script, use the API below.

Example: run and read a detective once

  1. Find a detective id with hunto discovery detective get, or copy it from the Detectives tab.
  2. Create the schedule with --frequency ONCE and the assets or targets to check.
  3. Watch it with hunto discovery run progress.
  4. Read results with hunto discovery run findings.

Kinds of command

Commands that change data ask for --yes in a terminal. Commands that spend credits, such as run start, do not ask, so check the target before you run one. Exit codes: 0 success, 1 error, 2 wrong usage, 3 version mismatch, 4 not signed in, 5 no permission, 6 rate limited, 7 timed out.

MCP

Connect an assistant to your region's address:

Region Address
India https://in.hunto.ai/api/mcp
EU https://eu.hunto.ai/api/mcp

Sign-in, API keys and expiry are covered in "Connect an AI assistant to Hunto (MCP)".

Discovery uses two permissions:

Permission Lets the assistant
discovery:read List discoveries, read progress, findings, changes and the checks of a run, list detectives, presets and checks, and preview which targets or checks a detective would use
discovery:write Start a lookup or a custom set of checks, save a detective, pause, resume or cancel runs, retry checks, add results to detections, and rate domains

Domain ratings are read with the separate score:read permission.

Tip: Grant discovery:read first. Add discovery:write only when you want the assistant to start runs, because starting a run spends credits.

When you run the Hunto CLI as an MCP server, it starts read-only. Add --allow-costly to permit runs and --allow-write to permit changes.

Example prompts

  • "List my discoveries from the last week and tell me which failed."
  • "Show what changed in the latest Outside-in rating run for example.com."
  • "Rate example.com and tell me the top three issues." (Starts a run, so the permission and credits are needed.)

API

The API is for rating domains and reading ratings and posture from your own code.

Authenticate

Create an API key in API Management. Send it with every request as either:

  • Authorization: Bearer hnt_..., or
  • x-api-key: hnt_...

If your account belongs to more than one organisation, add x-tik-workspace to choose one.

Endpoints

Method and path Purpose
POST /ratings Rate a domain. Returns 202 when a new run is started, or the latest rating if a fresh one exists.
GET /ratings/methodology The published scoring method
GET /ratings/{domain} The latest rating for a domain
GET /ratings/{domain}/findings Findings behind that rating
GET /ratings/{domain}/history The rating over time
GET /ratings/{domain}/runs Runs for that domain
GET /runs/{runId}/rating The rating of one run
GET /runs/{runId}/results The raw results of one run
GET /posture Your organisation's own posture
GET /posture/standard, /posture/findings, /posture/history The standard, findings and history for that posture

Bodies are JSON, up to 1 MB.

Errors

Status Meaning
400 Bad request
401 Missing or invalid key
402 Not enough credits
403 The key does not allow this
404 Not found
409 Conflict, for example a run already in progress
422 The domain or input is not valid
429 Too many requests

Use cases and wiring tips

  • Nightly rating of a vendor list. Loop over the domains with POST /ratings. A domain that already has a fresh shared rating returns it instead of starting a new run.
  • Dashboard. Read GET /ratings/{domain}/history into your own dashboard.
  • Assistant triage. Give an assistant discovery:read and detections:read, and ask it to summarise new findings each morning.
  • Wiring. Runs started from the CLI, MCP or API appear in Discoveries like any other run. Use the run report to review them.