linkshieldai 0.2.1

Python SDK for the LinkShieldAI URL safety API.

LinkShieldAI Python SDK

Python wrapper for the LinkShieldAI API at https://api.linkshieldai.com.

The SDK supports:

• Basic URL safety checks
• Detailed checks with screenshot URL and detected tag
• Screenshot download
• NSFW site checks
• Chimera AI classification
• Sync and async clients
• Retry/backoff for transient API failures
• A small command-line tool

Install

From this folder:

python -m pip install -e .

For tests:

python -m pip install -e ".[dev]"
python -m pytest

Authentication

The API uses a query parameter named key.

Pass the API key directly:

from linkshieldai import LinkShieldAI

client = LinkShieldAI(api_key="YOUR_API_KEY")

Or set an environment variable:

$env:LINKSHIELDAI_API_KEY = "YOUR_API_KEY"

from linkshieldai import LinkShieldAI

client = LinkShieldAI()

Basic Check

Wraps:

GET https://api.linkshieldai.com/?key={key}&url={url}

from linkshieldai import LinkShieldAI

client = LinkShieldAI(api_key="YOUR_API_KEY")
result = client.basic_check("https://example.com")

print(result.result)
print(result.is_malicious)
print(result.raw)

Detailed Check

Wraps:

GET https://api.linkshieldai.com/classify_link?key={key}&url={url}

result = client.detailed_check("https://example.com")

print(result.result)
print(result.screenshot_url)
print(result.tag)

The API field "screenshot url" is normalized to screenshot_url.

Download Screenshot

Wraps:

GET https://api.linkshieldai.com/screenshot/{file_name}

image_bytes = client.get_screenshot("05046f.png")
client.get_screenshot("https://api.linkshieldai.com/screenshot/05046f.png", "site.png")

NSFW Check

Wraps:

GET https://api.linkshieldai.com/nsfw/site?key={key}&url={url}

result = client.nsfw_check("https://example.com")
print(result.is_nsfw)

Chimera Check

Wraps:

GET https://api.linkshieldai.com/chimera?key={key}&url={url}

result = client.chimera("https://google.com")

print(result.result)
print(result.probability)
print(result.detection_method)
print(result.matched_signatures)

Async Usage

import asyncio
from linkshieldai import AsyncLinkShieldAI


async def main():
    async with AsyncLinkShieldAI(api_key="YOUR_API_KEY") as client:
        result = await client.chimera("https://google.com")
        print(result.result, result.probability)


asyncio.run(main())

Custom API Host

The default host is:

https://api.linkshieldai.com

You can override it for staging or testing:

client = LinkShieldAI(base_url="https://api.linkshieldai.com")

Timeouts, Retries, and Logging

By default the SDK uses:

• timeout=10.0
• max_retries=2
• backoff_factor=0.5

Retries are applied to temporary connection failures and HTTP 429, 502, 503, and 504.

import logging
from linkshieldai import LinkShieldAI

logging.basicConfig(level=logging.DEBUG)

client = LinkShieldAI(
    timeout=15.0,
    max_retries=3,
    backoff_factor=1.0,
)

CLI

After installation, use:

linkshieldai --api-key YOUR_API_KEY basic https://example.com
linkshieldai --api-key YOUR_API_KEY detailed https://example.com
linkshieldai --api-key YOUR_API_KEY nsfw https://example.com
linkshieldai --api-key YOUR_API_KEY chimera https://google.com
linkshieldai --api-key YOUR_API_KEY screenshot 05046f.png --output site.png

You can omit --api-key if LINKSHIELDAI_API_KEY is set.

Errors

from linkshieldai import (
    APIConnectionError,
    APIResponseError,
    APIStatusError,
    AuthenticationError,
    RateLimitError,
)

• AuthenticationError: missing API key.
• RateLimitError: HTTP 429.
• APIStatusError: non-success HTTP status.
• APIResponseError: malformed JSON or API payload with Error / error.
• APIConnectionError: timeout, DNS, or connection failure.

Raw API payloads are preserved on result objects through .raw.

Production Notes

• Keep API keys server-side. Do not expose them in browser JavaScript.
• Use max_retries with a small non-zero value for bots, moderation pipelines, and web apps.
• Catch RateLimitError when running near the documented limits.
• Tests are mocked by default and do not call the live API.
• For live smoke tests, set LINKSHIELDAI_API_KEY and run python -m pytest tests/test_live_optional.py.