enterprise_ai.file_security

Source: sdks/python/src/enterprise_ai/file_security/__init__.py. Back to the Python SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Class FileSecurityClient

/v1/file-security: engine status, tenant policy, explicit scans, rescans, sample purge and stats.

Resource

FileSecurityClient.get_scan

get_scan(scan_id: str) -> Any

Get a scan record. One scan record: status, verdict, reasons, source and its reference, file name, declared and detected type, size, SHA-256, answer of each engine, whether a sample is kept, the scan it rescans, creator and dates (creation, scan, sample expiry). Requires a tenant principal; a record of someone else is visible only to tenant_admin, security_officer and auditor (404 not_found otherwise).

Route: /v1/file-security/scans/{scan_id} (GET).

Name	Type	Default	Required	Description
scan_id	str		yes	Identifier of the scan record.

Returns: Any. Decoded JSON answer of the operation "Get a scan record".

Raises: the typed errors of the transport (Errors).

FileSecurityClient.list_scans

list_scans(status: str | None = None, verdict: str | None = None, source: str | None = None, limit: int | None = None, cursor: str | None = None) -> Any

List the scan records. Scan records of the tenant, newest first; a principal without a reader role (tenant_admin, security_officer, auditor) only sees its own scans. Requires a tenant principal. An unknown status, verdict or source answers 400 invalid_request; a malformed cursor 400 invalid_cursor.

Route: /v1/file-security/scans (GET).

Name	Type	Default	Required	Description
status	str | None	None	no	Only records in this status: quarantined, released or blocked.
verdict	str | None	None	no	Only records with this verdict: clean, malware, suspicious, unscannable, scan_error or policy_violation.
source	str | None	None	no	Only files from this entry point: knowledge, media, multimodal, transcription, connector, channel or api.
limit	int | None	None	no	Maximum number of records in one page: 50 by default, capped at 500.
cursor	str | None	None	no	Opaque cursor returned as next_cursor by the previous page. Omit it to read the newest records.

Returns: Any. Decoded JSON answer of the operation "List the scan records".

Raises: the typed errors of the transport (Errors).

FileSecurityClient.policy

policy() -> Any

Read the file security policy. Effective policy of the tenant: the locked rules, every editable rule (stored values over the defaults, the size never above the platform ceiling EAI_FILE_SCAN_MAX_BYTES), the known file types, and when and by whom it was last changed. Requires a tenant principal with tenant_admin, security_officer or auditor (403 forbidden).

Route: /v1/file-security/policy (GET).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Read the file security policy".

Raises: the typed errors of the transport (Errors).

FileSecurityClient.purge_sample

purge_sample(scan_id: str) -> Any

Purge the sample of a blocked file. Deletes the encrypted sample of a blocked file now, without waiting for the end of its retention, and answers sample_retained: false. The purge is audited (file_security.sample.purge) with the SHA-256 of the file. Requires a tenant principal with security_officer or tenant_admin (403 forbidden). A scan that is unknown or not visible to the caller answers 404 not_found.

Route: /v1/file-security/scans/{scan_id}/sample (DELETE).

Name	Type	Default	Required	Description
scan_id	str		yes	Identifier of the scan record.

Returns: Any. Decoded JSON answer of the operation "Purge the sample of a blocked file".

Raises: the typed errors of the transport (Errors).

FileSecurityClient.rescan

rescan(scan_id: str) -> Any

Rescan the sample of a blocked file. Scans the retained sample of a blocked file again, for example after a signature update, and answers 201 with a new record whose rescan_of names the original scan. The original upload is never released: a clean result only informs. Requires a tenant principal with security_officer or tenant_admin (403 forbidden). Without a retained sample: 409 file_sample_unavailable; unknown or invisible scan: 404 not_found.

Route: /v1/file-security/scans/{scan_id}/rescan (POST).

Name	Type	Default	Required	Description
scan_id	str		yes	Identifier of the blocked scan record whose sample is scanned again.

Returns: Any. Decoded JSON answer of the operation "Rescan the sample of a blocked file".

Raises: the typed errors of the transport (Errors).

FileSecurityClient.scan

scan(data: bytes, filename: str | None = None, mime_type: str | None = None) -> Any

Scan a file without ingesting it. Scans a file without ingesting it and answers 201 with the record, released or blocked (a blocked file is not an error here). Any tenant principal may call it (403 tenant_required otherwise).

Route: /v1/file-security/scans (POST).

Name	Type	Default	Required	Description
data	bytes		yes	Either JSON {content_base64, filename?, mime_type?} or multipart/form-data with a file part and the optional filename and mime_type fields (they override the values of the part).
filename	str | None	None	no	Name of the file sent with the multipart part (file when omitted).
mime_type	str | None	None	no	Media type of the content, for example application/pdf or image/png.

Returns: Any. Decoded JSON answer of the operation "Scan a file without ingesting it".

Raises: the typed errors of the transport (Errors).

FileSecurityClient.stats

stats(window_hours: int | None = None) -> Any

Read the scan statistics. Number of scans over the last window_hours hours, by status, by verdict and by source, with the time of the last blocked file. Readers (tenant_admin, security_officer, auditor) count every scan of the tenant, anyone else only its own. Requires a tenant principal. A window outside 1 to 8784 hours answers 400 invalid_request.

Route: /v1/file-security/stats (GET).

Name	Type	Default	Required	Description
window_hours	int | None	None	no	Length of the window in hours, 1 to 8784 (366 days), default 24.

Returns: Any. Decoded JSON answer of the operation "Read the scan statistics".

Raises: the typed errors of the transport (Errors).

FileSecurityClient.status

status() -> Any

Read the scan engines status. Mode (enforce or dev), readiness, pipeline and every ClamAV gateway and YARA-X worker, probed live: version, signature version, publication and age with a stale flag against the policy, rules version, hash, count and load time, latency. The instance is ready when each engine has at least one healthy endpoint (in enforce mode, or when it is configured). Requires tenant_admin, security_officer or auditor (403 forbidden).

Route: /v1/file-security/status (GET).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Read the scan engines status".

Raises: the typed errors of the transport (Errors).

FileSecurityClient.update_policy

update_policy(**fields: Any) -> Any

Change the file security policy. Changes the editable rules given in the body; the other rules keep their value. Sizes may only be tighter than the platform ceiling, and the locked rules never change (422 file_security_rule_locked). An unknown field, an unknown type or a value out of bounds answers 422 invalid_request with the field and the reason. Requires a tenant principal with security_officer or tenant_admin (403 forbidden). The change is audited (file_security.policy.update) with the values before and after; the answer is the new effective policy.

Route: /v1/file-security/policy (PUT).

Name	Type	Default	Required	Description
**fields	Any		no	Fields of the method (for example user and password), up to 16 text values.

Returns: Any. Decoded JSON answer of the operation "Change the file security policy".

Raises: the typed errors of the transport (Errors).