Core concepts - HiddenLayer Docs

This page explains the ideas you use in every HiddenLayer Python SDK program. Read it once before you start the workflow guides. Each section links to a page with more detail.

The client

The client is the object that holds your configuration (credentials, region, timeouts, retries) and sends requests to the HiddenLayer API. The SDK provides two clients with the same constructor arguments and the same methods:

Client	Import	Use it when
`HiddenLayer`	`from hiddenlayer import HiddenLayer`	You write ordinary (synchronous) Python: scripts, CI jobs, Flask or Django apps, notebooks.
`AsyncHiddenLayer`	`from hiddenlayer import AsyncHiddenLayer`	Your application already uses `asyncio` (for example FastAPI), or you need to send many requests concurrently.

Client and AsyncClient are aliases for the same classes. With the async client, you await every method call.

from hiddenlayer import HiddenLayer

# Reads HIDDENLAYER_CLIENT_ID and HIDDENLAYER_CLIENT_SECRET from the environment.
with HiddenLayer() as client:
    page = client.scans.jobs.list(limit=5)
    print(page.total)

import asyncio

from hiddenlayer import AsyncHiddenLayer


async def main() -> None:
    # Reads HIDDENLAYER_CLIENT_ID and HIDDENLAYER_CLIENT_SECRET from the environment.
    async with AsyncHiddenLayer() as client:
        page = await client.scans.jobs.list(limit=5)
        print(page.total)


asyncio.run(main())

Create one client and reuse it

Create the client once (for example at application startup) and share it. Reusing a client matters for two reasons:

Connection reuse. The client keeps a pool of HTTP connections open, so later requests are faster.
Token caching. With client ID and client secret authentication, the client requests an access token once, caches it, and refreshes it shortly before it expires. The cache is protected by a lock, so a single client can be shared safely across threads. A new client per request would fetch a new token every time.

Close the client when you are done, either with a with block (as shown above) or by calling client.close() (await client.close() for the async client). If you do neither, connections close when the client is garbage collected.

Resources and methods

The client groups API operations into resources. You call an operation as client.<resource>.<method>(). Some resources are nested, such as client.scans.jobs.list().

Resource	Product area	Status
`client.model_scanner`	AI Supply Chain Security: scan local files, folders, S3, Azure Blob, Hugging Face	High-level helper
`client.community_scanner`	AI Supply Chain Security: scan models at a remote location	High-level helper
`client.scans.jobs`	AI Supply Chain Security: list, retrieve, and request scans	Generally available
`client.scans.results`	AI Supply Chain Security: scan summary, paginated file results, SARIF export	Generally available
`client.scans.upload`, `client.scans.upload.file`	AI Supply Chain Security: multipart upload steps	Generally available
`client.models`	AI Supply Chain Security: retrieve and delete models	Generally available
`client.models.cards`	Model cards listing	Deprecated
`client.interactions`	AI Runtime Security: Interactions (analyze LLM input and output)	Generally available
`client.runtime`	AI Runtime Security: agentic evaluation endpoints	Beta
`client.prompt_analyzer`	Prompt Analyzer	Generally available
`client.evaluations.red_team`	AI Attack Simulation: low-level red team endpoints	Beta
`client.evaluation_sessions.red_team`	AI Attack Simulation: session helper with polling and callbacks	Beta (wraps Beta endpoints)
`client.sensors`	Sensors	Deprecated (the SDK docstring says the endpoint “will be removed after April 13, 2026”)

See the Python API reference for every method signature.

High-level helpers and low-level resources

Most resources map one-to-one to a REST endpoint. These are low-level resources: one method call sends one HTTP request. Three attributes are high-level helpers written by HiddenLayer on top of the low-level resources:

client.model_scanner uploads model files in parts, starts the scan, polls until it finishes, and collects all file results into one ScanReport.
client.community_scanner asks HiddenLayer to fetch and scan a model from a remote location, then optionally waits for results.
client.evaluation_sessions.red_team starts a red team workflow and drives it with polling, iteration, or a callback function.

Start with the helpers for common tasks. Use low-level resources when you need control the helpers do not offer, such as listing past scans or exporting SARIF. The API usage examples page shows low-level recipes.

Environments and base URL

An environment is the HiddenLayer region your account lives in. The client turns the environment into a base URL, the address every request starts with.

Environment	Base URL
`prod-us` (default)	`https://api.us.hiddenlayer.ai`
`prod-eu`	`https://api.eu.hiddenlayer.ai`

