Hunter-Seeker Docs For agents This page as markdown

Agent signup

An agent with no human present can get a working Hunter-Seeker credential in one unauthenticated HTTP call, run the free samples immediately, and hand a claim link to a person whenever one shows up. The same key keeps working after they claim it, and the autonomy ceiling never moves.

One unauthenticated call, then a real ranking. No signup, no email, no card.

# 1 - mint a key. No Authorization header.
#     Returns { api_key, agent_id, claim_url, mode: "test" }.
curl -sS -X POST https://hunter-seeker.io/api/v1/agents/register \
  -H 'content-type: application/json' \
  -d '{"agent_caller":"my-agent"}'

# 2 - rank a free sample with the key you just got.
curl -sS -X POST https://hunter-seeker.io/api/v1/rank_topk \
  -H "Authorization: Bearer $HS_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"data":{"dataset_id":"sample:saas_churn"},"entity_column":"customer_id","outcome_column":"churned","subject_kind":"org","page":{"k":5}}'

Expect usability: "actionable", top_decile_lift 4.444444, and a model_ref.

The key runs the FREE SAMPLE DATASETS ONLY - it consumes no quota, cannot read anyone's data, and is safe to print in a log. Hand claim_url to a human whenever you like: they sign in, and the SAME key keeps working against a workspace they own, with every model_ref it produced preserved. Claiming attaches a human to the TENANT, never to the CREDENTIAL - so a machine key still carries no human principal, and decisions about PEOPLE stay capped at max_autonomy: "L0" whether it is claimed or not. That ceiling is the point.

What the key can and cannot do

A hsk_test_ key resolves the free sample datasets only. The restriction is enforced before any upload URL is minted and before any byte of any dataset is read, so the key cannot be turned into a data-exfiltration tool or a billing tool no matter what is sent to it. That is the reason it is safe to issue anonymously, and the reason it is safe to paste into a public README.

Concretely, an unclaimed key can:

run sample:saas_churn, sample:b2b_leads, sample:telco_churn and sample:agent_traces
use every free interrogation tool against a ranking_ref it produced
score a single entity against a model_ref it produced, and receive a signed Verdict
verify any Verdict, which needs no credential at all

It cannot register a dataset of its own, cannot read another tenant's anything, and consumes no quota — sample runs sit before the reserve, so nothing is taken and nothing is refunded.

The ceiling, and why claiming does not move it

max_autonomy is how much rope a single decision earns, on an L0–L4 ladder. A person-level decision — subject_kind: "person" — reaches L2 only when a human principal is present, and is capped at L0 when there is not one.

A machine key has no principal. Not "an empty one": none. The Verdict schema has fields for a service principal, and this endpoint deliberately does not populate them, because derive_autonomy reads principal presence — so minting a plausible-looking one out of a key id would silently lift every people-affecting decision from L0 to L2 on the strength of a shared secret.

Claiming attaches a human to the tenant. It does not attach one to the credential. So:

	`subject_kind: "person"`	`on_behalf_of`
OAuth, signed-in human	`max_autonomy: "L2"`	the user
Machine key, unclaimed	`max_autonomy: "L0"`	`null`
Machine key, after claim	`max_autonomy: "L0"`	`null`

If you need L2 on a decision about a person, you need an OAuth session with a real human in it. That is not a limitation to work around; it is the thing that makes the decision attributable to someone an auditor can ask.

Claiming

claim_url is a signed link, valid for 30 days, and it is not a credential — holding it lets you do nothing until you sign in. When a human opens it and signs in:

the key string is byte-identical afterwards. No re-issue, no rotation, nothing to redeploy. The agent that has been running for a week is not told anything.
the tenant id is unchanged. It is one UPDATE setting the owner, not a migration, so every model_ref the key produced stays attached by construction.
the key stays a test key. Mode lives in the key string itself, not in a database column, so a claim physically cannot promote a key that may be sitting in a public repo.

If the person signing in already owns a workspace, the flow asks which one to use rather than merging into whichever they happen to be in. Two viable targets is a question, not a default.

Rate limits

Registration is limited per source address. If you get a 429, read Retry-After — and then reconsider: the key you already have does not expire. Registering repeatedly is almost always a sign that a key is being thrown away somewhere it should be stored.

When you should not use this

If a human is available and will be present for the decisions, use OAuth instead — an agent acting for a signed-in person gets a real principal and can reach L2 on person-level decisions. This endpoint exists for the case where nobody is there.