### JavaScript: Search Database

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Example of how to perform a database search using JavaScript. Ensure you have the 'axios' library installed for making HTTP requests.

```javascript
const axios = require('axios');

const searchDatabase = async (terms, types) => {
  try {
    const response = await axios.post('https://api.snusbase.com/data/search', {
      terms: terms,
      types: types,
      wildcard: false,
      group_by: false
    }, {
      headers: {
        'Content-Type': 'application/json',
        'Auth': 'YOUR_API_KEY_HERE'
      }
    });
    return response.data;
  } catch (error) {
    console.error('Error searching database:', error);
    return null;
  }
};

searchDatabase(['example@gmail.com'], ['email']).then(data => {
  console.log(data);
});
```

--------------------------------

### Python: Search Database

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Example of how to perform a database search using Python. This script sends a POST request to the Snusbase API.

```python
import requests
import json

def search_database(terms, types):
    url = "https://api.snusbase.com/data/search"
    headers = {
        "Content-Type": "application/json",
        "Auth": "YOUR_API_KEY_HERE"
    }
    payload = {
        "terms": terms,
        "types": types,
        "wildcard": False,
        "group_by": False
    }
    
    try:
        response = requests.post(url, headers=headers, data=json.dumps(payload))
        response.raise_for_status()  # Raise an exception for bad status codes
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error searching database: {e}")
        return None

results = search_database(['example@gmail.com'], ['email'])
if results:
    print(json.dumps(results, indent=2))
```

--------------------------------

### Python API Client Usage

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Examples demonstrating how to use the Snusbase API client in Python (requests) for various operations including fetching stats, performing searches, and using lookup tools.

```APIDOC
## Python 3 (requests)

```python
import os, requests

SNUSBASE_AUTH = os.environ["SNUSBASE_API_KEY"]   # e.g. "sbXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
SNUSBASE_API  = "https://api.snusbase.com/"

def snusbase_request(path: str, body: dict | None = None) -> dict:
    headers = {"Auth": SNUSBASE_AUTH, "Content-Type": "application/json"}
    method  = "POST" if body else "GET"
    resp    = requests.request(method, SNUSBASE_API + path, headers=headers, json=body)
    if not resp.ok:
        raise RuntimeError(f"Snusbase {resp.status_code}: {resp.text}")
    return {
        "data": resp.json(),
        "rate_limit": {
            "remaining":      int(resp.headers.get("X-Rate-Limit-Remaining", -1)),
            "reset_in_secs":  int(resp.headers.get("X-Rate-Limit-Reset", -1)),
        },
    }

# Usage examples
if __name__ == "__main__":
    stats = snusbase_request("data/stats")["data"]
    print(f"Total rows indexed: {stats['rows']}")

    result = snusbase_request("data/search", {
        "terms": ["example@gmail.com"],
        "types": ["email"],
    })
    print(f"Found {result['data']['size']} results "
          f"({result['rate_limit']['remaining']} requests left)")

    combo = snusbase_request("tools/combo-lookup", {
        "terms": ["example@gmail.com"], "types": ["username"],
    })["data"]
    print(f"Combo hits: {combo['size']}")

    hashes = snusbase_request("tools/hash-lookup", {
        "terms": ["482c811da5d5b4bc6d497ffa98491e38"], "types": ["hash"],
    })["data"]
    print(f"Hash resolved: {hashes['results']['HASHES'][0]['password']}")

    whois = snusbase_request("tools/ip-whois", {"terms": ["12.34.56.78"]})["data"]
    ip_info = whois["results"]["12.34.56.78"]
    print(f"IP location: {ip_info['city']}, {ip_info['country']}")
```
```

--------------------------------

### Reusable API Client in Python

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Handles authentication, method selection, and JSON serialization for Snusbase API requests. Includes usage examples for various endpoints.

```python
import os, requests

SNUSBASE_AUTH = os.environ["SNUSBASE_API_KEY"]   # e.g. "sbXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
SNUSBASE_API  = "https://api.snusbase.com/"

def snusbase_request(path: str, body: dict | None = None) -> dict:
    headers = {"Auth": SNUSBASE_AUTH, "Content-Type": "application/json"}
    method  = "POST" if body else "GET"
    resp    = requests.request(method, SNUSBASE_API + path, headers=headers, json=body)
    if not resp.ok:
        raise RuntimeError(f"Snusbase {resp.status_code}: {resp.text}")
    return {
        "data": resp.json(),
        "rate_limit": {
            "remaining":      int(resp.headers.get("X-Rate-Limit-Remaining", -1)),
            "reset_in_secs":  int(resp.headers.get("X-Rate-Limit-Reset", -1)),
        },
    }

# Usage examples
if __name__ == "__main__":
    stats = snusbase_request("data/stats")["data"]
    print(f"Total rows indexed: {stats['rows']}")

    result = snusbase_request("data/search", {
        "terms": ["example@gmail.com"],
        "types": ["email"],
    })
    print(f"Found {result['data']['size']} results "
          f"({result['rate_limit']['remaining']} requests left)")

    combo = snusbase_request("tools/combo-lookup", {
        "terms": ["example@gmail.com"], "types": ["username"],
    })["data"]
    print(f"Combo hits: {combo['size']}")

    hashes = snusbase_request("tools/hash-lookup", {
        "terms": ["482c811da5d5b4bc6d497ffa98491e38"], "types": ["hash"],
    })["data"]
    print(f"Hash resolved: {hashes['results']['HASHES'][0]['password']}")

    whois = snusbase_request("tools/ip-whois", {"terms": ["12.34.56.78"]})["data"]
    ip_info = whois["results"]["12.34.56.78"]
    print(f"IP location: {ip_info['city']}, {ip_info['country']}")
```

