← 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
)

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
)

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

Step 1: Validate the binary

import requests

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

# Read your PE file
with open("sample.exe", "rb") as f:
    file_content = f.read()

# Submit for validation
response = requests.post(
    "https://genuscodes.com/submit/binary",
    files={"file": ("sample.exe", file_content)},
    headers=headers
)

data = response.json()

if data.get("status") == "duplicate":
    print(f"Binary already exists: {data['results_url']}")
else:
    job_id = data["job_id"]
    upload_url = data["upload_url"]
    print(f"Validated! Job ID: {job_id}")

Step 2: Upload to S3 via presigned URL

# Upload the file using the presigned URL
upload_resp = requests.put(
    upload_url,
    data=file_content,
    headers={"Content-Type": "application/octet-stream"}
)

if upload_resp.status_code == 200:
    print("Upload successful")

Step 3: Confirm the upload

# Tell the server to process the uploaded file
response = requests.post(
    "https://genuscodes.com/submit/confirm-upload",
    json={"job_id": job_id},
    headers=headers
)

data = response.json()
print(f"Status: {data['status']}")
print(f"Results will be at: {data['results_url']}")

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
)

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']}")

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

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
)

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
)

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",
    "rabbitmq": "connected",
    "cache_api": "connected",
    "active_jobs": 3
}

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}")