ASN — Agent Security Number

Base URL

https://asn.earth/api/v1

All endpoints are versioned under /api/v1. The API uses JSON for request and response bodies, and returns standard HTTP status codes.

Authentication

Pass your API key or session token in the Authorization header:

Authorization: Bearer asn_live_k1a2b3c4d5e6f7...

Public endpoints (verification, agent profiles) do not require authentication. See Authentication for which endpoints are public.

Rate Limits

Public endpoints

Rate limited by IP. Varies by endpoint.

Authenticated endpoints

Default: 60 requests/minute per API key. Configurable per key.

Strict endpoints

Sensitive operations (key creation, KYC). Lower limits apply.

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1710763260

When rate limited, you receive a 429 with a Retry-After header in seconds.

Error Format

All errors return a consistent JSON envelope:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid ASN format",
    "status": 400
  }
}

Common Error Codes

400 VALIDATION_ERROR — Invalid input or parameters

401 UNAUTHORIZED — Missing or invalid authentication

402 AGENT_LIMIT_REACHED — Tier agent limit exceeded

403 FORBIDDEN — Insufficient permissions

404 NOT_FOUND — Resource not found

410 AGENT_DEACTIVATED — Agent is deactivated

429 RATE_LIMITED — Too many requests

500 INTERNAL_ERROR — Server error

curl Examples

Verify an agent (public):

curl https://asn.earth/api/v1/verify/ASN-2026-0384-7721-A

curl -X POST https://asn.earth/api/v1/agents \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "class": "A",
    "description": "Autonomous task runner"
  }'

Report activity:

curl -X POST https://asn.earth/api/v1/activity/report \
  -H "Authorization: Bearer asn_live_k1a2b3c4..." \
  -H "Content-Type: application/json" \
  -d '{
    "asn": "ASN-2026-0384-0001-7",
    "event_type": "task_completed",
    "metadata": { "task_id": "task-1" }
  }'

Get trust score:

curl https://asn.earth/api/v1/agents/ASN-2026-0384-7721-A/trust-score

Full verification (authenticated):

curl https://asn.earth/api/v1/verify/ASN-2026-0384-7721-A/full \
  -H "Authorization: Bearer asn_live_k1a2b3c4..."

Content Type

All request bodies must be JSON with Content-Type: application/json. All responses are JSON.

Pagination

List endpoints support cursor-based pagination:

page — Page number (1-indexed, default: 1)

per_page — Items per page (default: 20, max: 50)

Paginated responses include a pagination object with page, per_page, total, and total_pages.

← JavaScript SDK Integrations →