API Reference

Base URL

All API requests are made to the following base URL:

All endpoints are prefixed with /api/v1/ and accept JSON only. HTTPS is required for all requests.

Authentication

The platform uses a dual authentication model:

API Key (required for all public endpoints)

Pass your API key in the X-API-Key header. This identifies your account and enforces rate limits and billing.

curl -X POST /api/v1/check \
  -H "X-API-Key: apk_live_7f3a9b2c..." \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

JWT Bearer Token (for portal and admin endpoints)

Admin endpoints require a JWT token obtained from /api/authenticate. Tokens have a 5–15 minute TTL and are validated locally by each service.

curl -X GET /api/v1/admin/stats \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "X-API-Key: apk_live_7f3a9b2c..."

Standard Headers

Response Headers

Response Format

All responses are JSON. Successful responses return the resource directly (no wrapper envelope). Error responses use the RFC 7807 Problem Detail format.

Success Response

{
  "field1": "value",
  "field2": 42,
  "checkedAt": "2026-03-25T12:00:00Z"
}

Error Response (RFC 7807)

{
  "type": "/problems/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The 'email' field is required and must be a valid email address.",
  "instance": "/api/v1/check"
}

Batch Response

Batch endpoints return an array of results. Each item includes the input and the corresponding result, even if individual items fail.

{
  "results": [
    { "email": "a@safe.com", "disposable": false, "score": 0.02 },
    { "email": "b@tempmail.org", "disposable": true, "score": 0.95 }
  ],
  "checkedAt": "2026-03-25T12:00:00Z"
}

Error Codes

Rate Limits

Rate limits are enforced per API key via Redis sliding-window counters. Limits apply uniformly across all services.

Disposable Email Detector

Detect whether an email address belongs to a disposable/temporary email provider. Uses a multi-layer detection pipeline: static blocklist, regex patterns, MX record inspection, and domain-age heuristics.

Endpoints

Check a single email address.

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

{
  "email": "user@example.com",
  "domain": "example.com",
  "disposable": false,
  "score": 0.05,
  "reasons": [],
  "checkedAt": "2026-03-25T12:00:00Z"
}

Check multiple emails in one request (max 100 per batch).

{ "emails": ["a@safe.com", "b@tempmail.org"] }

Look up a specific domain for disposable status.

Phone Validation

Validate, format, and classify phone numbers. Returns carrier type (mobile, landline, VoIP), country code, and E.164 formatted number.

Validate and classify a single phone number.

{ "phoneNumber": "+1-555-123-4567", "defaultCountry": "US" }

{
  "valid": true,
  "e164": "+15551234567",
  "countryCode": "US",
  "type": "MOBILE",
  "carrier": "Verizon Wireless"
}

Batch validate multiple phone numbers.

IP Reputation

Score IP addresses for abuse risk. Detects proxies, VPNs, Tor exit nodes, and known malicious IPs using threat intelligence feeds.

Check the reputation of a single IP address.

{ "ip": "203.0.113.42" }

{
  "ip": "203.0.113.42",
  "riskScore": 0.72,
  "isProxy": true,
  "isVpn": false,
  "isTor": false,
  "threats": ["open_proxy", "spam_source"],
  "lastSeen": "2026-03-24T08:15:00Z"
}

Batch check multiple IP addresses.

Captcha (HVS)

Human Verification System — generate CAPTCHA challenges and validate user responses. Includes fraud scoring integration with the IP Geolocation module.

Generate a new CAPTCHA challenge.

{
  "challengeId": "chg_8a7b6c5d4e3f",
  "imageUrl": "/api/v1/captcha/image/chg_8a7b6c5d4e3f",
  "expiresAt": "2026-03-25T12:05:00Z"
}

Validate a user's CAPTCHA response.

{ "challengeId": "chg_8a7b6c5d4e3f", "answer": "xK9mP" }

Password Breach

Check whether a password has appeared in known data breaches. Uses k-anonymity — the full password is never transmitted over the network.

Check a single password against breach databases.

{ "password": "MyP@ssword123" }

{
  "breached": true,
  "occurrences": 4521,
  "message": "This password has appeared in known data breaches."
}

Batch check multiple passwords.

k-anonymity range query. Returns all hash suffixes matching the 5-character SHA-1 prefix.

