Documents API

Vysion integrates multiple threat intelligence sources, accessible via the document endpoints, enabling comprehensive search capabilities across various networks and data types.

Search for Documents

Search through the Vysion database using keyword queries with support for advanced operators.

GET/api/v2/document/search

Query Operators

The search supports “Google Dork” style syntax with the following operators:

• + signifies AND operation
• | signifies OR operation
• - negates a single token
• " wraps tokens to signify a phrase search
• * at the end of a term signifies a prefix query
• () signify precedence
• ~N after a word signifies edit distance (fuzziness)
• ~N after a phrase signifies slop amount

Parameters

Name	Type	Required	Description
q	string	Yes	Search query string
gte	string	No	Date filter (≥). Formats: Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss
lte	string	No	Date filter (≤). Formats: Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss
page	integer	No	Page number for pagination
page_size	integer	No	Results per page (default: 10)
network	string	No	Filter by network: tor, i2p, or clearnet
language	string	No	Filter by language code
include_tag	string	No	Include documents with specific tag
exclude_tag	string	No	Exclude documents with specific tag
safe_search	bool	No	Exclude documents with pornography tag (Default: False)

Example Requests

Shell

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

Python

from vysion import client

c = client.Client(api_key="YOUR_API_KEY")
result = c.search("contileaks")

for hit in result.hits:
    print(hit)

---

Get Document by ID

Retrieve a specific document by its unique identifier.

GET/api/v2/document/{id}

Parameters

Name	Type	Required	Description
id	string	Yes	Document ID

Example Requests

Shell

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

Python

from vysion import client

c = client.Client(api_key="YOUR_API_KEY")
result = c.get_document("62bdc0968e4892b70411895c")
print(result)

Note

Documents return an HTML chunk. For the complete HTML content, use the Document HTML API.

---

Get Document by URL

Fetch documents from the Vysion database based on their URLs. Returns multiple captures if available.

GET/api/v2/document/url/{url}

Parameters

Name	Type	Required	Description
url	string	Yes	URL to search for (URL-encoded)
gte	string	No	Formats: Unix Timestamp, YYYYY-MM-DD or YYYYY-MM-DDThh:mm:ss
lte	string	No	Formats: Unix Timestamp, YYYYY-MM-DD or YYYYY-MM-DDThh:mm:ss
page	integer	No	Page number
page_size	integer	No	Results per page (default: 10)

Example Requests

Shell

# URL must be URL-encoded
curl "https://api.vysion.ai/api/v2/document/url/example.onion%2Fpage?page=1" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

Python

from vysion import client

c = client.Client(api_key="YOUR_API_KEY")
result = c.find_url("example.onion/page")

for hit in result.hits:
    print(hit)

---

Get Documents by Tag

Search for documents that contain specific tags.

GET/api/v2/document/tag/{tag}

Parameters

Name	Type	Required	Description
tag	string	Yes	Tag to search for
gte	string	No	Formats: Unix Timestamp, YYYYY-MM-DD or YYYYY-MM-DDThh:mm:ss
lte	string	No	Formats: Unix Timestamp, YYYYY-MM-DD or YYYYY-MM-DDThh:mm:ss
page	integer	No	Page number
page_size	integer	No	Results per page (default: 10)

Tag examples

Namespace	Predicate	Value
dark-web	topic	credit-card
dark-web	topic	drugs-narcotics
dark-web	topic	electronics
dark-web	topic	escrow
dark-web	topic	finance
dark-web	topic	finance-crypto
dark-web	topic	gambling
dark-web	topic	hacking
dark-web	topic	identification-credentials
dark-web	topic	intellectual-property-copyright-materials
dark-web	topic	mixer
dark-web	topic	pornography-adult
dark-web	topic	pornography-child-exploitation
dark-web	topic	pornography-illicit-or-illegal
dark-web	topic	search-engine-index
dark-web	topic	softwares
dark-web	topic	weapons
dark-web	topic	ransomware-group

Example Requests

Shell

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

Python

from vysion import client

c = client.Client(api_key="YOUR_API_KEY")
result = c.get_tag("escrow")

for hit in result.hits:
    print(hit)

---

Get Documents by Wallet Address

