Scanii Getting Started: API Integration Guide (2026)

Getting started overview

Integrating Scanii into an application involves a series of steps designed to enable real-time content scanning for malware and other threats. The process begins with setting up a Scanii account to obtain necessary API credentials. Following account setup, developers can make their first API call, typically a file scan, to confirm successful integration. Scanii provides a comprehensive documentation portal and official SDKs to streamline this process across various programming languages.

This guide outlines the essential steps to get started, focusing on core actions: account registration, securing API keys, and executing an initial API request. This foundation allows developers to quickly move towards implementing more advanced features, such as integrating Scanii into existing upload workflows or content moderation pipelines.

Here’s a quick-reference table for the Scanii getting started process:

Create an account and get keys

To begin using Scanii, an account must first be established. Scanii offers a Developer Plan that includes 5,000 scans per month free of charge, suitable for testing and low-volume applications. Registration is typically completed via the Scanii website, requiring an email address and password.

1. Navigate to the Scanii website: Visit the Scanii pricing page.
2. Select a plan: Choose the 'Developer Plan' to start with the free tier, or select a paid plan based on anticipated usage.
3. Complete registration: Follow the prompts to create your account. This usually involves providing an email, setting a password, and agreeing to terms of service.
4. Access API Keys: Once logged in, your Scanii dashboard or account settings will contain your unique API Key and API Secret. These credentials are required for authenticating all API requests. The Scanii API Reference on authentication provides details on locating these keys.

Security Note: Your API Secret should be treated as sensitive information, similar to a password. It should not be hardcoded directly into client-side code, exposed in public repositories, or transmitted insecurely. Best practices for API key management, such as using environment variables or a secure configuration management system, should be followed to prevent unauthorized access to your Scanii account and services. For comprehensive guidance on securing API keys, consult resources like the Google Cloud API key best practices documentation.

Your first request

With an account created and API keys retrieved, the next step is to make a file scan request. Scanii's API is RESTful, supporting standard HTTP methods. Requests can be made directly using tools like curl, or via one of Scanii's official SDKs, which abstract away the HTTP request details.

Using an SDK (Python example)

Scanii provides SDKs for several languages including Python, Ruby, Java, Node.js, PHP, and Go. Using an SDK simplifies authentication and request body construction.

First, install the Python SDK:

pip install scanii-sdk

Then, use the following Python code to scan a local file:

from scanii import ScaniiClient
import os

# Replace with your actual API Key and Secret
api_key = os.environ.get("SCANNII_API_KEY")
api_secret = os.environ.get("SCANNII_API_SECRET")

if not api_key or not api_secret:
    raise ValueError("SCANNII_API_KEY and SCANNII_API_SECRET environment variables must be set.")

client = ScaniiClient(api_key, api_secret)

# Path to the file you want to scan
file_path = "./test_file.txt"

# Create a dummy file for demonstration
with open(file_path, "w") as f:
    f.write("This is a test file for Scanii scan.")

print(f"Scanning file: {file_path}")

try:
    # Scan the file
    result = client.scan_file(file_path)

    print("Scan Result:")
    print(f"  Id: {result.resource_id}")
    print(f"  MD5: {result.checksums.get('md5')}")
    print(f"  SHA1: {result.checksums.get('sha1')}")
    print(f"  SHA256: {result.checksums.get('sha256')}")
    print(f"  Content Type: {result.content_type}")
    print(f"  Findings: {result.findings}")
    print(f"  Blocked: {result.is_blocked}")

    if result.is_blocked:
        print("  Status: BLOCKED - Content contains threats or violates policies.")
    elif result.findings:
        print("  Status: THREATS DETECTED - Review findings.")
    else:
        print("  Status: CLEAN - No threats detected.")

except Exception as e:
    print(f"An error occurred during scan: {e}")
finally:
    # Clean up the dummy file
    if os.path.exists(file_path):
        os.remove(file_path)

Ensure that SCANNII_API_KEY and SCANNII_API_SECRET environment variables are set before running this script.

Using cURL (Direct HTTP Request)

For direct HTTP requests, you use HTTP Basic Authentication with your API Key as the username and API Secret as the password. The file content is sent as a multipart/form-data request.

First, create a dummy file:

echo "This is a test file contents." > test_file_curl.txt

Then, execute the cURL command:

curl -X POST \
  -u "YOUR_API_KEY:YOUR_API_SECRET" \
  -F "file=@./test_file_curl.txt" \
  https://api.scanii.com/v2.1/files

Replace YOUR_API_KEY and YOUR_API_SECRET with your actual credentials. The response will be a JSON object containing scan results, as described in the Scanii API Responses documentation.

Common next steps

After successfully completing your first scan, consider these common next steps to further integrate and optimize your Scanii usage:

1. Integrate into your application's upload flow: Modify your application to send user-uploaded files to Scanii immediately upon upload. This allows for real-time threat detection before content is processed or stored.
2. Implement asynchronous scanning with webhooks: For larger files or environments where immediate synchronous responses are not critical, configure Scanii webhooks. This allows Scanii to notify your application of scan results when they are ready, reducing latency in your primary request-response cycle.
3. Handle scan results: Develop logic within your application to interpret and act on Scanii's scan results. This might include quarantining infected files, blocking uploads, notifying administrators, or logging events.
4. Explore advanced features: Review the Scanii API Reference for features like content moderation, metadata scanning, and file submission via URL.
5. Monitor usage: Utilize the Scanii dashboard to monitor your scan volume and review API usage, ensuring you stay within your plan limits or scale up as needed.
6. Error handling: Implement robust error handling for API calls, including network issues, authentication failures, and rate limiting. The Scanii error handling guide provides more information.

Troubleshooting the first call

Encountering issues during the initial API call is common. Here are some troubleshooting steps:

• Check API Keys: Verify that the API Key and Secret used in your request exactly match those from your Scanii account. Authentication errors (HTTP 401 Unauthorized) are frequently caused by incorrect credentials. Ensure no leading or trailing spaces are present.
• Authentication Method: Confirm you are using HTTP Basic Authentication correctly. The API Key is the username, and the API Secret is the password. SDKs typically handle this automatically.
• Endpoint URL: Ensure the API endpoint URL is correct (e.g., https://api.scanii.com/v2.1/files). Refer to the Scanii API Reference for specific endpoint details.
• Network Connectivity: Confirm that your environment has outbound network access to api.scanii.com on port 443. Firewall rules or proxy settings can sometimes block these connections.
• Request Body Format: For file uploads, ensure the request body is correctly formatted as multipart/form-data, with the file attached to the appropriate field (e.g., file=@path/to/file in cURL). Malformed requests can lead to HTTP 400 Bad Request errors.
• SDK Specific Issues: If using an SDK, ensure it is installed correctly and updated to the latest version. Consult the specific Scanii SDK documentation for any language-specific requirements or common issues.
• Scanii Documentation and Support: Review the Scanii troubleshooting guide for common problems and solutions. If issues persist, Scanii's support channels can provide further assistance.
• Content Type Headers: While Scanii often detects content types automatically, explicitly setting the Content-Type header for your file can sometimes resolve issues, especially for unusual file types.