Leaks API

The Leaks API provides access to leaked data collected from Telegram channels, including files, credentials, personal information, and other sensitive data. Search by email, wallet address, IP address, phone number, username, file hash, or perform generic searches across all fields.

Generic Search

Perform a comprehensive search across all leak content and metadata fields with highlighting.

GET/api/v2/leak/search

This endpoint searches across content, detected entities (emails, usernames, phone numbers, IP addresses, wallet addresses), and channel information. Results include highlighted snippets showing where matches were found.

Parameters

Name	Type	Required	Description
`q`	string	Yes	Search query (minimum 3 characters, maximum 500)
`page`	integer	No	Page number (default: 1)
`page_size`	integer	No	Results per page (default: 50, max: 100)
`gte`	string	No	Start date filter (ISO 8601 format)
`lte`	string	No	End date filter (ISO 8601 format)

Highlighted Fields

Results include highlighted snippets with matches wrapped in <mark> tags:

content: Up to 3 context snippets (150 characters each)
detected_info fields: Emails, usernames, phone numbers, IP addresses, wallet addresses
channel_name, channel_username: Highlighted matches

curl "https://api.vysion.ai/api/v2/leak/search?q=password+database&page=1" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key="YOUR_API_KEY")
result = c.search_leaks(
    q="password database",
    gte="2024-01-01",
    lte="2024-12-31"
)

for hit in result.hits:
    print(f"File: {hit.filePath}")
    if hit.highlight:
        print(f"Highlights: {hit.highlight}")

Response with Highlighting

{
  "data": {
    "total": 21,
    "hits": [
      {
        "id": "xyz123",
        "filePath": "leaked_credentials.txt",
        "fileHash": "a3b2c1d4e5f6...",
        "detectionDate": "2024-01-15T10:30:00Z",
        "detectedInfo": {
          "emails": ["admin@company.com"],
          "usernames": ["admin"]
        },
        "highlight": {
          "detectedInfo.emails": ["<mark>admin@company.com</mark>"],
          "content": [
            "Username: admin\n<mark>Password</mark>: secret123",
            "Access to production <mark>database</mark>"
          ]
        }
      }
    ]
  },
  "error": null
}

Example Queries

Email addresses: user@example.com
Usernames: johndoe
IP addresses: 192.168.1.1
Phone numbers: +1234567890
Wallet addresses: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
Keywords: password, database, credentials

Search Leaks by Email

Search for leaked data containing a specific email address.

GET/api/v2/leak/email/{email}

Parameters

Name	Type	Required	Description
`email`	string	Yes	Email address to search for
`page`	integer	No	Page number (default: 1)
`page_size`	integer	No	Results per page (default: 50, max: 100)
`gte`	string	No	Start date filter (ISO 8601 format)
`lte`	string	No	End date filter (ISO 8601 format)

Example Requests

Shell
Python

curl "https://api.vysion.ai/api/v2/leak/email/user@example.com?page=1&page_size=10" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key="YOUR_API_KEY")
result = c.get_leak_by_email(
    email="user@example.com",
    page=1,
    page_size=10
)

for hit in result.hits:
    print(f"File: {hit.filePath}")
    print(f"Detected: {hit.detectionDate}")

Response

{
  "data": {
    "total": 5,
    "hits": [
      {
        "id": "abc123xyz",
        "detectionDate": "2024-01-15T10:30:00Z",
        "filePath": "leaked_database.sql",
        "fileHash": "a3b2c1d4e5f6...",
        "fileSize": 1024000,
        "fileType": "sql",
        "detectedMimeType": "text/plain",
        "detectedInfo": {
          "emails": ["user@example.com"],
          "usernames": ["johndoe"],
          "phone_numbers": ["+1234567890"]
        },
        "telegram": {
          "channelId": -1001234567890,
          "messageId": 42,
          "channelName": "Data Leaks"
        }
      }
    ]
  },
  "error": null
}

Search Leaks by Wallet Address

Search for leaked data containing a cryptocurrency wallet address.

GET/api/v2/leak/wallet/{chain}/{address}

Supported Chains

BTC - Bitcoin
ETH - Ethereum
XMR - Monero
XRP - Ripple
ZEC - Zcash
DOT - Polkadot
BNB - Binance Coin
DASH - Dash

Parameters

Name	Type	Required	Description
`chain`	string	Yes	Cryptocurrency chain identifier (case-insensitive)
`address`	string	Yes	Wallet address to search for
`page`	integer	No	Page number (default: 1)
`page_size`	integer	No	Results per page (default: 50, max: 100)
`gte`	string	No	Start date filter (ISO 8601 format)
`lte`	string	No	End date filter (ISO 8601 format)

Example Requests

Shell
Python

curl "https://api.vysion.ai/api/v2/leak/wallet/BTC/1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key="YOUR_API_KEY")
result = c.get_leak_by_wallet(
    chain="BTC",
    address="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
)

for hit in result.hits:
    print(f"File: {hit.filePath}")
    print(f"Wallets found: {hit.detectedInfo.get('bitcoin_addresses', [])}")

Search Leaks by IP Address

Search for leaked data containing an IP address (IPv4 or IPv6).