Search for documents containing specific cryptocurrency wallet addresses. Supports BTC, BNB, DOT, DASH, ETH, XMR, XRP and ZEC.

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

Parameters

Name	Type	Required	Description
chain	string	Yes	Before conducting a search, it is necessary to specify the blockchain type to search within.
address	string	Yes	Wallet address to search for.
gte	string	No	Formats: Unix Timestamp, YYYYY-MM-DD or YYYYY-MM-DDThh:mm:ss
lte	string	No	Formats: Unix Timestamp, YYYYY-MM-DD or YYYYY-MM-DDThh:mm:ss
page	integer	No	Page number
page_size	integer	No	Results per page (default: 10)

Example Requests

Shell

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

Python

from vysion import client

c = client.Client(api_key="YOUR_API_KEY")
result = c.find_wallet("BTC", "1F1tAaz5x1HUXrCNLbtMDqcw6o5GNn4xqX")

for hit in result.hits:
    print(hit)

---

Get Documents by Email

Search for documents containing specific email addresses.

GET/api/v2/document/email/{email}

Parameters

Name	Type	Required	Description
email	string	Yes	Email address to search for
gte	string	No	Formats: Unix Timestamp, YYYYY-MM-DD or YYYYY-MM-DDThh:mm:ss
lte	string	No	Formats: Unix Timestamp, YYYYY-MM-DD or YYYYY-MM-DDThh:mm:ss
page	integer	No	Page number
page_size	integer	No	Results per page (default: 10)

Example Requests

Shell

curl "https://api.vysion.ai/api/v2/document/email/someone@gmail.com" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

Python

from vysion import client

c = client.Client(api_key="YOUR_API_KEY")
result = c.find_email("someone@gmail.com")

for hit in result.hits:
    print(hit)

---

Get Documents by Phone Number

Search for documents containing specific phone numbers.

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

Parameters

Name	Type	Required	Description
country_code	string	Yes	Phone prefix to search for
number	string	Yes	Phone number to search for
gte	string	No	Formats: Unix Timestamp, YYYYY-MM-DD or YYYYY-MM-DDThh:mm:ss
lte	string	No	Formats: Unix Timestamp, YYYYY-MM-DD or YYYYY-MM-DDThh:mm:ss
page	integer	No	Page number
page_size	integer	No	Results per page (default: 10)

Example Requests

Shell

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

Python

from vysion import client

c = client.Client(api_key="YOUR_API_KEY")
result = c.find_phone("1", "123456789")

for hit in result.hits:
    print(hit)

Response example

{
  "data": {
    "total": 1,
    "hits": [
      {
        "page": {
          "id": "123456789101112131415161",
          "url": {
            "url": "site.onion/content/darknet",
            "networkProtocol": "http",
            "domainName": "site.onion",
            "port": 80,
            "path": "/content/darknet",
            "signature": "11111111-2222-3333-4444-555555555555",
            "network": "tor"
          },
          "foundAt": "666666-7777-8888-9999-101010101010",
          "pageTitle": "Сайты даркнет",
          "language": "ru",
          "html": "",
          "text": null,
          "sha1sum": "05dc1502645113cb2173ff35c86db5618b9e8b0c",
          "sha256sum": "d030e1b02d71e2d056000331ec444382ca4f0f3a83a1ce8fe85726f0c0d4326b",
          "ssdeep": null,
          "detectionDate": "2024-12-10T09:49:40",
          "ingestionDate": "2024-12-11T03:14:22",
          "screenshot": null,
          "chunk": true,
          "htmlOversize": false,
          "docType": "text/html"
        },
        "tag": [],
        "email": [],
        "paste": [],
        "skype": [],
        "telegram": [
          {
            "value": "https://t.me/someone"
          },
          {
            "value": "http://t.me/omebody"
          }
        ],
        "whatsapp": [],
        "bitcoin_address": [],
        "polkadot_address": [],
        "ethereum_address": [],
        "monero_address": [],
        "ripple_address": [],
        "zcash_address": []
      }
    ]
  }
}

Response Status Codes

Status	Meaning	Description
200	OK	Successful response
401	Unauthorized	Invalid or missing API key
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded

Tip

Use filters like network and language to narrow down your search results for better performance and relevance.