← Home

API Documentation

Python examples for interacting with the Genus Codes API

Authentication

All API endpoints require authentication via a Bearer token. Generate a token from your Account page.

import requests

API_TOKEN = "gc_your_token_here"
headers = {"Authorization": f"Bearer {API_TOKEN}"}

# Use headers with every request
response = requests.post(
    "https://genuscodes.com/search/function",
    json={"function_hash": "..."},
    headers=headers
)

1. Search for a Function

Request

import requests

API_TOKEN = "gc_your_token_here"
headers = {"Authorization": f"Bearer {API_TOKEN}"}

# Function hash (UUID5 format)
function_hash = "e935d66e-4777-579f-9278-e4c6d955b79b"

response = requests.post(
    "https://genuscodes.com/search/function",
    json={
        "function_hash": function_hash,
        "limit": 100  # Optional: max results
    },
    headers=headers
)

response.raise_for_status()
data = response.json()
print(f"Found in {data.get('total_binaries', 0)} binaries")

Response

{
    "function_hash": "e935d66e-4777-579f-9278-e4c6d955b79b",
    "total_binaries": 52,
    "binaries": [
        {"sha256": "abc123...", "malicious": true, "source": "VirusShare_00001"},
        {"sha256": "def456...", "malicious": false, "source": "Win10"}
    ],
    "from_cache": true
}

2. Search for a Binary

Request

import requests

API_TOKEN = "gc_your_token_here"
headers = {"Authorization": f"Bearer {API_TOKEN}"}

sha256 = "b99d61d874728edc0918ca0eb10eab93d381e7367e377406e65963366c874450"

response = requests.post(
    "https://genuscodes.com/search/binary",
    json={
        "hash_value": sha256,
        "hash_type": "sha256"
    },
    headers=headers
)

response.raise_for_status()
data = response.json()

# If processing, poll for results
if data.get("status") == "processing":
    job_id = data["job_id"]
    print(f"Job submitted: {job_id}")
    # Poll /job/{job_id} for completion

3. Submit a Binary for Analysis

Parameters (multipart form)

• file (required) — binary file, zip, or 7z archive
• password (optional) — archive password. If not provided, "infected" is tried automatically.

Submit a raw binary

import requests

API_TOKEN = "gc_your_token_here"
headers = {"Authorization": f"Bearer {API_TOKEN}"}

with open("sample.exe", "rb") as f:
    response = requests.post(
        "https://genuscodes.com/submit/binary",
        files={"file": ("sample.exe", f)},
        headers=headers
    )

if not response.ok:
    print(f"Error: {response.status_code} - {response.text}")
else:
    data = response.json()
    if data["status"] == "duplicate":
        print(f"Already exists: {data['results_url']}")
    elif data["status"] == "submitted":
        print(f"Submitted! SHA256: {data['sha256']}")
        print(f"Results: {data['results_url']}")

Submit an encrypted zip/7z

# Default password "infected" is tried automatically
with open("malware.zip", "rb") as f:
    response = requests.post(
        "https://genuscodes.com/submit/binary",
        files={"file": ("malware.zip", f)},
        headers=headers
    )

# With a custom password
with open("malware.7z", "rb") as f:
    response = requests.post(
        "https://genuscodes.com/submit/binary",
        files={"file": ("malware.7z", f)},
        data={"password": "mypassword"},
        headers=headers
    )

Response (submitted)

{
    "status": "submitted",
    "job_id": "a1b2c3d4-...",
    "sha256": "b99d61d874728edc...",
    "results_url": "/results/b99d61d874728edc..."
}

Response (password required)

{
    "status": "password_required",
    "message": "Archive is encrypted. Provide a password."
}

4. Check Job Status

Request

import requests
import time

API_TOKEN = "gc_your_token_here"
headers = {"Authorization": f"Bearer {API_TOKEN}"}

job_id = "your-job-id-here"

# Poll until complete
while True:
    response = requests.get(f"https://genuscodes.com/job/{job_id}", headers=headers)
    data = response.json()

    status = data.get("status")
    print(f"Status: {status}")

    if status in ["completed", "failed"]:
        break

    time.sleep(5)  # Wait 5 seconds between polls

print(f"Result: {data}")

5. Get Binary Analysis Results

This endpoint returns an HTML page. For programmatic access, use:

Request

import requests

API_TOKEN = "gc_your_token_here"
headers = {"Authorization": f"Bearer {API_TOKEN}"}

sha256 = "b99d61d874728edc0918ca0eb10eab93d381e7367e377406e65963366c874450"

response = requests.get(
    f"https://genuscodes.com/api/binary/{sha256}/results",
    headers=headers
)

response.raise_for_status()
data = response.json()

print(f"Total functions: {data['summary']['total_functions']}")
print(f"Unique functions: {data['summary']['unique_functions']}")
print(f"Malicious matches: {data['summary']['functions_with_malicious_matches']}")

# Global tags (admin-curated labels, e.g. malware family names)
print(f"Global tags: {data['binary'].get('global_tags', [])}")

# Binary similarity
similarity = data.get("similarity", {})
for threshold, info in similarity.get("thresholds", {}).items():
    print(f"{threshold}: {info['count']} similar binaries")

