V2 API Architecture

The URLert V2 API is designed around two core interaction patterns. Understanding when an endpoint is Synchronous (instant) versus Hybrid (async-capable) is key to building robust integrations.

POST

The Hybrid Pattern (Async-Capable)

Most operations—such as threat analysis and domain classification—require significant processing time, which is why the API is asynchronous by default. For resource types that support it (such as Domain Classification), the API checks for existing results first to optimize for performance and cost; if a fresh result is found in our cache, it is returned immediately at a reduced price.

Outcome: Cache Hit

200 OK

If a fresh result exists, it is returned immediately in the response body.

Outcome: Cache Miss

202 Accepted

If no result exists, a background job is spawned and a job ID is returned.

GET

The Synchronous Pattern (Lookup)

Retrieval operations are strictly synchronous. These endpoints only interact with existing data and are guaranteed never to trigger new background processing.

Outcome: Found

200 OK

The requested data is returned immediately.

Outcome: Not Found

404 Not Found

If the data does not exist, 404 is returned. This does not incur any charges.

Billing & Refunds

The V2 API standardizes patterns for how charges and refunds are handled for async tasks.

The X-Charge-Amount Header

To ensure transparent usage tracking, every V2 API response includes the X-Charge-Amount header. This value represents the precise amount deducted from your organization's balance for that specific request.

For detailed pricing tiers and category-specific costs, please refer to the main Pricing Page.

Async Refunds Policy

Async jobs are charged upon submission. If a job eventually fails on our end due to system errors, a refund is automatically credited back to your balance immediately.

The V2 Process Flow

Follow this 3-step sequence for any V2 resource request.

1. Checking Cache (Optional)

GET

For long-lived resources like Domain Classifications, you can use GET to check if a result already exists. This is the fastest, most cost-effective way to retrieve data when immediate real-time analysis isn't required.

Conditional Step

This step only applies to specific resource types that support persisted lookups. For real-time scanners, you should proceed directly to Step 2.

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

2. Request Creation

POST

If Step 1 is not applicable or returns a 404, submit a POST request to initiate processing. The API will either return immediate results (internal cache hit) or spawn a background job.

Response Tracking

If the resource is not in cache, the API returns a 202 Accepted status with a job ID and status URL.

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

{
  "message": "Classification in progress",
  "status_url": "https://api.urlert.com/v2/domain-classification/jobs/bb0e8400-e29b-41d4-a716-446655440006",
  "timeout_seconds": 30.0
}

3. Polling Results

GET

Using the status_url from Step 2, poll at a reasonable interval (e.g. 2-5s). Depending on the job progress, you will receive one of the following standard responses.

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

Standard Job Responses

The polling endpoint returns a consistent JSON structure across all V2 resources. Depending on the job progress, you will receive one of the following responses.

Processing

Waiting State

The job is currently in the queue or actively running across our workers. The result field remains null during this phase.

Check every 2-5 seconds

{
  "status": "processing",
  "job_id": "bb0e8400-e29b-41d4-a716-446655440006",
  "error": null,
  "result": null
}

Complete

Success State

The job finished successfully. The result object is now populated with the full data payload specific to the resource.

Result is available in the 'result' field

{
  "status": "complete",
  "job_id": "bb0e8400-e29b-41d4-a716-446655440006",
  "error": null,
  "result": {
    "domain": "example-startup.com",
    "category": "Technology/SaaS",
    "confidence": 0.98,
    "generated_at": "2023-10-27T10:00:05Z"
  }
}

Failed

Error State

The task encountered a system error or timeout. The error field contains the failure message. No charge applied.

Automatic refund triggered

{
  "status": "failed",
  "job_id": "bb0e8400-e29b-41d4-a716-446655440006",
  "error": "Job exceeded maximum processing time",
  "result": null
}