API Documentation & Guide

Welcome to the Onion Search Engine API! Our API suite provides programmatic access to our comprehensive index of the Tor network, allowing you to integrate deep web search and analysis capabilities directly into your applications.

Authentication

All requests to the Onion Search Engine API suite must be authenticated using an API Key (your token), found in your user dashboard. To authenticate, include your key in the X-API-Key HTTP header.

X-API-Key: sk-your_unique_api_key_here

Standard Search API

Endpoint URL: `/api.php`

This is the core endpoint for performing real-time keyword searches.

Parameter	Type	Required	Description
`q`	string	Yes	Your search query. Supports the `site:` operator.
`page`	integer	No	The page number for pagination. Defaults to `1`.

Understanding the JSON Response

All successful responses are returned in JSON format with a standard structure. An example from the Search API is below:

{
    "status": "success",
    "pagination": { "total_results": 150, "total_pages": 15, ... },
    "results": [ { "title": "...", "url": "...", "context": "...", ... } ]
}

History API PREMIUM

Endpoint URL: `/api_history.php`

Access historical snapshots of a given .onion page, like a "Wayback Machine" for Tor. This is a premium feature available on Researcher plans and above.

This endpoint has two modes:

1. List Available Snapshots

Call with just the url parameter to get a list of all cached dates.

# Request
curl -H "X-API-Key: sk-your_key" "https://onionsearchengine.com/api_history.php?url=example.onion"

# Response
{
    "status": "success",
    "url": "example.onion",
    "available_snapshots": 2,
    "snapshot_dates": ["2025-06-10T10:30:00Z", "2025-05-15T08:00:00Z"]
}

2. Get Specific Snapshot Content

Add the date parameter to retrieve the full HTML content of a specific snapshot.

# Request
curl -H "X-API-Key: sk-your_key" "https://onionsearchengine.com/api_history.php?url=example.onion&date=2025-05-20"

# Response
{
    "status": "success",
    "data": { "url": "...", "snapshot_date": "...", "content": "..." }
}

Metadata API PREMIUM

Endpoint URL: `/api_metadata.php`

Retrieve structured metadata (emails, crypto addresses, etc.) that our system has automatically extracted from a site's content.

# Request
curl -H "X-API-Key: sk-your_key" "https://onionsearchengine.com/api_metadata.php?url=example.onion"

# Response
{
    "status": "success",
    "data": {
        "url": "example.onion",
        "last_analyzed": "...",
        "emails": ["[email protected]"],
        "btc_addresses": ["1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"],
        "xmr_addresses": []
    }
}

Link Graph API PREMIUM

Endpoint URL: `/api_graph.php`

Analyze the relationships between sites by querying for inbound or outbound links.

Parameter	Type	Required	Description
`url`	string	Yes	The .onion URL to analyze.
`direction`	string	No	Set to `in` for inbound links or `out` for outbound links. Defaults to `out`.

# Request for outbound links
curl -H "X-API-Key: sk-your_key" "https://onionsearchengine.com/api_graph.php?url=example.onion&direction=out"

# Response
{
    "status": "success",
    "query_details": { "analyzed_url": "example.onion", "direction": "out", ... },
    "links": ["siteB.onion", "siteC.onion"]
}

Vulnerability Analysis PREMIUM

Retrieve a list of known vulnerabilities (CVEs) for the technologies detected on a specific .onion site.

This endpoint leverages our internal technology profiling data and cross-references it with public vulnerability databases (like the NVD) to provide actionable security intelligence. This feature is available for **Plus, Researcher, and Enterprise** plans.

GET /api_vulnerabilities.php

Headers

Header	Description
`X-API-Key`	Required. Your unique API key for authentication.

Parameters

Parameter	Description
`url`	Required. The .onion URL you want to analyze (e.g., `examplewzdd3a5555.onion`).

Example Request (cURL)


curl -H "X-API-Key: YOUR_API_KEY_HERE" \
"https://onionsearchengine.com/api_vulnerabilities.php?url=examplewzdd3a5555.onion"

Example Success Response (200 OK)


{
  "status": "success",
  "url": "http://examplewzdd3a5555.onion",
  "data": [
    {
      "software_name": "nginx",
      "cve_id": "CVE-2021-23017",
      "severity": "HIGH",
      "description": "A security issue in the DNS resolver in nginx..."
    },
    {
      "software_name": "wordpress",
      "cve_id": "CVE-2023-4567",
      "severity": "CRITICAL",
      "description": "A critical vulnerability in the core..."
    }
  ]
}

Example Error Response (403 Forbidden)


{
  "status": "error",
  "message": "Your current plan does not allow access to this feature."
}

Error Handling & Status Codes

If a request fails, the API will return a non-200 HTTP status code and a JSON body with an error message. This applies to all endpoints.

Code Examples (for Standard Search)

Here are practical examples for using the standard search API. The pattern for calling premium endpoints is similar.

Frequently Asked Questions (FAQ)

How do I get an API key?

You can get an API key instantly by signing up for one of our plans. The free Developer plan is a great way to start.

How can I check my usage and access premium tools?

Your usage stats, API key, and premium features like Keyword Alerts and Site Analysis are all available on your personal dashboard.

What is the difference between the APIs?

The **Standard Search API** is for real-time keyword searches. The **Premium APIs** (History, Metadata, Graph) provide deeper, pre-processed analytical data about specific sites, saving you countless hours of manual work.

How can I report a problem?

Please do not hesitate to contact our support team.