API Reference Documentation
Welcome to the complete developer documentation. Integrate vision-powered dynamic scraping and automated phishing forensics into your apps in minutes.
Authentication
All API requests to production endpoints require authentication using a custom header. Create your keys in the developer dashboard.
| Header | Type | Description |
|---|---|---|
| X-API-Key | string | Your active production API Key. Starts with the prefix op_live_. |
# Authenticating with cURL curl -H "X-API-Key: op_live_your_actual_key_here" \\ https://opticparse-api.onrender.com/health
Error Codes
Our APIs return standardized HTTP status codes for errors, with JSON detail bodies explaining the root cause.
| Code | Status | Description / Cause |
|---|---|---|
| 400 | Bad Request | Invalid parameters, payload too large, or malformed queries. |
| 401 | Unauthorized | Invalid or missing API key. Key format must check out. |
| 429 | Rate Limit Exceeded | Monthly request usage quota exceeded, or too many concurrent requests. |
| 500 | Internal Server Error | AI reasoning error, Playwright navigation failure, or server-side issue. |
POST /api/vision-scrape
Analyze a web page visually using headful browser rendering and return structured data according to your query and JSON schema.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| target_url | string | required | The full HTTP/HTTPS URL of the target webpage to scrape. Resolves only public URLs. |
| extraction_query | string | required | Instructions in plain English describing what data fields you want to extract. |
| response_schema | object | optional | A raw JSON schema dict defining exactly how the returned JSON object must be shaped. |
| wait_until | string | optional | Browser wait condition. Allowed: load (default), domcontentloaded, networkidle. |
| timeout | integer | optional | Browser navigation timeout in ms. Default 30,000 (30 seconds). Max 60,000. |
# Example Request curl -X POST \\ https://opticparse-api.onrender.com/api/vision-scrape \\ -H "X-API-Key: YOUR_API_KEY" \\ -H "Content-Type: application/json" \\ -d '{ "target_url": "https://news.ycombinator.com", "extraction_query": "Extract the top story title and point score" }'
POST /api/crawl
Crawl multiple pages of a website by following a CSS selector (e.g. "Next" pagination buttons) and extract structured data incrementally.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| start_url | string | required | The starting URL of the crawl. |
| extraction_query | string | required | The prompt detailing what structured data to collect from each page. |
| follow_selector | string | required | CSS selector for the pagination button to click to advance to the next page. |
| max_pages | integer | optional | Maximum number of pages to crawl. Default 5. Max 20. |
POST /api/watch
Establish a periodic monitoring task for a webpage. Compares visual states over time and fires a webhook when structural differences are detected.
POST /api/batch
Scrape up to 20 target URLs concurrently. Distributes tasks across browser runners to bypass standard sequential latencies.
POST /api/phish-detect
Visit a target URL, render the visual state, analyze it via our multimodal brand impersonation rules, and output threat forensics.
Parameters
| Field | Type | Description |
|---|---|---|
url | string | The target webpage to analyze. Must start with http:// or https://. |
dry_run | boolean (optional) | If true, bypasses AI analysis and instantly returns the raw base64 screenshot and text payload. Useful for tuning thresholds without consuming AI tokens. Default is false. |
# Example Request curl -X POST \\ https://opticparse-1opticparse-node-sg.onrender.com/api/phish-detect \\ -H "X-API-Key: YOUR_API_KEY" \\ -H "Content-Type: application/json" \\ -d '{ "url": "https://example.com", "dry_run": false }'
# Example Response { "verdict": "malicious", "confidence_score_percentage": 98, "impersonated_brand": "Microsoft", "threat_type": "brand_impersonation", "visual_anomalies_detected": ["Mismatched logo aspect ratio"], "hidden_payload_detected": null, "javascript_threats": [], "redirect_risk": "High (3 hops through bit.ly)", "domain_age_days": 2, "registrar": "Namecheap", "cached": false }
POST /api/phish-batch
Scan a list of URLs concurrently for visual threat analysis.
GET /api/phish-report
Download a detailed, brand-impersonation investigation PDF report for a previously scanned URL.
POST /api/monitor
Create a scheduled checker that periodically visits a target URL to check for malicious payloads, domain redirection anomalies, or visual phishing signs.