/docs — api reference

auth

every /v1/* call needs a key: X-API-Key: hk_live_... (or Authorization: Bearer). limit: 60 req/min/key. interactive docs at api.hinklo.com/docs.

POST /v1/check

body: { domain | url, context? }. unknown domains return confirm_with_user + INSUFFICIENT_DATA and are queued for assessment.

curl -X POST https://api.hinklo.com/v1/check \
    -H "X-API-Key: hk_live_..." \
    -d '{"domain": "example-store.com"}'

{
  "check_id":   "uuid — reference for outcomes/disputes",
  "merchant":   "example-store.com",
  "decision":   "proceed | confirm_with_user | block",
  "score":      "int 0-100 or null",
  "risk_band":  "low | medium | high",
  "confidence": "float 0-1",
  "reasons":    [{ "code": "...", "text": "..." }, ...],
  "model_version": "rules-v0",
  "last_checked":  "iso timestamp or null",
  "cache_hit":     "bool"
}

decisions

proceed	score ≥ 80 and confidence ≥ 0.80
block	hard flag present and confidence ≥ 0.60
confirm_with_user	everything else, incl. unknown domains

hard-flag reason codes

BLOCKLIST_HIT	domain on a known-abuse blocklist — score capped at 5
LOOKALIKE_OF_*	brand impersonation — score capped at 15
NEW_DOMAIN_NO_CONTACT	< 30 days old and no contact — capped at 20
INJECTION_ATTEMPT	page text tries to instruct the agent — capped at 25

signal reason codes

NEW_DOMAIN_D / YOUNG_DOMAIN_D	recently registered
ESTABLISHED_DOMAIN	> 2 years old
NO_CONTACT / HAS_CONTACT	reachable contact channel
NO_RETURN_POLICY / HAS_RETURN_POLICY	return or refund policy
BANK_TRANSFER_ONLY	only irreversible payment methods
WHOIS_PRIVATE	registration details hidden
REGISTRY_MATCH	legal entity found in an official registry
VALID_TLS	valid TLS certificate
COUNTDOWN_TIMER	fake scarcity countdown
URGENCY_CLAIMS	urgency/scarcity claims on page
PRECHECKED_ADDON	pre-checked add-ons at checkout
FORCED_ACCOUNT	account required to purchase
INSUFFICIENT_DATA	not yet assessed — crawl queued

other endpoints

POST /v1/outcomes	report delivery/refund/chargeback per check_id
GET /v1/merchants/{domain}	latest assessment for a domain
POST /v1/disputes	merchant disputes an assessment

errors

401	invalid or missing API key
429	rate limit exceeded
422	missing domain/url, or invalid field

mcp: a check_merchant tool wraps /v1/check for agent frameworks — see repo.