GET/api/v2/leak/ip/{ip_address}

Parameters

Name	Type	Required	Description
`ip_address`	string	Yes	IP address (IPv4 or IPv6)
`page`	integer	No	Page number (default: 1)
`page_size`	integer	No	Results per page (default: 50, max: 100)
`gte`	string	No	Start date filter (ISO 8601 format)
`lte`	string	No	End date filter (ISO 8601 format)

Example Requests

Shell
Python

curl "https://api.vysion.ai/api/v2/leak/ip/192.168.1.1" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key="YOUR_API_KEY")
result = c.get_leak_by_ip(
    ip_address="192.168.1.1",
    gte="2024-01-01",
    lte="2024-12-31"
)

for hit in result.hits:
    print(f"File: {hit.filePath}")
    print(f"IPs found: {hit.detectedInfo.get('ipv4_addresses', [])}")

Search Leaks by Phone Number

Search for leaked data containing a phone number.

GET/api/v2/leak/phone/{country_code}/{number}

Parameters

Name	Type	Required	Description
`country_code`	string	Yes	Country code (e.g., “1” for US, “34” for Spain)
`number`	string	Yes	Phone number without country code
`page`	integer	No	Page number (default: 1)
`page_size`	integer	No	Results per page (default: 50, max: 100)
`gte`	string	No	Start date filter (ISO 8601 format)
`lte`	string	No	End date filter (ISO 8601 format)

Example Requests

Shell
Python

curl "https://api.vysion.ai/api/v2/leak/phone/1/5551234567" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key="YOUR_API_KEY")
result = c.get_leak_by_phone(
    country_code="1",
    number="5551234567"
)

for hit in result.hits:
    print(f"File: {hit.filePath}")
    print(f"Phones found: {hit.detectedInfo.get('phone_numbers', [])}")

Search Leaks by Username

Search for leaked data containing a username.

GET/api/v2/leak/username/{username}

Parameters

Name	Type	Required	Description
`username`	string	Yes	Username to search for
`page`	integer	No	Page number (default: 1)
`page_size`	integer	No	Results per page (default: 50, max: 100)
`gte`	string	No	Start date filter (ISO 8601 format)
`lte`	string	No	End date filter (ISO 8601 format)

Example Requests

Shell
Python

curl "https://api.vysion.ai/api/v2/leak/username/johndoe" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key="YOUR_API_KEY")
result = c.get_leak_by_username(
    username="johndoe"
)

for hit in result.hits:
    print(f"File: {hit.filePath}")
    print(f"Usernames found: {hit.detectedInfo.get('usernames', [])}")

Search Leaks by File Hash

Search for leaked files by hash (SHA256, SHA1, or MD5).

GET/api/v2/leak/hash/{hash}

The hash type is automatically detected based on length:

64 characters: SHA256
40 characters: SHA1
32 characters: MD5

Parameters

Name	Type	Required	Description
`hash`	string	Yes	File hash (SHA256, SHA1, or MD5)
`page`	integer	No	Page number (default: 1)
`page_size`	integer	No	Results per page (default: 50, max: 100)
`gte`	string	No	Start date filter (ISO 8601 format)
`lte`	string	No	End date filter (ISO 8601 format)

Example Requests

Shell
Python

curl "https://api.vysion.ai/api/v2/leak/hash/a3b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key="YOUR_API_KEY")
result = c.get_leak_by_hash(
    hash_value="a3b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
)

for hit in result.hits:
    print(f"File: {hit.filePath}")
    print(f"Hash: {hit.fileHash}")
    print(f"Size: {hit.fileSize} bytes")

Get Leak by ID

Retrieve a specific leak document by its ID, including a download link to the file.

GET/api/v2/leak/{id}

Download Behavior

Standalone files: Direct download link to the file
Archive members: Link to the compressed archive (not individual members)
Storage: Files stored in byronlabs-telegram-media S3 bucket
URL format: {channelId}/{YYYYMM}/{sha1sum}.{extension}

Parameters

Name	Type	Required	Description
`id`	string	Yes	Elasticsearch document ID of the leak
`search_highlight`	string	No	Optional keyword or phrase to search within that leak and return matching highlights

Example Requests

Shell
Python

curl "https://api.vysion.ai/api/v2/leak/abc123xyz" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

from vysion import client

c = client.Client(api_key="YOUR_API_KEY")
result = c.get_leak_by_id(leak_id="abc123xyz")

leak = result.hits[0]
print(f"File: {leak.filePath}")
if leak.downloadUrl:
    print(f"Download: {leak.downloadUrl}")

Response

