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)

curl "https://api.vysion.ai/api/v2/document/search?q=contileaks&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("contileaks")

for hit in result.hits:
    print(hit)

Response

{
  "data": {
    "total": 150,
    "hits": [
      {
        "page": {
          "id": "62bdc0968e4892b70411895c",
          "url": {
            "url": "http://example.onion/page",
            "networkProtocol": "http",
            "domainName": "example.onion",
            "port": 80,
            "path": "/page",
            "signature": "88fef6f3-fdb6-486d-87e1-c7ae0750df94",
            "network": "tor"
          },
          "foundAt": "2022-06-30T10:15:30Z",
          "pageTitle": "Sample Page",
          "language": "en",
          "html": "<html>...</html>",
          "text": "Sample page content...",
          "sha1sum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
          "sha256sum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
          "ssdeep": "3:a+JrJL:aJrJL",
          "detectionDate": "2022-06-30T10:15:30Z",
          "chunk": false
        },
        "tag": [
          {
            "namespace": "misp",
            "predicate": "threat-actor",
            "value": "conti"
          }
        ],
        "email": [
          {
            "value": "contact@example.com"
          }
        ],
        "bitcoin_address": [
          {
            "value": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2"
          }
        ]
      }
    ]
  },
  "error": null
}

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
Python

curl "https://api.vysion.ai/api/v2/document/62bdc0968e4892b70411895c" \
  --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_document("62bdc0968e4892b70411895c")
print(result)

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	Date filter (≥)
`lte`	string	No	Date filter (≤)
`page`	integer	No	Page number
`page_size`	integer	No	Results per page (default: 10)

Example Requests

Shell
Python

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

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	Date filter (≥)
`lte`	string	No	Date filter (≤)
`page`	integer	No	Page number
`page_size`	integer	No	Results per page (default: 10)

Get Documents by Wallet Address

Search for documents containing specific cryptocurrency wallet addresses.

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

Parameters

Name	Type	Required	Description
`wallet`	string	Yes	Wallet address to search for
`gte`	string	No	Date filter (≥)
`lte`	string	No	Date filter (≤)
`page`	integer	No	Page number
`page_size`	integer	No	Results per page (default: 10)

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	Date filter (≥)
`lte`	string	No	Date filter (≤)
`page`	integer	No	Page number
`page_size`	integer	No	Results per page (default: 10)

Get Documents by Phone Number

Search for documents containing specific phone numbers.

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

Parameters

Name	Type	Required	Description
`phone`	string	Yes	Phone number to search for
`gte`	string	No	Date filter (≥)
`lte`	string	No	Date filter (≤)
`page`	integer	No	Page number
`page_size`	integer	No	Results per page (default: 10)

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