Uptime Monitor

Schedule HTTP, TCP, and ICMP health checks against your endpoints. Track uptime percentages, response times, and manage incidents with alerting.

Create a new monitoring target.

{
  "name": "Production API",
  "url": "https://api.myapp.com/health",
  "type": "HTTP",
  "intervalSeconds": 60,
  "expectedStatusCode": 200
}

List all monitoring targets (paginated).

Get current status and uptime percentage for a target.

Get check history with response times and status codes.

Trigger an ad-hoc health check immediately.

DNS Checker

Resolve DNS records for any domain. Supports A, AAAA, MX, TXT, CNAME, NS, SOA, and SRV record types. Results are cached via Caffeine for sub-50ms responses.

Look up DNS records for a domain.

{
  "domain": "example.com",
  "recordTypes": ["A", "MX", "TXT"]
}

Batch DNS lookup for multiple domains.

Quick lookup for a single domain (all record types).

IP Geolocation

Map IP addresses to geographic location, ISP, ASN, and organization data. Supports both IPv4 and IPv6.

Look up geolocation data for an IP address.

{
  "ip": "8.8.8.8",
  "country": "US",
  "region": "California",
  "city": "Mountain View",
  "latitude": 37.386,
  "longitude": -122.084,
  "isp": "Google LLC",
  "asn": 15169
}

Batch geolocation lookup for multiple IPs.

Cron Service

Schedule HTTP callbacks using cron expressions. Define jobs that dispatch HTTP requests to your endpoints on a schedule, with full execution history and retry logic.

Create a new scheduled job.

{
  "name": "Nightly cleanup",
  "cronExpression": "0 0 3 * * ?",
  "targetUrl": "https://myapp.com/api/cleanup",
  "httpMethod": "POST",
  "headers": { "Authorization": "Bearer ..." }
}

List all scheduled jobs (paginated).

Get execution history for a job.

Delete a scheduled job.

SSL Checker

Inspect TLS/SSL certificates for any hostname. Reports certificate expiry, chain validity, hostname matching, protocol support, and an overall security grade.

Check the SSL certificate of a hostname.

{ "hostname": "github.com", "port": 443 }

{
  "hostname": "github.com",
  "grade": "A+",
  "issuer": "DigiCert",
  "validFrom": "2025-03-01T00:00:00Z",
  "validUntil": "2027-03-01T23:59:59Z",
  "daysRemaining": 706,
  "chainValid": true,
  "hostnameMatch": true,
  "protocols": ["TLSv1.2", "TLSv1.3"]
}

Batch check multiple hostnames.

URL Metadata

Fetch and extract Open Graph, Twitter Card, and standard HTML meta tags from any URL. Useful for link previews and SEO analysis.

Extract metadata from a URL.

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

{
  "url": "https://github.com",
  "title": "GitHub: Let's build from here",
  "description": "GitHub is where over 100 million developers...",
  "ogImage": "https://github.githubassets.com/images/og-image.png",
  "ogType": "website",
  "twitterCard": "summary_large_image",
  "favicon": "https://github.com/favicon.ico",
  "language": "en"
}

Batch extract metadata from multiple URLs.

Screenshot

Capture full-page or viewport-sized screenshots of web pages using a headless Chromium browser (Playwright). Returns PNG/JPEG images or PDF documents.

Capture a screenshot of a web page.

{
  "url": "https://example.com",
  "format": "png",
  "width": 1280,
  "height": 720,
  "fullPage": false
}

Retrieve a previously captured screenshot.

Readability

Analyze text readability using multiple scoring algorithms: Flesch-Kincaid Grade Level, Flesch Reading Ease, Gunning Fog Index, Coleman-Liau Index, SMOG Grade, and Automated Readability Index.

Analyze a text passage.

{ "text": "The quick brown fox jumps over the lazy dog...", "language": "en" }

{
  "fleschKincaidGrade": 5.2,
  "fleschReadingEase": 78.5,
  "gunningFog": 7.1,
  "colemanLiau": 6.8,
  "smogGrade": 6.5,
  "ari": 5.0,
  "wordCount": 142,
  "sentenceCount": 8,
  "avgWordsPerSentence": 17.75
}

Keyword Extractor

Extract keywords and key phrases from text using a deterministic NLP pipeline. Returns ranked keywords with relevance scores.

