enterprise_ai.storage
Source: sdks/python/src/enterprise_ai/storage/__init__.py. Back to the Python SDK reference index.
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 StorageClient
/v1/storage.
Resource
StorageClient.checks
checks(profile_id: str, limit: int | None = None) -> Any
List the verifications of a profile. History of the capability verifications of the profile, newest first: status, capabilities found, missing capabilities, whether a write probe ran, error, duration in milliseconds and who ran it. One page only (next_cursor is always null). Same readers as the list.
Route: /v1/storage/profiles/{profile_id}/checks (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
profile_id | str | yes | Identifier (UUID) of the storage profile. | |
limit | int | None | None | no | Maximum number of verifications, 1 to 500, default 50. |
Returns: Any. Decoded JSON answer of the operation "List the verifications of a profile".
Raises: the typed errors of the transport (Errors).
StorageClient.create_profile
create_profile(name: str, provider: str, bucket: str, scope: str | None = None, endpoint: str | None = None, region: str | None = None, key_prefix: str | None = None, credential_ref: str | None = None, auth: dict[str, Any] | None = None, encryption: dict[str, Any] | None = None, purposes: list[str] | None = None, presign_prefixes: list[str] | None = None, required_capabilities: list[str] | None = None, options: dict[str, Any] | None = None, description: str | None = None) -> Any
Create a storage profile. Creates a profile with status unverified and answers 201. Requires tenant_admin for scope tenant (inside a tenant) or platform_admin for scope platform (403 storage_scope_forbidden), and the policy decision storage.profile.create. Audited (storage.profile.create).
Route: /v1/storage/profiles (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
name | str | yes | Unique name of the profile in its scope: 2 to 63 characters, lowercase letters, digits and dashes, starting with a letter or a digit. | |
provider | str | yes | Storage provider: aws_s3, ibm_cos, seaweedfs, s3_compatible, azure_blob or gcs. | |
bucket | str | yes | Bucket or container name: 3 to 222 characters, lowercase letters, digits, dots, dashes and underscores, starting and ending with a letter or digit, no ... | |
scope | str | None | None | no | tenant (default) for a profile of the caller's tenant, platform for a profile shared by the platform (platform administrator only). |
endpoint | str | None | None | no | HTTPS address of the storage service, 500 characters at most. Required for ibm_cos, seaweedfs and s3_compatible; optional otherwise. |
region | str | None | None | no | Region of the bucket, 64 characters at most. |
key_prefix | str | None | None | no | Prefix added to every object key written through this profile, 512 characters at most; empty by default. |
credential_ref | str | None | None | no | Reference of the secret, 210 characters at most: openbao://<path> for a tenant profile, env://EAI_CRED_<NAME> for a platform profile. Not used with workload_identity. The secret value is never sent. |
auth | dict[str, Any] | None | None | no | Non secret authentication settings: method (sigv4 for S3 family providers, also ibm_iam for IBM COS; shared_key, sas, entra_client_secret or workload_identity for Azure; service_account for GCS) and, as needed, account, tenant_id, client_id, service_instance_id, token_url, scope. account is required for Azure; workload_identity is for platform profiles only. |
encryption | dict[str, Any] | None | None | no | Server side encryption, default {mode: provider_default}. Modes: provider_default, sse-s3, sse-kms for the S3 family; provider_default, encryption-scope (with encryption_scope) for Azure; provider_default, cmek (with kms_key_id) for GCS. |
purposes | list[str] | None | None | no | What the profile is used for, up to 10 among audit_worm, evidence, documents, media, exports, backups, general. audit_worm needs object lock, retention and integrity; evidence needs object lock and integrity. |
presign_prefixes | list[str] | None | None | no | Key prefixes reachable through the API (presigned URLs, listing, deletion), up to 20. Empty by default: no key is reachable. |
required_capabilities | list[str] | None | None | no | Capabilities the profile must have beyond those of its purposes, up to 20 among versioning, object_lock, legal_hold, retention, multipart, presign, sse, kms, storage_classes, lifecycle, replication, integrity. |
options | dict[str, Any] | None | None | no | Provider options: path_style (path style addressing for S3) and storage_class. Any other key is refused. |
description | str | None | None | no | Free description, 500 characters at most. |
Returns: Any. Decoded JSON answer of the operation "Create a storage profile".
Raises: the typed errors of the transport (Errors).
StorageClient.delete_object
delete_object(profile_id: str, key: str, version_id: str | None = None) -> Any
Delete an object of a profile. Deletes one object (or one version of it) inside the presign prefixes of the profile. A profile serving audit_worm or evidence never deletes through the API (409 storage_object_protected); a retention refusal of the backend is returned as is. Requires tenant_admin, developer or agent (platform profile: platform_admin) and the policy decision storage.object.delete; audited with the full key and version. Other errors: 403 storage_key_out_of_scope, 422 storage_key_invalid, 409 storage_profile_disabled.
Route: /v1/storage/profiles/{profile_id}/objects/delete (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
profile_id | str | yes | Identifier (UUID) of the storage profile. | |
key | str | yes | Key of the object relative to the profile key prefix, 1 to 1024 characters, inside a presign prefix; no control character, no leading /, no . or .. segment. | |
version_id | str | None | None | no | Version of the object to delete on a versioned bucket, 1 to 1024 characters. Omit it to delete the current version. |
Returns: Any. Decoded JSON answer of the operation "Delete an object of a profile".
Raises: the typed errors of the transport (Errors).
StorageClient.delete_profile
delete_profile(profile_id: str) -> Any
Delete a storage profile. Deletes the profile (the bucket and its objects are not touched) and answers 204. Requires tenant_admin for a tenant profile, platform_admin for a platform profile (403 storage_scope_forbidden), and the policy decision storage.profile.delete. The audit event storage.profile.delete records the provider, bucket and the number of audit exports that used it. Unknown id: 404 storage_profile_not_found.
Route: /v1/storage/profiles/{profile_id} (DELETE).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
profile_id | str | yes | Identifier (UUID) of the storage profile. |
Returns: Any. Decoded JSON answer of the operation "Delete a storage profile".
Raises: the typed errors of the transport (Errors).
StorageClient.get
get(profile_id: str, key: str, purpose: str | None = None) -> Any
Issue a presigned URL. Issues a presigned URL to read (GET) or write (PUT) one object directly in the bucket, and answers 201 with the grant id, URL, method, full key, lifetime and expiry. The key must be inside the presign prefixes (403 storage_key_out_of_scope) and the profile must have a verified, recent presign capability (409 storage_capability_missing). The lifetime may not exceed EAI_STORAGE_PRESIGN_MAX_SECONDS (3600 by default, never more than 604800; 422 storage_presign_expiry_invalid). Requires tenant_admin, developer or agent (platform profile: platform_admin) and the policy decision storage.presign.read or storage.presign.write. The grant is recorded with a SHA-256 of the URL (never the URL itself) and audited.
Route: /v1/storage/profiles/{profile_id}/presign (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
profile_id | str | yes | Identifier (UUID) of the storage profile. | |
key | str | yes | Key of the object relative to the profile key prefix, 1 to 1024 characters, inside a presign prefix of the profile. | |
purpose | str | None | None | no | Free label of why the URL is issued, stored with the grant; 200 characters at most. |
Returns: Any. Decoded JSON answer of the operation "Issue a presigned URL".
Raises: the typed errors of the transport (Errors).
StorageClient.get_profile
get_profile(profile_id: str) -> Any
Get a storage profile. One storage profile with its status, discovered capabilities, verification time, missing and needed capabilities and last error. Never a secret value. Same readers as the list. Unknown id: 404 storage_profile_not_found.
Route: /v1/storage/profiles/{profile_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
profile_id | str | yes | Identifier (UUID) of the storage profile. |
Returns: Any. Decoded JSON answer of the operation "Get a storage profile".
Raises: the typed errors of the transport (Errors).
StorageClient.list_objects
list_objects(profile_id: str, prefix: str | None = None, limit: int | None = None, cursor: str | None = None) -> Any
List the objects of a profile. Objects stored under a prefix inside the presign prefixes of the profile: key relative to the profile key prefix (usable with presign and delete), stored key, size, ETag, content type, SHA-256, version, last modification and storage class. Requires tenant_admin, developer, agent or auditor (platform profile: platform_admin) and the policy decision storage.object.list; the listing is audited. Errors: 422 storage_prefix_required when prefix is omitted and the profile has not exactly one presign prefix, 403 storage_key_out_of_scope outside the presign prefixes, 409 storage_profile_disabled.
Route: /v1/storage/profiles/{profile_id}/objects (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
profile_id | str | yes | Identifier (UUID) of the storage profile. | |
prefix | str | None | None | no | Key prefix to list, relative to the profile key prefix and inside one of its presign prefixes; 1024 characters at most. Defaults to the only presign prefix of the profile. |
limit | int | None | None | no | Maximum number of objects in one page, 1 to 500, default 50. |
cursor | str | None | None | no | Opaque continuation token of the backend, returned as next_cursor by the previous page; 4096 characters at most. |
Returns: Any. Decoded JSON answer of the operation "List the objects of a profile".
Raises: the typed errors of the transport (Errors).
StorageClient.list_profiles
list_profiles(provider: str | None = None, purpose: str | None = None, scope: str | None = None, limit: int | None = None) -> Any
List the storage profiles. Storage profiles visible to the caller, ordered by scope then name, each with its needed_capabilities (required capabilities plus those its purposes need). One page only: next_cursor is always null. Requires platform_admin, or a tenant principal with tenant_admin, security_officer, developer or auditor.
Route: /v1/storage/profiles (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
provider | str | None | None | no | Only profiles of this provider, for example aws_s3 or azure_blob. |
purpose | str | None | None | no | Only profiles that serve this purpose, for example audit_worm or documents. |
scope | str | None | None | no | Only profiles of this scope: tenant or platform. |
limit | int | None | None | no | Maximum number of profiles, 1 to 500, default 50. |
Returns: Any. Decoded JSON answer of the operation "List the storage profiles".
Raises: the typed errors of the transport (Errors).
StorageClient.presign
presign(profile_id: str, key: str, scope: str, purpose: str | None = None, content_type: str | None = None, expires_seconds: int | None = None) -> Any
Issue a presigned URL. Issues a presigned URL to read (GET) or write (PUT) one object directly in the bucket, and answers 201 with the grant id, URL, method, full key, lifetime and expiry. The key must be inside the presign prefixes (403 storage_key_out_of_scope) and the profile must have a verified, recent presign capability (409 storage_capability_missing). The lifetime may not exceed EAI_STORAGE_PRESIGN_MAX_SECONDS (3600 by default, never more than 604800; 422 storage_presign_expiry_invalid). Requires tenant_admin, developer or agent (platform profile: platform_admin) and the policy decision storage.presign.read or storage.presign.write. The grant is recorded with a SHA-256 of the URL (never the URL itself) and audited.
Route: /v1/storage/profiles/{profile_id}/presign (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
profile_id | str | yes | Identifier (UUID) of the storage profile. | |
key | str | yes | Key of the object relative to the profile key prefix, 1 to 1024 characters, inside a presign prefix of the profile. | |
scope | str | yes | Direction of the URL: read gives a GET URL, write a PUT URL. | |
purpose | str | None | None | no | Free label of why the URL is issued, stored with the grant; 200 characters at most. |
content_type | str | None | None | no | Content type passed to the backend when the URL is signed (the type the upload is expected to send); 200 characters at most. |
expires_seconds | int | None | None | no | Lifetime of the URL in seconds, default 900, at most EAI_STORAGE_PRESIGN_MAX_SECONDS (3600 by default) and never more than 604800. |
Returns: Any. Decoded JSON answer of the operation "Issue a presigned URL".
Raises: the typed errors of the transport (Errors).
StorageClient.put
put(profile_id: str, key: str, data: bytes, content_type: str | None = None, purpose: str | None = None, headers: dict[str, str] | None = None) -> Any
Issue a presigned URL. Issues a presigned URL to read (GET) or write (PUT) one object directly in the bucket, and answers 201 with the grant id, URL, method, full key, lifetime and expiry. The key must be inside the presign prefixes (403 storage_key_out_of_scope) and the profile must have a verified, recent presign capability (409 storage_capability_missing). The lifetime may not exceed EAI_STORAGE_PRESIGN_MAX_SECONDS (3600 by default, never more than 604800; 422 storage_presign_expiry_invalid). Requires tenant_admin, developer or agent (platform profile: platform_admin) and the policy decision storage.presign.read or storage.presign.write. The grant is recorded with a SHA-256 of the URL (never the URL itself) and audited.
Route: /v1/storage/profiles/{profile_id}/presign (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
profile_id | str | yes | Identifier (UUID) of the storage profile. | |
key | str | yes | Key of the object relative to the profile key prefix, 1 to 1024 characters, inside a presign prefix of the profile. | |
data | bytes | yes | Object, direction and lifetime of the presigned URL. | |
content_type | str | None | None | no | Content type passed to the backend when the URL is signed (the type the upload is expected to send); 200 characters at most. |
purpose | str | None | None | no | Free label of why the URL is issued, stored with the grant; 200 characters at most. |
headers | dict[str, str] | None | None | no | Headers of the event, string values. The trace context is added. |
Returns: Any. Decoded JSON answer of the operation "Issue a presigned URL".
Raises: the typed errors of the transport (Errors).
StorageClient.update_profile
update_profile(profile_id: str, **changes: Any) -> Any
Update a storage profile. Changes the given fields; the merged profile is validated like a new one. A change of provider, endpoint, region, bucket, auth, credential_ref, encryption or options clears the capabilities and sets the status back to unverified; status: disabled disables the profile, status: active on a disabled profile makes it unverified. Adding the purpose audit_worm without such a change requires a verified object lock capability (409 storage_capability_missing). Requires tenant_admin (platform profile: platform_admin) and the policy decision storage.profile.update; audited with the changed fields.
Route: /v1/storage/profiles/{profile_id} (PATCH).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
profile_id | str | yes | Identifier (UUID) of the storage profile. | |
**changes | Any | no | Fields of the storage profile to change. |
Returns: Any. Decoded JSON answer of the operation "Update a storage profile".
Raises: the typed errors of the transport (Errors).
StorageClient.verify_profile
verify_profile(profile_id: str, probe_write: bool | None = None) -> Any
Verify the capabilities of a profile. Discovers the capabilities of the bucket by real calls and stores them. Requires tenant_admin or security_officer (platform profile: platform_admin) and the policy decision storage.profile.verify. A disabled profile answers 409 storage_profile_disabled.
Route: /v1/storage/profiles/{profile_id}/verify (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
profile_id | str | yes | Identifier (UUID) of the storage profile. | |
probe_write | bool | None | None | no | When true (default), a probe object is written with the configured encryption, storage class and legal hold, read back and removed, to verify storage classes and integrity. It is skipped when the bucket has a default retention. When false, those two capabilities stay unverified. |
Returns: Any. Decoded JSON answer of the operation "Verify the capabilities of a profile".
Raises: the typed errors of the transport (Errors).
Functions
confirm_deleted
confirm_deleted(answer: Any) -> Any
Return an object deletion only when the server reports deleted: true.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
answer | Any | yes | Answer of POST /v1/storage/profiles/{profile_id}/objects/delete to check. |
Returns: Any. The same answer, unchanged; otherwise storage_delete_unconfirmed is raised.
Raises: EaiError.