V2 API

Domain Classification

Categorize and identify domains using our real-time classification engine.

Domain Classification is used to resolve the fundamental identity and purpose of a domain. Unlike threat scanners, this API looks at the origin entity, operating company, and functional category of the root domain.

Billing & Transparency

Pricing is dynamically determined based on the resource state.

$0.001 Cache Hit Returns 200 OK if domain was previously classified.
$0.01 Cache Miss Triggers a fresh crawl. Returns 202 Accepted.
$0.000 Not Found Standard 404 if domain was never classified.
Async jobs are automatically refunded if they fail on our end.

1. Checking Cache (Optional)

GET

Always attempt to retrieve the domain from cache first to save time and credits.

curl -X GET "https://api.urlert.com/v2/domain-classification/github.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

2. Request Creation

POST

If the resource is not in cache (404), trigger a new classification job.

curl -X POST "https://api.urlert.com/v2/domain-classification" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "github.com"}'

3. Polling Results

GET

Poll the status_url provided in Step 2 until the job is complete.

curl -X GET "https://api.urlert.com/v2/domain-classification/jobs/bb0e8400-e29b-41d4-a716-446655440006" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

Typical response payload for a developed domain.

{
  "status": "complete",
  "job_id": "bb0e8400-e29b-41d4-a716-446655440006",
  "error": null,
  "result": {
    "domain": "github.com",
    "state": "developed",
    "scraping_status": "httpx_success",
    "stability": "permanent",
    "enrichment_status": "complete",
    "confidence": "high",
    "facts": {
      "created_at": "2007-10-09",
      "rank": 42,
      "hosting_provider": "Microsoft Corporation",
      "redirect_destination": null
    },
    "identity": {
      "headline": "World's leading software development platform",
      "summary": "GitHub is a developer platform that allows developers to create, store, manage and share their code. It uses Git software, providing the distributed version control of Git plus access control, bug tracking, software feature requests, task management, continuous integration, and wikis for every project.",
      "operator": "GitHub, Inc.",
      "parent_entity": "Microsoft Corporation",
      "topics": ["software development", "version control", "git", "devops", "collaboration"]
    },
    "category": {
      "purpose": "developer_platform",
      "specialization": "Source Code Management"
    },
    "classified_at": "2024-01-20T10:30:00Z",
    "updated_at": "2024-01-20T10:30:00Z"
  }
}

Job Status Schema

The job status object returned when polling or following a 202 Accepted response.

Top-Level Fields

Property Description

Classification Result Schema

The full domain classification object, returned directly on cache hits (200 OK) or as the 'result' field in a completed job.

Top-Level Fields

Property Description

Rate Limits

All endpoints are rate limited per organization, per minute.

Operation Limit Description
GET /v2/domain-classification/{domain} 60/minute Check cache or retrieve results
POST /v2/domain-classification 10/minute Trigger new classification
GET /v2/domain-classification/jobs/{id} 60/minute Poll active jobs