6. Check Usage & Quota

Request

import requests

API_TOKEN = "gc_your_token_here"
headers = {"Authorization": f"Bearer {API_TOKEN}"}

response = requests.get(
    "https://genuscodes.com/billing/usage",
    headers=headers
)

response.raise_for_status()
data = response.json()
print(f"Plan: {data['plan']}")
print(f"Binary ops: {data['binary_ops']} / {data['binary_limit']} ({data['binary_remaining']} remaining)")
print(f"Function ops: {data['function_ops']} / {data['function_limit']} ({data['function_remaining']} remaining)")

Response

{
    "plan": "free",
    "binary_ops": 12,
    "binary_limit": 50,
    "binary_remaining": 38,
    "function_ops": 1500,
    "function_limit": 36000,
    "function_remaining": 34500,
    "is_lifetime": true,
    "status": "active"
}

7. Track Fetch Progress

Request

import requests

API_TOKEN = "gc_your_token_here"
headers = {"Authorization": f"Bearer {API_TOKEN}"}

sha256 = "b99d61d874728edc0918ca0eb10eab93d381e7367e377406e65963366c874450"

response = requests.get(
    f"https://genuscodes.com/api/binary/{sha256}/progress",
    headers=headers
)

response.raise_for_status()
data = response.json()
print(f"Progress: {data['fetched']} / {data['total']}")

Response

{
    "fetched": 150,
    "total": 500
}

8. Refresh Binary Cache

Request

import requests

API_TOKEN = "gc_your_token_here"
headers = {"Authorization": f"Bearer {API_TOKEN}"}

sha256 = "b99d61d874728edc0918ca0eb10eab93d381e7367e377406e65963366c874450"

response = requests.post(
    f"https://genuscodes.com/api/binary/{sha256}/refresh-cache",
    headers=headers
)

response.raise_for_status()
data = response.json()
print(f"Status: {data['status']}")

Response (success)

{
    "status": "refreshed",
    "message": "Binary analysis has been refreshed"
}

Response (cooldown)

{
    "status": "too_recent",
    "message": "Binary was analyzed recently. Please wait before refreshing."
}

9. Health Check

Request

import requests

response = requests.get("https://genuscodes.com/health")
data = response.json()
print(f"Status: {data['status']}")

Response

{
    "status": "healthy"
}

10. Research — Search by Tag or Filename

Query Parameters

• type — global_tag, user_tag, or filename
• q — Search query (min 2 chars for tags, min 3 for filename)

Search by Global Tag

import requests

response = requests.get(
    "https://genuscodes.com/research",
    params={"type": "global_tag", "q": "mirai"},
    headers={"Authorization": "Bearer gc_YOUR_TOKEN"}
)

Search by Filename

response = requests.get(
    "https://genuscodes.com/research",
    params={"type": "filename", "q": "calc.exe"},
    headers={"Authorization": "Bearer gc_YOUR_TOKEN"}
)

Search by User Tag

response = requests.get(
    "https://genuscodes.com/research",
    params={"type": "user_tag", "q": "lockbit"},
    headers={"Authorization": "Bearer gc_YOUR_TOKEN"}
)

11. Function Tags

Get Global Function Tags (Batch)

import requests

API_TOKEN = "gc_your_token_here"
headers = {"Authorization": f"Bearer {API_TOKEN}", "Content-Type": "application/json"}

response = requests.post(
    "https://genuscodes.com/api/function-tags-batch",
    json={"func_hashes": [
        "ad57bfc0-33e4-502e-adf1-ee76738aa0c7",
        "ffa8519c-d90c-506c-8986-20ad012fccc8"
    ]},
    headers=headers
)

response.raise_for_status()
data = response.json()
for func_hash, tags in data["tags"].items():
    print(f"{func_hash}: {tags}")

Response

{
    "tags": {
        "ad57bfc0-33e4-502e-adf1-ee76738aa0c7": ["crypto_aes", "c2_beacon"],
        "ffa8519c-d90c-506c-8986-20ad012fccc8": ["packer_upx"]
    }
}

Update User Function Tags

func_hash = "ad57bfc0-33e4-502e-adf1-ee76738aa0c7"

response = requests.post(
    f"https://genuscodes.com/api/function/{func_hash}/tags",
    json={"tags": ["my_label", "suspicious"]},
    headers=headers
)

Response

{
    "status": "ok",
    "tags": ["my_label", "suspicious"]
}

Error Handling

The API returns standard HTTP status codes:

• 200 - Success
• 400 - Bad request (invalid parameters)
• 401 - Authentication required (missing or invalid token)
• 403 - Forbidden (email not verified)
• 404 - Not found
• 413 - File too large (max 100MB)
• 422 - Validation error (malformed request body)
• 429 - Rate limited
• 500 - Server error
• 503 - Service unavailable

try:
    response = requests.post(...)
    response.raise_for_status()  # Raise exception for 4xx/5xx
    data = response.json()
except requests.exceptions.HTTPError as e:
    print(f"HTTP Error: {e.response.status_code}")
    print(f"Details: {e.response.text}")