The client chooses the base URL in this order:

The base_url constructor argument.
The environment constructor argument.
The HIDDENLAYER_BASE_URL environment variable.
prod-us.

If you pass environment while HIDDENLAYER_BASE_URL is also set, the constructor raises a ValueError (“Ambiguous URL”). Set only one of them. Use base_url for a self-hosted endpoint, such as a local AI Runtime Security container. Credentials are region specific, because the token request goes to the same base URL. Use credentials created in the same region you connect to.

Authentication

The client supports two authentication methods:

OAuth2 client credentials (recommended). OAuth2 client credentials is a standard flow where your program exchanges a client ID and client secret for a short-lived access token. Set HIDDENLAYER_CLIENT_ID and HIDDENLAYER_CLIENT_SECRET. The client fetches, caches, and refreshes the token for you.
Bearer token. Set HIDDENLAYER_TOKEN to an access token you obtained elsewhere. The client sends it as-is and does not refresh it.

Configure only one method. See Authentication and configuration for setup steps.

Request parameters are TypedDicts

Method arguments that contain nested data, such as metadata or input for client.interactions.analyze(), are typed as TypedDicts. A TypedDict is a normal Python dict with a declared set of keys and value types. Because of this:

You pass plain dictionaries. You do not need to import or construct special classes.
Editors and type checkers (such as Pyright or mypy) can autocomplete keys and flag typos.

from hiddenlayer import HiddenLayer

client = HiddenLayer()

response = client.interactions.analyze(
    metadata={"model": "gpt-4o", "requester_id": "user-1234"},
    input={"messages": [{"role": "user", "content": "Hello"}]},
)

Responses are Pydantic models

Methods return Pydantic models. Pydantic is a data validation library. A Pydantic model is a Python object whose attributes are parsed from JSON and have declared types. You read values with attribute access, for example report.summary.highest_severity. Useful helpers on every response model:

Helper	What it does
`.to_dict()`	Converts the model to a Python dictionary.
`.to_json()`	Converts the model to an indented JSON string. Useful for logging or saving results.
`.model_fields_set`	The set of fields present in the API response. Use it to tell whether a `None` value was `null` in the JSON or missing entirely.
`.model_extra`	A dictionary of fields the API returned that this SDK version does not define yet.

from hiddenlayer import HiddenLayer

client = HiddenLayer()

summary = client.scans.results.retrieve_summary("YOUR_SCAN_ID")
print(summary.status)
print(summary.to_json())

if summary.end_time is None and "end_time" not in summary.model_fields_set:
    print("The API did not return end_time.")

Response types live under hiddenlayer.types, for example from hiddenlayer.types import InteractionAnalyzeResponse or from hiddenlayer.types.scans import ScanReport. Import them for type hints. A few endpoints return plain Python types instead of models. For example, client.scans.results.sarif() returns a str, and client.runtime.evaluate_request() returns a dict.

Projects and the `hl_project_id` parameter

In AI Runtime Security, a project groups your application’s traffic and selects the policy used to evaluate it. Runtime methods (interactions.analyze, runtime.evaluate_*, prompt_analyzer.create) and evaluations.red_team.create accept an optional hl_project_id argument. The SDK sends it as the HL-Project-Id HTTP header. If you omit it, the API applies its default behavior.

from hiddenlayer import HiddenLayer

client = HiddenLayer()

response = client.interactions.analyze(
    metadata={"model": "gpt-4o", "requester_id": "user-1234"},
    input={"messages": [{"role": "user", "content": "Hello"}]},
    hl_project_id="YOUR_PROJECT_ID",
)

The red team session helper uses the argument name hiddenlayer_project_id instead. See Runtime security and the policy documentation.

Beta APIs and `BetaWarning`

Some endpoints are Beta: they are not generally available and can change without notice, including breaking changes. Beta functions and types are excluded from the SDK’s semantic versioning guarantees. See the Beta API guidelines. When you call a Beta endpoint, the SDK emits a hiddenlayer.BetaWarning (a subclass of Python’s UserWarning) through the standard warnings module. In SDK version 3.10.0 this applies to:

client.runtime.evaluate_interaction, evaluate_request, and evaluate_response
All client.evaluations.red_team methods, including calls made by client.evaluation_sessions.red_team

The 3.9.0 changelog says the Beta label was removed from the runtime v2 endpoints, but version 3.10.0 still emits BetaWarning for them. This discrepancy needs confirmation.