--------------------------------

### Reusable API Client in JavaScript

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Handles authentication, method selection, and JSON serialization for Snusbase API requests. Includes usage examples for various endpoints.

```javascript
const SNUSBASE_AUTH = process.env.SNUSBASE_API_KEY; // e.g. "sbXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
const SNUSBASE_API  = 'https://api.snusbase.com/';

async function snusbaseRequest(path, body = null) {
  const res = await fetch(SNUSBASE_API + path, {
    method:  body ? 'POST' : 'GET',
    headers: { 'Auth': SNUSBASE_AUTH, 'Content-Type': 'application/json' },
    body:    body ? JSON.stringify(body) : null,
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error(`Snusbase ${res.status}: ${JSON.stringify(err.errors ?? err)}`);
  }
  // Expose rate-limit state for upstream throttling
  const remaining = res.headers.get('X-Rate-Limit-Remaining');
  const reset      = res.headers.get('X-Rate-Limit-Reset');
  const data       = await res.json();
  return { data, rateLimit: { remaining: Number(remaining), resetInSeconds: Number(reset) } };
}

// Usage examples
(async () => {
  const { data: stats } = await snusbaseRequest('data/stats');
  console.log(`Total rows indexed: ${stats.rows}`);

  const { data: search, rateLimit } = await snusbaseRequest('data/search', {
    terms: ['example@gmail.com'],
    types: ['email'],
  });
  console.log(`Found ${search.size} results (${rateLimit.remaining} requests left)`)

  const { data: combo } = await snusbaseRequest('tools/combo-lookup', {
    terms: ['example@gmail.com'], types: ['username'],
  });
  console.log(`Combo hits: ${combo.size}`);

  const { data: hashes } = await snusbaseRequest('tools/hash-lookup', {
    terms: ['482c811da5d5b4bc6d497ffa98491e38'], types: ['hash'],
  });
  console.log(`Hash resolved: ${hashes.results?.HASHES?.[0]?.password}`);

  const { data: whois } = await snusbaseRequest('tools/ip-whois', {
    terms: ['12.34.56.78'],
  });
  console.log(`IP location: ${whois.results['12.34.56.78'].city}, ${whois.results['12.34.56.78'].country}`);
})();
```

--------------------------------

### JavaScript API Client Usage

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Examples demonstrating how to use the Snusbase API client in JavaScript (Node.js/browser fetch) for various operations including fetching stats, performing searches, and using lookup tools.

```APIDOC
## JavaScript (Node.js / browser fetch)

```javascript
const SNUSBASE_AUTH = process.env.SNUSBASE_API_KEY; // e.g. "sbXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
const SNUSBASE_API  = 'https://api.snusbase.com/';

