linkshieldai 0.3.0

Python SDK for the LinkShieldAI URL safety API.

LinkShieldAI Python SDK

New integrations should use client.scan(url, mode="standard"), which calls Bearer-authenticated POST /v1/scan. Existing methods remain for compatibility.

from linkshieldai import LinkShieldAI
client = LinkShieldAI()  # Reads LINKSHIELDAI_API_KEY.
result = client.scan("https://example.com", mode="standard")
print(result.verdict, result.request_id, result.reason_codes)

UNKNOWN means the API found no decisive signal. Do not treat it as SAFE.

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

pip install linkshieldai

Authentication

Every SDK request sends the key as an Authorization: Bearer header. Legacy endpoints receive only the URL as a query parameter.

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/?url={url}
Authorization: Bearer {key}

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?url={url}
Authorization: Bearer {key}

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}
Authorization: Bearer {key}

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?url={url}
Authorization: Bearer {key}

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

Chimera Check

Wraps:

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

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 scan https://example.com --mode standard
linkshieldai --api-key YOUR_API_KEY scan https://example.com --mode detailed
linkshieldai --api-key YOUR_API_KEY scan https://example.com --mode deep
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.