After you have reviewed the Beta terms, you can silence the warning:

import warnings

import hiddenlayer

warnings.filterwarnings("ignore", category=hiddenlayer.BetaWarning)

Pagination

Endpoints that return many items use one of three patterns. Each one needs different code, so check the return type in the API reference.

Pattern	Used by	How to page
Cursor pagination (`SyncCursorPagination` / `AsyncCursorPagination`)	`client.scans.results.list_files()`	Iterate the result with `for` (or `async for`) and the SDK fetches pages automatically. Items of the current page are in `.items`. For manual control, use `.has_next_page()` and `.get_next_page()`.
Offset pagination (`SyncOffsetPage` / `AsyncOffsetPage`)	`client.models.cards.list()` (deprecated)	Iterate to auto-paginate. Items of the current page are in `.results`.
Plain list with `limit` and `offset`	`client.scans.jobs.list()`	Not auto-paginated. The response has `items`, `limit`, `offset`, and `total`. Increase `offset` yourself until you reach `total`.

from hiddenlayer import HiddenLayer

client = HiddenLayer()

# Cursor pagination: the loop fetches more pages as needed.
for file_result in client.scans.results.list_files("YOUR_SCAN_ID", page_size=50):
    print(file_result.file_location, file_result.status)

See API usage examples for full paging loops.

Raw and streaming responses

By default, methods return the parsed body only. Two prefixes give you access to the underlying HTTP response:

client.<resource>.with_raw_response.<method>(...) returns an APIResponse with .status_code, .headers, and .parse() (which returns the normal parsed object). Use it when you need a response header, such as the hl-runtime-action header from the agentic evaluation endpoints.
client.<resource>.with_streaming_response.<method>(...) must be used in a with block. It does not read the body until you call a method such as .iter_bytes(), .iter_lines(), .json(), or .parse(). Use it for large responses.

from hiddenlayer import HiddenLayer

client = HiddenLayer()

raw = client.scans.results.with_raw_response.retrieve_summary("YOUR_SCAN_ID")
print(raw.status_code, raw.headers.get("content-type"))
summary = raw.parse()

Retries and timeouts

The client retries failed requests automatically so that short outages do not break your program.

Setting	Default	How to change
Retries	2 retries with exponential backoff (starting at 0.5 seconds, capped at 8 seconds). The client honors `retry-after` headers.	`max_retries=` on the client or with `client.with_options()`. `0` disables retries.
Retried conditions	Connection errors, timeouts, and HTTP 408, 409, 429, and 5xx responses	Not configurable
Timeout	60 seconds per request, 5 seconds to connect	`timeout=` on the client, with `client.with_options()`, or per method call. Accepts a number of seconds or an `httpx.Timeout`.

from hiddenlayer import HiddenLayer

client = HiddenLayer(max_retries=4, timeout=30.0)

# Override for a single call without changing the shared client.
client.with_options(timeout=120.0, max_retries=0).scans.jobs.list(limit=10)

client.with_options() returns a new client that shares the original’s connection pool, so it is cheap to call.

Retries and timeouts apply to each HTTP request. They do not limit how long model_scanner or community_scanner wait for a scan when wait_for_results=True. Those helpers poll until the scan finishes, with no overall time limit. See Model scanning.

Logging

The SDK uses Python’s standard logging module. Set the HIDDENLAYER_LOG environment variable to turn it on:

info enables informational messages from the SDK and its HTTP library (httpx), such as requests sent and retries.
debug adds detailed request information, including request bodies.

Debug logging can write prompts, model responses, and other sensitive request data to your logs. Do not enable HIDDENLAYER_LOG=debug in production or anywhere logs are shared.

​The client

​Create one client and reuse it

​Resources and methods

​High-level helpers and low-level resources

​Environments and base URL

​Authentication

​Request parameters are TypedDicts

​Responses are Pydantic models

​Projects and the hl_project_id parameter

​Beta APIs and BetaWarning

​Pagination

​Raw and streaming responses

​Retries and timeouts

​Logging

​Next steps

The client

Create one client and reuse it

Resources and methods

High-level helpers and low-level resources

Environments and base URL

Authentication

Request parameters are TypedDicts

Responses are Pydantic models

Projects and the `hl_project_id` parameter

Beta APIs and `BetaWarning`

Pagination

Raw and streaming responses

Retries and timeouts

Logging

Next steps