async function snusbaseRequest(path, body = null) {
  const res = await fetch(SNUSBASE_API + path, {
    method:  body ? 'POST' : 'GET',
    headers: { 'Auth': SNUSBASE_AUTH, 'Content-Type': 'application/json' },
    body:    body ? JSON.stringify(body) : null,
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error(`Snusbase ${res.status}: ${JSON.stringify(err.errors ?? err)}`);
  }
  // Expose rate-limit state for upstream throttling
  const remaining = res.headers.get('X-Rate-Limit-Remaining');
  const reset      = res.headers.get('X-Rate-Limit-Reset');
  const data       = await res.json();
  return { data, rateLimit: { remaining: Number(remaining), resetInSeconds: Number(reset) } };
}

// Usage examples
(async () => {
  const { data: stats } = await snusbaseRequest('data/stats');
  console.log(`Total rows indexed: ${stats.rows}`);

  const { data: search, rateLimit } = await snusbaseRequest('data/search', {
    terms: ['example@gmail.com'],
    types: ['email'],
  });
  console.log(`Found ${search.size} results (${rateLimit.remaining} requests left)`)

  const { data: combo } = await snusbaseRequest('tools/combo-lookup', {
    terms: ['example@gmail.com'], types: ['username'],
  });
  console.log(`Combo hits: ${combo.size}`);

  const { data: hashes } = await snusbaseRequest('tools/hash-lookup', {
    terms: ['482c811da5d5b4bc6d497ffa98491e38'], types: ['hash'],
  });
  console.log(`Hash resolved: ${hashes.results?.HASHES?.[0]?.password}`);

  const { data: whois } = await snusbaseRequest('tools/ip-whois', {
    terms: ['12.34.56.78'],
  });
  console.log(`IP location: ${whois.results['12.34.56.78'].city}, ${whois.results['12.34.56.78'].country}`);
})();
```
```

--------------------------------

### GET Database Statistics

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Retrieve information about the current databases in the main search engine. This endpoint does not require authentication.

```http
GET https://api.snusbase.com/data/stats
```

--------------------------------

### API Authentication Header

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Include your activation code in the 'Auth' header for all API requests. Codes generated after September 2021 start with 'sb'.

```http
Auth: sb[...]
```

--------------------------------

### Get Database Statistics

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Retrieves statistics about the available data in the database.

```APIDOC
## GET /data/stats

### Description
Fetches general statistics about the Snusbase database, such as the total number of entries or available data types.

### Method
GET

### Endpoint
https://api.snusbase.com/data/stats

### Response
#### Success Response (200)
- **stats** (object) - An object containing various database statistics.

#### Response Example
```json
{
  "stats": {
    "total_entries": 1000000,
    "available_types": ["username", "email", "hash"]
  }
}
```
```

--------------------------------

### Get Database Statistics

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Retrieves aggregate statistics about all tables in the Snusbase search engine. This endpoint does not require authentication and is useful for health checks or dynamically building search interfaces.

```bash
curl -s https://api.snusbase.com/data/stats | jq .
```

--------------------------------

### GET /data/stats — Database Statistics

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Retrieves aggregate statistics about the Snusbase breach database, including total row counts and table schemas. This endpoint does not require authentication.

```APIDOC
## GET /data/stats — Database Statistics

### Description
Returns aggregate statistics about all tables available in the main search engine, including total row counts, per-table column schemas, and which tables support extended features such as `view_more` and `combo_lookup`. This endpoint requires no authentication and is suitable for health checks or dynamically building search UI from available table schemas.

### Method
GET

### Endpoint
/data/stats

### Response
#### Success Response (200)
- **rows** (integer) - Total number of rows in the database.
- **tables** (object) - An object where keys are table names and values are arrays of column names.
- **features** (object) - An object detailing tables that support specific features like `view_more` and `combo_lookup`.

### Response Example
```json
{
  "rows": 18006941078,
  "tables": {
    "0001_STEALERLOGS_NA_121M_MALWARE_2023": ["email", "username", "password", "host", "_domain"],
    ...
  },
  "features": {
    "view_more": ["0005_ZING_VN_51M_ENTERTAINMENT_052015", ...],
    "combo_lookup": ["0001_PEMIBLANC_COMBOLIST_245M_2018", ...]
  }
}
```
```

--------------------------------

### Search with Wildcards

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Utilize wildcard characters '%' (any number of characters) and '_' (exactly one character) in search terms. Wildcards cannot be the first character. Use the `_domain` type for domain searches. Escape wildcards with a backslash.

```http
POST https://api.snusbase.com/data/search
Content-Type: application/json
Auth: YOUR_API_KEY_HERE

{
  "terms": ["exa____@%.tld"],
  "types": ["email"],
  "wildcard": true
}
```

--------------------------------

### Simulate Auth Failure with cURL

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Demonstrates how to simulate an authentication failure by using an invalid API key. This returns a 401 status code.

```bash
# Simulate an auth failure
curl -s -o /dev/null -w "%{http_code}" \
  -X POST https://api.snusbase.com/data/search \
  -H "Auth: invalid_key" \
  -H "Content-Type: application/json" \
  -d '{"terms":["test"],"types":["email"]}'
# → 401
```

--------------------------------

### Combolist Lookup (Username/Email)

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Queries the combolist database to find all passwords associated with a given username or email. This endpoint is specifically for credential-pair lookups.

```bash
curl -s -X POST https://api.snusbase.com/tools/combo-lookup \
  -H "Auth: sbYOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": ["example@gmail.com"],
    "types": ["username"]
  }' | jq .
```

--------------------------------

### Check Rate Limit State with cURL

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Shows how to check the current rate-limit state without consuming search quota by making a request to the /data/stats endpoint and grepping for rate-limit headers.

```bash
# Check current rate-limit state without consuming search quota
curl -si https://api.snusbase.com/data/stats \
  -H "Auth: sbYOUR_API_KEY_HERE" | grep -i "X-Rate-Limit"
# X-Rate-Limit: 256
# X-Rate-Limit-Remaining: 255
```

--------------------------------

### POST Combo Lookup Request

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Search the combolist database for username/password combinations. Requires 'Content-Type: application/json' and 'Auth' headers.

```http
POST https://api.snusbase.com/tools/combo-lookup
Content-Type: application/json
Auth: YOUR_API_KEY_HERE

{
  "terms": ["username:password"],
  "types": ["combo"]
}
```

--------------------------------

### Search Breach Database (Multiple Terms and Types)

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Searches the database for multiple terms across various data types including username, email, IP address, password, and hash. This demonstrates flexible querying capabilities.

```bash
curl -s -X POST https://api.snusbase.com/data/search \
  -H "Auth: sbYOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": ["alice", "bob@example.com"],
    "types": ["username", "email", "lastip", "hash", "password", "name"]
  }' | jq .
```

--------------------------------

### Combo Lookup Request

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Use this endpoint to search for username/password combinations. Ensure 'terms' and 'types' are provided.

```http
POST https://api.snusbase.com/tools/combo-lookup
Content-Type: application/json
Auth: YOUR_API_KEY_HERE

{
  "terms": ["example@gmail.com"],
  "types": ["username"]
}
```

--------------------------------

### Search Breach Database (Targeted Table and Grouping)

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Searches a specific table within the breach database and groups the results by domain instead of the default database. This allows for more focused analysis.

```bash
curl -s -X POST https://api.snusbase.com/data/search \
  -H "Auth: sbYOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": ["example"],
    "types": ["username"],
    "tables": ["0001_STEALERLOGS_NA_106M_MALWARE_2023"],
    "group_by": "_domain"
  }' | jq .
```

--------------------------------

### Combo Lookup

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Search the combolist database for username/password combinations from large credential dumps.

```APIDOC
## POST /tools/combo-lookup

### Description
Search the combolist database for username/password combinations from large credential dumps.

### Method
POST

### Endpoint
https://api.snusbase.com/tools/combo-lookup

### Headers
- `Content-Type: application/json`
- `Auth: YOUR_API_KEY_HERE`
```

--------------------------------

### Combo Lookup

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Performs a lookup for combined username and password pairs.

```APIDOC
## POST /tools/combo-lookup

### Description
Looks up potential username and password combinations based on provided terms.

### Method
POST

### Endpoint
https://api.snusbase.com/tools/combo-lookup

### Parameters
#### Request Body
- **terms** (array of strings) - Required - The terms to look up (e.g., usernames).
- **types** (array of strings) - Optional - The types of data to associate with the terms. Defaults to ["username"].

### Request Example
```json
{
  "terms": ["john_doe"],
  "types": ["username"]
}
```

### Response
#### Success Response (200)
- **results** (array) - The lookup results.

#### Response Example
```json
{
  "results": [
    {
      "username": "john_doe",
      "password": "password123"
    }
  ]
}
```
```

--------------------------------

### POST /tools/combo-lookup — Combo Lookup

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Queries the combolist database for username/password pairs. Supports wildcard searches and grouping, similar to the database search endpoint.

```APIDOC
## POST /tools/combo-lookup — Combo Lookup

### Description
Queries the combolist database, which is a separate index of username/password pairs sourced from large credential dumps. Supported `types` are `"username"` and `"password"`. The endpoint supports the same `wildcard` and `group_by` parameters as `/data/search`. Use this endpoint specifically when you need credential-pair lookups rather than full breach record searches.

### Method
POST

### Endpoint
/tools/combo-lookup

### Parameters
#### Query Parameters
- **terms** (array of strings) - Required - The terms to search for (usernames or passwords).
- **types** (array of strings) - Required - The field types to search within (`"username"` or `"password"`).
- **wildcard** (boolean) - Optional - Enables wildcard search.
- **group_by** (string) - Optional - Field to group search results by.

#### Request Body
- **terms** (array of strings) - Required - The terms to search for.
- **types** (array of strings) - Required - The field types to search within.
- **wildcard** (boolean) - Optional - Enables wildcard search.
- **group_by** (string) - Optional - Field to group search results by.

### Request Example
```json
{
  "terms": ["example@gmail.com"],
  "types": ["username"]
}
```
```

--------------------------------

### Search with Multiple Types

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Use this endpoint to search across multiple data types simultaneously. Each type applies to all terms provided.

```http
POST https://api.snusbase.com/data/search
Content-Type: application/json
Auth: YOUR_API_KEY_HERE

{
  "terms": ["example1", "example2"],
  "types": ["username", "email", "lastip", "hash", "password", "name"]
}
```

--------------------------------

### Combo Lookup

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Performs a combo lookup to find usernames and passwords based on provided terms.

```APIDOC
## POST /tools/combo-lookup

### Description
Performs a combo lookup to find usernames and passwords based on provided terms.

### Method
POST

### Endpoint
https://api.snusbase.com/tools/combo-lookup

### Parameters
#### Query Parameters
- **terms** (Array of strings) - Required - Search terms (usernames or passwords).
- **types** (Array of strings) - Required - Types of data to search. Possible values: "username", "password".
- **wildcard** (Boolean) - Optional - Enable wildcard search (`true` or `false`).
- **group_by** (Boolean or string) - Optional - Group results. Defaults to "db". Set to `false` to disable grouping.

### Request Example
```http
POST https://api.snusbase.com/tools/combo-lookup
Content-Type: application/json
Auth: YOUR_API_KEY_HERE

{
  "terms": ["example@gmail.com"],
  "types": ["username"]
}
```

### Response
#### Success Response (200)
- **took** (float) - Time taken for the search in seconds.
- **size** (integer) - Number of results found.
- **results** (object) - An object containing the lookup results, grouped by combolist.
  - **[combolist_name]** (array) - An array of objects, where each object contains a username and password.
    - **username** (string) - The found username.
    - **password** (string) - The found password.

#### Response Example
```json
{
  "took": 2.905,
  "size": 1194,
  "results": {
    "0007_COLLECTION3_COMBOLIST_300M_2019": [
      {
        "username": "example@gmail.com",
        "password": "0981122847"
      },
      {
        "username": "example@gmail.com",
        "password": "123456"
      }
    ]
  }
}
```
```

--------------------------------

### Hash Lookup: Plaintext to Hash

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Performs a reverse lookup to find hashes corresponding to a known plaintext password. Use 'password' in 'types'.

```bash
curl -s -X POST https://api.snusbase.com/tools/hash-lookup \
  -H "Auth: sbYOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": ["password123"],
    "types": ["password"]
  }' | jq .
```

--------------------------------

### Search Breach Database (Wildcard Email)

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Performs a wildcard search to match all email addresses at a specific domain. This requires enabling wildcard mode and using '%' and '_' as wildcard characters.

```bash
curl -s -X POST https://api.snusbase.com/data/search \
  -H "Auth: sbYOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": ["exa____@%.tld"],
    "types": ["email"],
    "wildcard": true
  }' | jq .
```

--------------------------------

### Database Statistics

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Retrieve information about the current databases in the main search engine. This endpoint does not require authentication.

```APIDOC
## GET /data/stats

### Description
Retrieve information about the current databases in the main search engine.

### Method
GET

### Endpoint
https://api.snusbase.com/data/stats

### Request Example
```http
GET https://api.snusbase.com/data/stats
```

### Response
#### Success Response (200)
- **rows** (integer) - Total number of rows across all databases.
- **tables** (object) - An object where keys are table names and values are arrays of column names.
- **features** (object) - An object detailing features like "view_more" and "combo_lookup" with associated table names.

#### Response Example
```json
{
  "rows": 18006941078,
  "tables": {
    "0001_STEALERLOGS_NA_121M_MALWARE_2023": [
      "email", "username", "password", "host", "_domain"
    ]
  },
  "features": {
    "view_more": [
      "0005_ZING_VN_51M_ENTERTAINMENT_052015"
    ],
    "combo_lookup": [
      "0001_PEMIBLANC_COMBOLIST_245M_2018"
    ]
  }
}
```
```

--------------------------------

### Search Breach Database (Basic Email)

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Performs a basic search for a specific email address in the Snusbase breach database. Requires authentication and specifies the search term and type.

```bash
curl -s -X POST https://api.snusbase.com/data/search \
  -H "Auth: sbYOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"terms": ["example@gmail.com"], "types": ["email"]}' | jq .
```

--------------------------------

### IP WHOIS Lookup

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Retrieves WHOIS information for IP addresses.

```APIDOC
## POST /tools/ip-whois

### Description
Retrieves WHOIS information for IP addresses.

### Method
POST

### Endpoint
https://api.snusbase.com/tools/ip-whois

### Parameters
#### Query Parameters
- **terms** (Array of strings) - Required - IP addresses to look up.

### Request Example
```http
POST https://api.snusbase.com/tools/ip-whois
Content-Type: application/json
Auth: YOUR_API_KEY_HERE

{
  "terms": ["12.34.56.78"]
}
```

### Response
#### Success Response (200)
- **took** (float) - Time taken for the search in seconds.
- **size** (integer) - Number of results found.
- **results** (object) - An object containing WHOIS information for each IP address.
  - **[ip_address]** (object) - WHOIS details for the specified IP address.
    - **continent** (string) - The continent of the IP address.
    - **continentCode** (string) - The continent code.
    - **country** (string) - The country of the IP address.
    - **countryCode** (string) - The country code.
    - **region** (string) - The region of the IP address.
    - **regionName** (string) - The name of the region.
    - **city** (string) - The city of the IP address.
    - **zip** (string) - The zip code of the IP address.
    - **lat** (float) - The latitude of the IP address.
    - **lon** (float) - The longitude of the IP address.
    - **timezone** (string) - The timezone of the IP address.
    - **isp** (string) - The Internet Service Provider (ISP) of the IP address.
    - **org** (string) - The organization associated with the IP address.
    - **as** (string) - The Autonomous System (AS) number and name.
    - **asname** (string) - The AS name.
    - **mobile** (boolean) - Indicates if the IP is associated with a mobile network.
    - **proxy** (boolean) - Indicates if the IP is a proxy.
    - **hosting** (boolean) - Indicates if the IP is used for hosting.

#### Response Example
```json
{
  "took": 6.4,
  "size": 1,
  "results": {
    "12.34.56.78": {
      "continent": "North America",
      "continentCode": "NA",
      "country": "United States",
      "countryCode": "US",
      "region": "OH",
      "regionName": "Ohio",
      "city": "Columbus",
      "zip": "43215",
      "lat": 39.9612,
      "lon": -82.9988,
      "timezone": "America/New_York",
      "isp": "AT&T Enterprises, LLC",
      "org": "AT&T Enterprises, LLC",
      "as": "AS7018 AT&T Enterprises, LLC",
      "asname": "ATT-INTERNET4",
      "mobile": false,
      "proxy": false,
      "hosting": false
    }
  }
}
```
```

--------------------------------

### Hash Lookup Response

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

The response includes the time taken, total size, and a list of found hashes with their corresponding passwords.

```json
{
  "took": 0.102,
  "size": 1,
  "results": {
    "HASHES": [
      {
        "hash": "482c811da5d5b4bc6d497ffa98491e38",
        "password": "password123"
      }
    ]
  }
}
```

--------------------------------

### Search Specific Tables

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Specify one or more tables to narrow down search results. This is useful for features like 'View More' and displays all available columns for the specified tables.

```http
POST https://api.snusbase.com/data/search
Content-Type: application/json
Auth: YOUR_API_KEY_HERE

{
  "terms": ["example"],
  "types": ["username"],
  "tables": ["0001_STEALERLOGS_NA_106M_MALWARE_2023"]
}
```

--------------------------------

### IP WHOIS Lookup

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Performs a WHOIS lookup for a given IP address.

```APIDOC
## POST /tools/ip-whois

### Description
Fetches WHOIS information for a specified IP address.

### Method
POST

### Endpoint
https://api.snusbase.com/tools/ip-whois

### Parameters
#### Request Body
- **terms** (array of strings) - Required - The IP addresses to perform the WHOIS lookup on.

### Request Example
```json
{
  "terms": ["12.34.56.78"]
}
```

### Response
#### Success Response (200)
- **results** (array) - The WHOIS lookup results.

#### Response Example
```json
{
  "results": [
    {
      "ip": "12.34.56.78",
      "country": "USA"
    }
  ]
}
```
```

--------------------------------

### JavaScript API Client

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

A JavaScript client for interacting with the Snusbase API. Includes functions for making authenticated requests to various endpoints like data statistics, search, combo lookup, hash lookup, and IP WHOIS.

```javascript
const snusbaseAuth = 'YOUR_API_KEY_HERE';
const snusbaseAPI = 'https://api.snusbase.com/';

const sendRequest = async (url, body = null) => {
  const options = {
    method: body ? 'POST' : 'GET',
    headers: {
      'Auth': snusbaseAuth,
      'Content-Type': 'application/json',
    },
    body: body ? JSON.stringify(body) : null,
  };
  const response = await fetch(snusbaseAPI + url, options);
  return await response.json();
};

// Example: Get Database Statistics
sendRequest('data/stats').then(response => console.log(response));

// Example: Search Snusbase
sendRequest('data/search', {
  terms: ['example@gmail.com'],
  types: ['email'],
}).then(response => console.log(response));

// Example: Combo Lookup
sendRequest('tools/combo-lookup', {
  terms: ['example@gmail.com'],
  types: ['username'],
}).then(response => console.log(response));

// Example: Hash Lookup
sendRequest('tools/hash-lookup', {
  terms: ['482c811da5d5b4bc6d497ffa98491e38'],
  types: ['hash'],
}).then(response => console.log(response));

// Example: IP WHOIS Lookup
sendRequest('tools/ip-whois', {
  terms: ['12.34.56.78'],
}).then(response => console.log(response));
```

--------------------------------

### Hash Lookup: Resolve Hash to Plaintext

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Looks up a given password hash to retrieve the corresponding plaintext password. Use 'hash' in 'types'.

```bash
curl -s -X POST https://api.snusbase.com/tools/hash-lookup \
  -H "Auth: sbYOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": ["482c811da5d5b4bc6d497ffa98491e38"],
    "types": ["hash"]
  }' | jq .
```

--------------------------------

### IP WHOIS Lookup Request

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Retrieve WHOIS information for IP addresses. The 'terms' parameter must contain an array of IP addresses.

```http
POST https://api.snusbase.com/tools/ip-whois
Content-Type: application/json
Auth: YOUR_API_KEY_HERE

{
  "terms": ["12.34.56.78"]
}
```

--------------------------------

### Python API Client

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

A Python client for interacting with the Snusbase API using the requests library. Provides functions for authenticated requests to endpoints such as data statistics, search, combo lookup, hash lookup, and IP WHOIS.

```python
import requests

snusbase_auth = 'YOUR_API_KEY_HERE'
snusbase_api = 'https://api.snusbase.com/'

def send_request(url, body=None):
    headers = {
        'Auth': snusbase_auth,
        'Content-Type': 'application/json',
    }
    method = 'POST' if body else 'GET'
    response = requests.request(method, snusbase_api + url, headers=headers, json=body)
    return response.json()

# Example: Get Database Statistics
stats_response = send_request('data/stats')
print(stats_response)

# Example: Search Snusbase
search_response = send_request('data/search', {
    'terms': ['example@gmail.com'],
    'types': ['email'],
})
print(search_response)

# Example: Combo Lookup
combo_lookup_response = send_request('tools/combo-lookup', {
    'terms': ['example@gmail.com'],
    'types': ['username'],
})
print(combo_lookup_response)

# Example: Hash Lookup
hash_lookup_response = send_request('tools/hash-lookup', {
    'terms': ['482c811da5d5b4bc6d497ffa98491e38'],
    'types': ['hash'],
})
print(hash_lookup_response)

# Example: IP WHOIS Lookup
ip_whois_response = send_request('tools/ip-whois', {
    'terms': ['12.34.56.78'],
})
print(ip_whois_response)
```

--------------------------------

### Combo Lookup Response

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

The response contains lookup results, including the number of results and the data organized by combolist.

```json
{
  "took": 2.905,
  "size": 1194,
  "results": {
    "0007_COLLECTION3_COMBOLIST_300M_2019": [
      {
        "username": "example@gmail.com",
        "password": "0981122847"
      },
      {
        "username": "example@gmail.com",
        "password": "123456"
      },
      /* Other results.. */
    ],
    /* Other combolists */
  }
}
```

--------------------------------

### POST /tools/hash-lookup — Hash Lookup

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Looks up password hashes against the cracked-hash database to retrieve the corresponding plaintext password, or performs a reverse lookup (plaintext → hash). Supports `wildcard` and `group_by` parameters. Useful for offline password-audit pipelines where hashes need to be resolved without local cracking infrastructure.

```APIDOC
## POST /tools/hash-lookup — Hash Lookup

### Description
Looks up password hashes against the cracked-hash database to retrieve the corresponding plaintext password, or performs a reverse lookup (plaintext → hash). Supported `types` are `"hash"` and `"password"`. Supports `wildcard` and `group_by` parameters. Useful for offline password-audit pipelines where hashes need to be resolved without local cracking infrastructure.

### Method
POST

### Endpoint
https://api.snusbase.com/tools/hash-lookup

### Parameters
#### Request Body
- **terms** (array[string]) - Required - The terms to look up (hashes or plaintexts).
- **types** (array[string]) - Required - The type of terms to look up. Can be `"hash"` or `"password"`.
- **wildcard** (boolean) - Optional - Whether to use wildcard matching.
- **group_by** (boolean) - Optional - Whether to group results.

### Request Example
```json
{
  "terms": ["482c811da5d5b4bc6d497ffa98491e38"],
  "types": ["hash"]
}
```

### Response
#### Success Response (200)
- **took** (float) - The time taken for the request in seconds.
- **size** (integer) - The number of results found.
- **results** (object) - An object containing the lookup results.
  - **HASHES** (array[object]) - An array of objects, where each object contains the `hash` and `password`.
    - **hash** (string) - The found hash.
    - **password** (string) - The corresponding plaintext password.

#### Response Example
```json
{
  "took": 0.102,
  "size": 1,
  "results": {
    "HASHES": [
      { "hash": "482c811da5d5b4bc6d497ffa98491e38", "password": "password123" }
    ]
  }
}
```
```

--------------------------------

### IP WHOIS Lookup: Multiple IPs

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Enriches multiple IP addresses in a single request with geographic and network metadata. Results are keyed by the queried IP address.

```bash
curl -s -X POST https://api.snusbase.com/tools/ip-whois \
  -H "Auth: sbYOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"terms": ["12.34.56.78", "98.76.54.32", "1.2.3.4"]}' | jq .
```

--------------------------------

### Hash Lookup

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Looks up information associated with a given hash.

```APIDOC
## POST /tools/hash-lookup

### Description
Retrieves data associated with a specific hash value.

### Method
POST

### Endpoint
https://api.snusbase.com/tools/hash-lookup

### Parameters
#### Request Body
- **terms** (array of strings) - Required - The hash values to look up.
- **types** (array of strings) - Optional - The type of hash. Defaults to ["hash"].

### Request Example
```json
{
  "terms": ["482c811da5d5b4bc6d497ffa98491e38"],
  "types": ["hash"]
}
```

### Response
#### Success Response (200)
- **results** (array) - The lookup results.

#### Response Example
```json
{
  "results": [
    {
      "hash": "482c811da5d5b4bc6d497ffa98491e38",
      "username": "user1"
    }
  ]
}
```
```

--------------------------------

### Hash Lookup Request

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Perform a hash lookup to find corresponding plaintext passwords. Requires 'terms' and 'types' to be specified.

```http
POST https://api.snusbase.com/tools/hash-lookup
Content-Type: application/json
Auth: YOUR_API_KEY_HERE

{
  "terms": ["482c811da5d5b4bc6d497ffa98491e38"],
  "types": ["hash"]
}
```

--------------------------------

### Group Search Results by Column

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Group search results by a specific column. If a result lacks the specified column, it will be placed in a `NO_{GROUP_BY}` object. The default grouping is 'db', which can be disabled by setting `group_by` to `false`.

```http
POST https://api.snusbase.com/data/search
Content-Type: application/json
Auth: YOUR_API_KEY_HERE

{
  "terms": ["example"],
  "types": ["username"],
  "group_by": "_domain"
}
```

--------------------------------

### Reverse Lookup by Password

Source: https://context7.com/snusbase/docs.snusbase.com/llms.txt

Find all usernames associated with a known password. Requires the password in the 'terms' and 'password' in 'types'.

```bash
curl -s -X POST https://api.snusbase.com/tools/combo-lookup \
  -H "Auth: sbYOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": ["hunter2"],
    "types": ["password"],
    "group_by": false
  }' | jq .
```

--------------------------------

### POST Database Search Request

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Search the Snusbase database for leaked information using terms and data types. Enable wildcard search and specify tables if needed. Requires 'Content-Type: application/json' and 'Auth' headers.

```http
POST https://api.snusbase.com/data/search
Content-Type: application/json
Auth: YOUR_API_KEY_HERE

{
  "terms": ["example@gmail.com"],
  "types": ["email"]
}
```

--------------------------------

### IP WHOIS Lookup Response

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

The response provides detailed WHOIS information for the queried IP address, including location, ISP, and network details.

```json
{
  "took": 6.4,
  "size": 1,
  "results": {
    "12.34.56.78": {
      "continent": "North America",
      "continentCode": "NA",
      "country": "United States",
      "countryCode": "US",
      "region": "OH",
      "regionName": "Ohio",
      "city": "Columbus",
      "zip": "43215",
      "lat": 39.9612,
      "lon": -82.9988,
      "timezone": "America/New_York",
      "isp": "AT&T Enterprises, LLC",
      "org": "AT&T Enterprises, LLC",
      "as": "AS7018 AT&T Enterprises, LLC",
      "asname": "ATT-INTERNET4",
      "mobile": false,
      "proxy": false,
      "hosting": false
    }
  }
}
```

--------------------------------

### Hash Lookup

Source: https://github.com/snusbase/docs.snusbase.com/blob/main/README.md

Searches for corresponding plaintext passwords or vice versa in the cracked password hash database.

```APIDOC
## POST /tools/hash-lookup

### Description
Searches for corresponding plaintext passwords or vice versa in the cracked password hash database.

### Method
POST

### Endpoint
https://api.snusbase.com/tools/hash-lookup

### Parameters
#### Query Parameters
- **terms** (Array of strings) - Required - Hashes or passwords to look up.
- **types** (Array of strings) - Required - Types of lookup. Possible values: "hash", "password".
- **wildcard** (Boolean) - Optional - Enable wildcard search.
- **group_by** (Boolean or string) - Optional - Group results. Defaults to "db". Set to `false` to disable grouping.

### Request Example
```http
POST https://api.snusbase.com/tools/hash-lookup
Content-Type: application/json
Auth: YOUR_API_KEY_HERE

{
  "terms": ["482c811da5d5b4bc6d497ffa98491e38"],
  "types": ["hash"]
}
```

### Response
#### Success Response (200)
- **took** (float) - Time taken for the search in seconds.
- **size** (integer) - Number of results found.
- **results** (object) - An object containing the lookup results.
  - **HASHES** (array) - An array of objects, where each object contains a hash and its corresponding plaintext password.
    - **hash** (string) - The input hash.
    - **password** (string) - The found plaintext password.

#### Response Example
```json
{
  "took": 0.102,
  "size": 1,
  "results": {
    "HASHES": [
      {
        "hash": "482c811da5d5b4bc6d497ffa98491e38",
        "password": "password123"
      }
    ]
  }
}
```
```