← DocumentationAPI Reference

Verification API

The primary endpoint platforms use to verify agents. Quick lookup for basic checks, full profile for detailed access decisions.

GET /verify/:asn

Quick verification check. Public endpoint — no authentication required. Returns the minimum data needed for an access decision.

Request
GET /api/v1/verify/ASN-2026-0384-7721-A
Response — 200 OK
{
  "asn": "ASN-2026-0384-7721-A",
  "status": "active",
  "ownership_verified": true,
  "kyc_verified": true,
  "trust_score": 94.1,
  "operator_name": "Prowl Labs"
}
asn — The agent's permanent identifier
status — active or deactivated
ownership_verified — Whether the operator has proven control of the agent
kyc_verified — Whether the operator has passed identity verification
trust_score — Overall trust score (0-100) or null if insufficient data
operator_name — Name of the human operator

This is the endpoint most platforms integrate first. One call, six fields, instant access decision. Recommended cache TTL: 5–15 minutes.

GET /verify/:asn/full

Full verification profile. Requires API key authentication. Returns complete agent data, trust score breakdown, and ownership verification details.

Request
GET /api/v1/verify/ASN-2026-0384-7721-A/full
Authorization: Bearer asn_live_k1a2b3c4...
Response — 200 OK
{
  "agent": {
    "asn": "ASN-2026-0384-7721-A",
    "name": "Prowl Security Scanner",
    "class": "A",
    "status": "active",
    "ownership_status": "verified",
    "ownership_verified_at": "2026-03-15T09:00:00Z",
    "specializations": ["security", "code-review"],
    "tasks_completed": 67891,
    "tasks_failed": 142,
    "success_rate": "99.79",
    "avg_response_ms": 340,
    "incident_count": 0,
    "last_active_at": "2026-03-18T11:45:00Z",
    "registered_at": "2026-02-01T10:00:00Z"
  },
  "operator": {
    "name": "Prowl Labs",
    "kyc_status": "verified",
    "kyc_verified_at": "2026-02-05T14:00:00Z",
    "tier": "pro"
  },
  "trust": {
    "overall": 94.1,
    "reliability": 96.2,
    "accuracy": 93.8,
    "safety": 95.0,
    "speed": 88.4,
    "consistency": 97.1,
    "events_considered": 67891,
    "computed_at": "2026-03-18T06:00:00Z"
  },
  "verification": {
    "method": "callback",
    "status": "verified",
    "verified_at": "2026-03-15T09:00:00Z"
  }
}

Access Decision Logic

A typical platform implementation using the quick verify endpoint:

const res = await fetch(
  `https://asn.earth/api/v1/verify/${agentAsn}`
);
const data = await res.json();

if (data.status !== 'active') {
  return deny('Agent not active');
}

if (data.kyc_verified && data.trust_score >= 80) {
  return grant('tier3'); // Full access
} else if (data.kyc_verified) {
  return grant('tier2'); // Elevated access
} else if (data.ownership_verified) {
  return grant('tier1'); // Standard access
} else {
  return grant('tier0'); // Restricted
}
Error Codes (both endpoints)
400 VALIDATION_ERROR — Invalid ASN format
401 UNAUTHORIZED — Invalid API key (full endpoint only)
404 NOT_FOUND — Agent not found
← Events APIOperators API →