{
  "data": {
    "total": 1,
    "hits": [
      {
        "id": "abc123xyz",
        "detectionDate": "2024-01-15T10:30:00Z",
        "filePath": "archive.zip/leaked_data.pdf",
        "fileHash": "a3b2c1d4e5f6...",
        "fileSize": 1024000,
        "fileType": "pdf",
        "detectedMimeType": "application/pdf",
        "decompressedFilename": "leaked_data.pdf",
        "archiveSource": "archive.zip",
        "archiveMemberPath": "leaked_data.pdf",
        "detectedInfo": {
          "emails": ["user@example.com"],
          "phone_numbers": ["+1234567890"],
          "usernames": ["johndoe"]
        },
        "telegram": {
          "telegram_id": "-1002104057089_108",
          "channelId": -1002104057089,
          "messageId": 108,
          "channelName": "Data Leaks",
          "channelUsername": "dataleaks"
        },
        "language": "en",
        "languages": [
          {
            "language": "en",
            "probability": 0.95
          }
        ],
        "parseStatus": "success",
        "downloadUrl": "https://byronlabs-telegram-media.s3.amazonaws.com/..."
      }
    ]
  },
  "error": null
}

LeakHit Schema

All leak endpoints return data using the LeakHit schema with camelCase field names.

Core Fields

Field	Type	Description
`id`	string	Unique leak identifier
`detectionDate`	string	ISO 8601 timestamp when leak was detected
`filePath`	string	Path to the leaked file
`fileHash`	string	File hash (SHA256, SHA1, or MD5)
`fileSize`	integer	File size in bytes
`fileType`	string	File extension/type
`detectedMimeType`	string	MIME type detected from file content

Archive Fields

Field	Type	Description
`decompressedFilename`	string	Original filename if extracted from archive
`archiveSource`	string	Parent archive filename
`archiveMemberPath`	string	Path within archive

Content Fields

Field	Type	Description
`language`	string	Primary language code (ISO 639-1)
`languages`	array	Detected languages with confidence scores
`parseStatus`	string	Parsing status (success, failed, etc.)

Detected Information

Field	Type	Description
`detectedInfo.emails`	array	Email addresses found
`detectedInfo.usernames`	array	Usernames found
`detectedInfo.phone_numbers`	array	Phone numbers found
`detectedInfo.ipv4_addresses`	array	IPv4 addresses found
`detectedInfo.ipv6_addresses`	array	IPv6 addresses found
`detectedInfo.bitcoin_addresses`	array	Bitcoin wallet addresses
`detectedInfo.ethereum_addresses`	array	Ethereum wallet addresses
`detectedInfo.monero_addresses`	array	Monero wallet addresses
`detectedInfo.ripple_addresses`	array	Ripple wallet addresses
`detectedInfo.zcash_addresses`	array	Zcash wallet addresses
`detectedInfo.polkadot_addresses`	array	Polkadot wallet addresses
`detectedInfo.binance_addresses`	array	Binance Coin wallet addresses
`detectedInfo.dash_addresses`	array	Dash wallet addresses
`detectedInfo.hashes`	array	File hashes found in content

Telegram Fields

Field	Type	Description
`telegram.telegram_id`	string	Telegram message identifier
`telegram.channelId`	integer	Telegram channel ID
`telegram.messageId`	integer	Telegram message ID
`telegram.channelName`	string	Telegram channel name
`telegram.channelUsername`	string	Telegram channel username

Additional Fields

Field	Type	Description
`downloadUrl`	string	Presigned S3 URL for download (only in `/leak/{id}` endpoint)
`highlight`	object	Highlighted search matches (only in `/leak/search` endpoint)

Language Object

{
  "language": "en",
  "probability": 0.95
}

Field	Type	Description
`language`	string	ISO 639-1 language code
`probability`	number	Confidence score (0-1)

Best Practices

Date Filtering

Use ISO 8601 format for date filters:

result = c.get_leak_by_email(
    email="user@example.com",
    gte="2024-01-01T00:00:00Z",
    lte="2024-12-31T23:59:59Z"
)

Pagination

Process large result sets efficiently:

page = 1
page_size = 100

while True:
    result = c.search_leaks(
        q="password",
        page=page,
        page_size=page_size
    )

    if not result.hits:
        break

    for hit in result.hits:
        process_leak(hit)

    if len(result.hits) < page_size:
        break

    page += 1

Working with Highlights

Extract highlighted content from search results:

def extract_highlights(leak_hit):
    if not leak_hit.highlight:
        return []

    snippets = []
    for field, values in leak_hit.highlight.items():
        for value in values:
            # Remove <mark> tags if needed
            clean_value = value.replace('<mark>', '').replace('</mark>', '')
            snippets.append({
                'field': field,
                'snippet': value,
                'clean': clean_value
            })

    return snippets

Handling Download URLs

Always check if download URL is available:

leak = c.get_leak_by_id(leak_id="abc123").hits[0]

if leak.downloadUrl:
    # Download the file
    import requests
    response = requests.get(leak.downloadUrl)

    with open(leak.decompressedFilename or "download.bin", "wb") as f:
        f.write(response.content)
else:
    print(f"No download available for {leak.filePath}")

Rate Limiting

All leak endpoints are subject to the standard Vysion API rate limits. See the Rate Limiting guide for details.

Error Handling

Leak endpoints return standard Vysion error responses. Common errors include:

Status Code	Error	Description
400	Bad Request	Invalid parameters (e.g., invalid email format, unsupported chain)
401	Unauthorized	Missing or invalid API key
404	Not Found	Leak ID not found (only for `/leak/{id}`)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error

See the Error Codes reference for complete error documentation.