Overview

The S4E Python SDK provides a fully typed client for every endpoint in the S4E REST API. It handles authentication, pagination, retries, and error mapping so you can interact with the platform from any Python application or script with minimal boilerplate.

Installation

Install the SDK from PyPI:

pip install s4e-sdk

Note

Python 3.9 or later is required. The SDK has no compiled dependencies and works on Linux, macOS, and Windows.

Quick Start

from s4e import S4EClient

client = S4EClient(api_key="YOUR_API_KEY")

# List all assets in your workspace
assets = client.assets.list()
for asset in assets:
    print(asset.domain, asset.security_score)

# Trigger a scan on a specific asset
scan = client.scans.create(asset_id="ast_01h8x...", scan_type="full")
print(f"Scan {scan.id} started - status: {scan.status}")

Client Configuration

The S4EClient constructor accepts several optional parameters that control how the SDK communicates with the API:

Parameter	Default	Description
`api_key`	-	Your API key (required).
`base_url`	`https://api.s4e.io/v1`	Base URL of the S4E API.
`timeout`	`30`	Request timeout in seconds.
`retries`	`3`	Number of automatic retries on transient errors.
`proxy`	`None`	HTTP/HTTPS proxy URL.

client = S4EClient(
    api_key="YOUR_API_KEY",
    base_url="https://on-prem.example.com/api/v1",
    timeout=60,
    retries=5,
    proxy="http://proxy.internal:8080",
)

Tip

For on-premises deployments, set base_url to the address of your private S4E instance.

Async Support

The SDK ships with a fully asynchronous client that mirrors the synchronous API. Use it when you need non-blocking I/O, such as inside an asyncio application or a FastAPI handler:

import asyncio
from s4e import AsyncS4EClient

async def main():
    async with AsyncS4EClient(api_key="YOUR_API_KEY") as client:
        assets = await client.assets.list()
        for asset in assets:
            print(asset.domain)

asyncio.run(main())

Error Handling

All API errors are mapped to typed exceptions so you can handle them precisely:

Exception	HTTP Status	Description
`S4EAuthError`	401 / 403	Invalid or expired API key.
`S4ERateLimitError`	429	Too many requests - back off and retry.
`S4ENotFoundError`	404	Requested resource does not exist.
`S4EValidationError`	422	Request payload failed validation.
`S4EAPIError`	5xx / other	Generic server-side or unexpected error.

from s4e.exceptions import S4EAuthError, S4ERateLimitError, S4EAPIError

try:
    findings = client.findings.list(severity="critical")
except S4EAuthError:
    print("Check your API key.")
except S4ERateLimitError as exc:
    print(f"Rate limited. Retry after {exc.retry_after} seconds.")
except S4EAPIError as exc:
    print(f"API error {exc.status_code}: {exc.message}")

SDK Modules

The client is organized into resource modules, each corresponding to a top-level API resource:

Module	Description
`assets`	CRUD operations on monitored domains and IPs.
`scans`	Create, list, and manage vulnerability scans.
`findings`	Query and export discovered vulnerabilities.
`actions`	Trigger remediation or notification actions.
`playbooks`	Execute and manage automated response playbooks.
`webhooks`	Register and manage webhook subscriptions.

Pagination Helpers

List endpoints return a PaginatedResponse object. You can iterate over pages manually or use the built-in auto-pagination helper:

# Auto-pagination - iterates through every page automatically
for finding in client.findings.list_auto(severity="high"):
    print(finding.title)

# Manual pagination
page = client.findings.list(page=1, per_page=50)
print(page.total, page.current_page, page.last_page)

Warning

Auto-pagination fetches all matching records. For very large result sets, consider filtering by date range or severity to limit the volume.

Logging Configuration

The SDK uses Python's standard logging module under the s4e logger name. Enable debug output to inspect outgoing requests and responses:

import logging

logging.basicConfig()
logging.getLogger("s4e").setLevel(logging.DEBUG)

Set the level to WARNING or higher in production to avoid leaking sensitive headers into log files.