API Documentation

Score domains for trust and reliability programmatically.

Authentication

All API requests require a Bearer token. Get your API key from the dashboard under API Keys.

Authorization: Bearer lrn_live_abc123...

Base URL

https://lirnoa.com/api/v1

Score a Domain

GET /score?domain={domain}

Query Parameters

Parameter	Type	Description
`domain` required	string	Domain to score (e.g. `example.com`)
`force`	boolean	Set to `true` to bypass cache and re-score
`timeout`	integer	Timeout in ms (1000-55000). Returns `202` if scoring exceeds this limit — retry shortly for the cached result.
`referrer`	string	Attribution tag (e.g. `clay`). Max 50 chars.

Response Headers

Header	Description
`X-Lirnoa-Cache`	`HIT` or `MISS`
`X-Lirnoa-Latency`	Processing time in ms
`X-RateLimit-Limit`	Hourly rate limit
`X-RateLimit-Remaining`	Requests remaining

Example Response

{
  "domain": "example.com",
  "score": 82,
  "risk_level": "low",
  "recommendation": "Engage normally",
  "confidence": 0.85,
  "cached": false,
  "dns": {
    "domain_age_days": 10950,
    "has_mx": true,
    "has_spf": true,
    "has_dkim": true,
    "has_dmarc": true,
    "ssl_valid": true,
    "is_blacklisted": false
  },
  "web_presence": {
    "has_website": true,
    "has_contact_info": true,
    "has_social_links": true,
    "og_tags_present": true
  },
  "business_verification": {
    "google_business_found": true,
    "companies_house_found": false,
    "kvk_registry_found": false,
    "linkedin_found": true
  },
  "company": {
    "name": "Example Inc.",
    "industry": "Technology",
    "country": "US",
    "city": "San Francisco",
    "employee_range": "51-200",
    "domain_age_years": 30.0,
    "google_rating": 4.5,
    "google_review_count": 120
  },
  "risk_dimensions": { ... },
  "analyst_assessment": {
    "summary": "Example Inc. is an established technology company.",
    "company_summary": "Example Inc. is an established technology company. They operate globally...",
    "risk_level": "Low",
    "recommendation": "Engage normally",
    "quick_signals": ["✅ Domain age: 30 years", "✅ LinkedIn found"]
  },
  "scored_at": "2026-03-18T12:00:00.000Z",
  "latency_ms": 8500
}

202 Accepted (Timeout)

When using the timeout parameter and scoring takes longer than the specified limit:

{
  "status": "scoring",
  "domain": "newdomain.com",
  "message": "Domain is being scored. Retry shortly.",
  "retry_after_seconds": 30
}

Code Examples

cURL

curl -H "Authorization: Bearer lrn_live_YOUR_KEY" \
  "https://lirnoa.com/api/v1/score?domain=example.com"

JavaScript (Node.js)

const res = await fetch(
  'https://lirnoa.com/api/v1/score?domain=example.com',
  { headers: { Authorization: 'Bearer lrn_live_YOUR_KEY' } }
);
const data = await res.json();
console.log(data.score, data.risk_level);

Python

import requests

res = requests.get(
    'https://lirnoa.com/api/v1/score',
    params={'domain': 'example.com'},
    headers={'Authorization': 'Bearer lrn_live_YOUR_KEY'}
)
data = res.json()
print(data['score'], data['risk_level'])

Rate Limits

Plan	Per Second	Per Hour	Monthly Quota
Starter (€29/mo)	5	300	1,000
Pro (€79/mo)	15	1,000	5,000

Rate-limited requests return 429 Too Many Requests with a Retry-After header. Quota-exceeded requests return 402 Payment Required.

Errors

{
  "error": {
    "code": "INVALID_DOMAIN",
    "message": "The provided domain is not valid."
  }
}

Code	HTTP	Meaning
`MISSING_DOMAIN`	400	No domain parameter provided
`INVALID_DOMAIN`	400	Domain could not be parsed
`UNAUTHORIZED`	401	Missing or invalid API key
`RATE_LIMITED`	429	Rate limit exceeded
`QUOTA_EXCEEDED`	402	Monthly quota exceeded
`INTERNAL_ERROR`	500	Server error