API Reference Documentation

Authentication

All API requests to production endpoints require authentication using a custom header. Create your keys in the developer dashboard.

# 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.

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

# 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

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

# 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.

POST /api/stealth-browse

Bypasses sophisticated anti-bot shields (Cloudflare Turnstile, DataDome, PerimeterX) using randomized bezier human cursor curves, micro-scroll deceleration, and optional custom residential proxy routing.

Parameters

# Stealth Browse with Custom Residential Proxy
curl -X POST https://opticparse-api.onrender.com/api/stealth-browse \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/protected-page",
    "proxy": "http://user:pass@proxy.brightdata.com:22225",
    "wait_for_challenge_seconds": 3,
    "simulate_human_interactions": true
  }'

POST /api/cache/markdown

Extracts token-optimized clean Markdown stripped of 98% of HTML boilerplate (navbars, tracking pixels, ads, footers) backed by a persistent semantic edge cache with cryptographic attestation.

Parameters

POST /api/verify-attestation

Validates an HMAC-SHA256 cryptographic attestation proof proving that scraped web content was extracted accurately at a specific Unix timestamp without tampering.

Parameters

Python SDK (opticparse-py v1.0.1)

The official zero-dependency Python SDK with sub-50ms local heuristic evaluation and native proxy passthrough.

# Install
pip install --upgrade opticparse-py

# Usage with custom proxy & fast heuristics
from opticparse import OpticParse

client = OpticParse(
    api_key="op_live_...",
    proxy="http://user:pass@proxy.ip:port"  # Optional enterprise proxy
)

# Sub-50ms rapid threat scan
verdict = client.detect_phishing("https://example.com", fast_heuristics=True)
print("Safety Score:", verdict["threat_score"], "Verdict:", verdict["verdict"])

LangChain Tool (langchain-opticparse v1.0.3)

Drop-in multi-agent toolkits for LangChain, CrewAI, and AutoGPT with in-terminal prepaid credit refills.

# Install
pip install --upgrade langchain-opticparse

# Usage with LangChain Agent
from langchain_opticparse import OpticParseTool, PhishVisionTool

scraper = OpticParseTool(proxy="http://proxy:8080")
threat_scanner = PhishVisionTool()

# Bind to any tool-calling LLM
llm_with_tools = llm.bind_tools([scraper, threat_scanner])

LlamaIndex ToolSpec (llama-index-tools-opticparse)

Official BaseToolSpec integration for LlamaIndex query engines and autonomous agents.

# Install
pip install llama-index-tools-opticparse

# Usage in LlamaIndex
from llama_index.tools.opticparse import OpticParseToolSpec
from llama_index.core.agent import FunctionCallingAgentWorker

tool_spec = OpticParseToolSpec(api_key="op_live_...")
tools = tool_spec.to_tool_list()
agent = FunctionCallingAgentWorker.from_tools(tools, llm=llm).as_agent()