Extract keywords from text.

{
  "text": "Machine learning algorithms are transforming how we process...",
  "maxKeywords": 10,
  "language": "en"
}

{
  "keywords": [
    { "term": "machine learning", "score": 0.92 },
    { "term": "algorithms", "score": 0.85 },
    { "term": "data processing", "score": 0.71 }
  ],
  "language": "en"
}

Log Redaction

Detect and redact PII, secrets, and sensitive data from log text. Supports credit card numbers, SSNs, emails, API keys, JWTs, and custom patterns.

Redact sensitive data from text.

{
  "text": "User john@acme.com paid with card 4111-1111-1111-1111",
  "rules": ["EMAIL", "CREDIT_CARD"]
}

{
  "redacted": "User [EMAIL_REDACTED] paid with card [CC_REDACTED]",
  "detections": [
    { "type": "EMAIL", "offset": 5, "length": 13 },
    { "type": "CREDIT_CARD", "offset": 35, "length": 19 }
  ]
}

Batch redact multiple text entries.

Deduplication

Detect and remove duplicate records from datasets. Supports exact matching, fuzzy matching, and configurable field-level strategies.

Detect duplicate records in a dataset.

{
  "records": [
    { "name": "John Smith", "email": "john@acme.com" },
    { "name": "Jon Smith", "email": "john@acme.com" }
  ],
  "strategy": "FUZZY",
  "matchFields": ["name", "email"]
}

{
  "duplicateGroups": [
    { "similarity": 0.94, "indices": [0, 1] }
  ],
  "totalRecords": 2,
  "duplicatesFound": 1
}

JSON Validator

Validate JSON documents against JSON Schema (Draft 4, 6, 7, 2019-09, and 2020-12). Also performs syntax checking, linting, and custom rule evaluation.

Validate a JSON document against a schema.

{
  "document": { "name": "test", "age": "not-a-number" },
  "schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "age": { "type": "integer" }
    }
  }
}

{
  "valid": false,
  "issues": [
    {
      "path": "$.age",
      "message": "Expected type integer but got string",
      "severity": "ERROR"
    }
  ]
}

Check JSON syntax validity only (no schema required).

File Type

Detect file type from magic bytes, extension analysis, and content inspection. Identifies MIME type, category, and whether the file is safe to process.

Upload a file for type detection (multipart form data).

{
  "filename": "report.pdf",
  "mimeType": "application/pdf",
  "category": "DOCUMENT",
  "extension": "pdf",
  "magicBytesMatch": true,
  "safe": true
}

Classify a file by URL reference (no upload required).

Batch classify multiple files.

Webhook Inspector

Capture, inspect, and replay inbound webhooks. Validates signatures (HMAC-SHA256, etc.) for popular providers like Stripe, GitHub, and Twilio.

Create a new webhook capture endpoint.

{
  "id": "wh_9x8y7z6w",
  "captureUrl": "/api/v1/webhooks/capture/wh_9x8y7z6w",
  "provider": "stripe"
}

List captured webhook deliveries.

Replay a captured webhook delivery.

Rate Test

Run controlled HTTP load tests against your own endpoints. Configurable concurrency, duration, and request patterns with real-time metrics collection.

Create a load test scenario.

{
  "name": "API stress test",
  "targetUrl": "https://myapp.com/api/health",
  "method": "GET",
  "concurrency": 10,
  "durationSeconds": 60,
  "requestsPerSecond": 100
}

Execute a load test scenario.

Get execution results with latency percentiles, throughput, and error rates.

{
  "status": "COMPLETED",
  "totalRequests": 6000,
  "successCount": 5982,
  "errorCount": 18,
  "latencyP50ms": 12,
  "latencyP95ms": 45,
  "latencyP99ms": 128,
  "throughputRps": 99.7
}

MCP / AI Integration

Orovai exposes a Model Context Protocol (MCP) tools manifest that describes every API endpoint in a machine-readable format. AI agents, LLM tool-use frameworks, and automation platforms can consume this manifest to discover and invoke Orovai services automatically.

Point your MCP-compatible client at https://api.orovai.com/api/mcp-tools.json to load all available tools. The manifest follows the MCP specification and includes parameter schemas, descriptions, and authentication requirements for each service.

See also: raw manifest file.