Documentation

Complete API reference for AgentUtil. All tools use the same async pattern.

Quick Start

Base URL

https://api.agentutil.dev

The Pattern

Every tool uses the same async pattern:

# 1. Create a task

POST /v1/tools/{tool}/tasks

{"email": "user@example.com"}

# Response: 202 Accepted

{"task_id": "task_abc123", "poll_url": "/v1/tasks/task_abc123"}

# 2. Poll for result

GET /v1/tasks/task_abc123

# Response when complete

{"status": "complete", "result": {"deliverable": true, ...}}

Payment

Default

x402 Micropayments

Just send a request. You'll get a 402 response with payment details. Pay with USDC on Base, then retry with the payment proof.

# 1. Request → 402

POST /v1/tools/email.verify/tasks

← 402 Payment Required

{"x402": {"price": "0.01", "network": "base", "token": "USDC"}}

# 2. Pay + retry

X-Payment-Proof: ...

← 202 Accepted

Alternative

Prepaid API Key

Prepay via Stripe at agentutil.dev/#pricing.

Authorization: Bearer sk_live_...

Tools Reference

Email Verification

email.verify

$0.01

per call

Deep email validation — MX records, SMTP handshake, disposable/free email detection. Returns deliverability score and autocorrect suggestions.

Endpoint

POST /v1/tools/email.verify/tasks

Request

{
  "email": "user@example.com"
}

Response

{
  "deliverable": true,
  "quality_score": 0.95,
  "is_disposable": false,
  "is_role_based": false,
  "is_free_email": false,
  "mx_found": true,
  "smtp_valid": true,
  "autocorrect": null
}

Input Schema

email: string

Output Schema

deliverable: boolean

quality_score: number

is_disposable: boolean

is_role_based: boolean

is_free_email: boolean

mx_found: boolean

smtp_valid: boolean

autocorrect: string|null

IP Intelligence

ip.geolocate

$0.005

per call

Get location, ISP, and security data for any IP. Detects VPNs, proxies, Tor, datacenter IPs. Returns threat score.

Endpoint

POST /v1/tools/ip.geolocate/tasks

Request

{
  "ip": "8.8.8.8"
}

Response

{
  "ip": "8.8.8.8",
  "city": "Mountain View",
  "region": "California",
  "country": "United States",
  "country_code": "US",
  "lat": 37.386,
  "lng": -122.0838,
  "isp": "Google LLC",
  "is_vpn": false,
  "is_proxy": false,
  "is_tor": false,
  "is_datacenter": true,
  "threat_score": 0
}

Input Schema

ip: string

Output Schema

ip: string

city: string|null

region: string|null

country: string|null

lat: number|null

lng: number|null

isp: string|null

is_vpn: boolean

is_proxy: boolean

is_tor: boolean

is_datacenter: boolean

threat_score: number|null

Geocoding

geo.locate

$0.005

per call

Convert addresses to lat/lng coordinates. Handles partial addresses, landmarks, natural language queries.

Endpoint

POST /v1/tools/geo.locate/tasks

Request

{
  "address": "1600 Pennsylvania Ave NW, Washington DC"
}

Response

{
  "lat": 38.8977,
  "lng": -77.0365,
  "confidence": 0.82,
  "formatted_address": "1600 Pennsylvania Avenue NW, Washington, DC 20500, USA",
  "components": {
    "street": "Pennsylvania Avenue NW",
    "city": "Washington",
    "state": "District of Columbia",
    "country": "United States",
    "postal_code": "20500"
  }
}

Input Schema

address: string

Output Schema

lat: number

lng: number

confidence: number

formatted_address: string

components: object

DNS Lookup

dns.lookup

$0.002

per call

Query DNS records for a domain — A, AAAA, MX, TXT, NS, CNAME. Returns all record types.

Endpoint

POST /v1/tools/dns.lookup/tasks

Request

{
  "domain": "stripe.com"
}

Response

{
  "domain": "stripe.com",
  "records": {
    "A": [
      "3.18.1.79",
      "3.18.168.150"
    ],
    "AAAA": [],
    "MX": [
      {
        "priority": 1,
        "exchange": "aspmx.l.google.com"
      },
      {
        "priority": 5,
        "exchange": "alt1.aspmx.l.google.com"
      }
    ],
    "TXT": [
      "v=spf1 include:_spf.google.com ~all"
    ],
    "NS": [
      "ns1.p16.dynect.net",
      "ns2.p16.dynect.net"
    ]
  },
  "queried_at": "2026-03-05T18:00:00Z"
}

Input Schema

domain: string

record_type: string?

Output Schema

domain: string

records: object

queried_at: string

URL Status Check

url.status

$0.002

per call

Check if a URL is reachable. Returns status code, redirects, response time, SSL validity.

Endpoint

POST /v1/tools/url.status/tasks

Request

{
  "url": "https://example.com"
}

Response

{
  "url": "https://example.com",
  "final_url": "https://example.com/",
  "status_code": 200,
  "status_text": "OK",
  "reachable": true,
  "response_time_ms": 142,
  "ssl": {
    "valid": true
  },
  "checked_at": "2026-03-05T18:00:00Z"
}

Input Schema

url: string

follow_redirects: boolean?

timeout_ms: number?

Output Schema

reachable: boolean

status_code: number

final_url: string

response_time_ms: number

ssl: object

Home Services Search

homeservices.search

$0.02

per call

Find local home service professionals with real ratings and contact info. Plumbers, electricians, HVAC, roofers, etc.

Endpoint

POST /v1/tools/homeservices.search/tasks

Request

{
  "service": "plumber",
  "zip": "90210"
}

Response

{
  "pros": [
    {
      "id": "pro_abc123",
      "name": "Ace Plumbing Co.",
      "phone": "+1-310-555-1234",
      "rating": 4.8,
      "review_count": 127,
      "address": "123 Main St, Beverly Hills, CA",
      "website": "https://aceplumbing.com",
      "description": "Licensed plumber serving Beverly Hills since 1985"
    },
    {
      "id": "pro_def456",
      "name": "Quick Fix Plumbing",
      "phone": "+1-310-555-5678",
      "rating": 4.6,
      "review_count": 89,
      "address": "456 Oak Ave, Los Angeles, CA"
    }
  ]
}

Input Schema

service: string

zip: string

Output Schema

pros: array

Home Services Request

homeservices.request

$0.05

per call

Submit a job request on behalf of a homeowner. We notify matched local pros directly.

Endpoint

POST /v1/tools/homeservices.request/tasks

Request

{
  "service": "plumber",
  "zip": "90210",
  "name": "John Smith",
  "phone": "+1-555-123-4567",
  "email": "john@example.com",
  "notes": "Leaky faucet in kitchen, dripping for 2 days"
}

Response

{
  "request_id": "req_abc123",
  "status": "received",
  "message": "Request received. Matched pros will be notified."
}

Input Schema

service: string

zip: string

name: string

phone: string

email: string?

notes: string

Output Schema

request_id: string

status: string

message: string

Task Lifecycle

pending

→

running

→

complete

failed

{
  "task_id": "task_abc123",
  "status": "complete",
  "tool": "email.verify",
  "result": { ... },
  "error": "..."
}

Error Handling

Status	Meaning	Action
400	Invalid input	Fix request per error message
402	Payment required	Pay via x402 or use API key
404	Not found	Check tool name or task ID
500	Server error	Retry or contact support

Discovery

/.well-known/agent-service.jsonService metadata

/.well-known/agent.jsonA2A Agent Card

/openapi.jsonOpenAPI 3.1 spec

/v1/toolsList all tools

/v1/tools/{tool}Tool details

Questions? Email silas@agentutil.dev