Files, models & artifacts

Methods for uploading, updating, and managing files, models, artifacts, comments, and revisions on the Istari Digital Platform.

All methods are available on the Client instance. Parameters marked (required) must be provided. See Enums for valid enum values and Pagination for page/size defaults.

Files

add_file()

Add a new file to the system.

This method uploads a file from the specified path and optionally attaches metadata such as description, version name, external identifier, and associated sources.

• Parameters:

  • path (PathLike) – Filesystem path to the file to upload.
  • sources (list [**NewSource | str ] | None) – Optional list of sources related to the file. Each item may be a NewSource instance or a string source name.
  • description (str | None) – Optional text describing the file’s contents or purpose.
  • version_name (str | None) – Optional user-defined version label for the file.
  • external_identifier (str | None) – Optional external system identifier for the file.
  • display_name (str | None) – Optional human-readable name for the file.

• Return Type: File

update_file()

Update an existing file with a new version and optional metadata.

This method replaces the contents of a file by uploading a new version from the specified path. You can also update metadata such as sources, description, version name, or external identifier.

• Parameters:

  • file_id (str) – Unique identifier of the file to update.
  • path (PathLike | str) – Filesystem path or string path to the new file contents.
  • sources (list [**NewSource | str ] | None) – Optional list of sources related to the file. Each item may be a NewSource instance or a string source name.
  • description (str | None) – Optional updated description of the file.
  • version_name (str | None) – Optional user-defined version label for the updated file.
  • external_identifier (str | None) – Optional external system identifier for the file.
  • display_name (str | None) – Optional human-readable name for the file.

• Return Type: File

update_file_properties()

Update metadata properties of an existing file.

This method updates non-content attributes of a file, such as display name, description, version name, or external identifier, without modifying the file’s contents.

• Parameters:

  • file (File) – The file object whose metadata will be updated.
  • display_name (str | None) – Optional human-readable name to assign to the file.
  • description (str | None) – Optional text describing the file.
  • external_identifier (str | None) – Optional external system identifier for cross-referencing the file.
  • version_name (str | None) – Optional user-defined version label for the file.

• Return Type: File

get_file()

Gets a file by id.

• Parameters:

  • file_id (str) – The id of the file to get. (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: File

get_file_by_revision_id()

Gets a file by revision id.

• Parameters:

  • revision_id (str) – The revision id of the file to get. (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: File

list_files()

Lists all files that a user has access to.

• Parameters:

  • page (int) – Page number
  • size (int) – Page size
  • filter_by (FilterBy) – Filter results by ownership. One of: created_by_id (created by you), -created_by_id (shared with you).
  • archive_status (ArchiveStatus) – Filter results by archive status. One of: active, archived, all. Default: active.
  • sort (str)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: PageFile

archive_file()

Archives a file by updating it’s archive status to Archived.

• Parameters:

  • file_id (str) – The id of the file to archive. (required)
  • archive (Archive)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: File

restore_file()

Restores a file by updating it’s archive status to Active.

• Parameters:

  • file_id (str) – The id of the file to restore. (required)
  • restore (Restore)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: File

get_file_control_tagging_history()

Gets the full history of control taggings added to and removed from a file.

• Parameters:

  • file_id (str) – The ID of the file to get.. (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: List[FileControlTagging]

get_file_control_taggings()

Gets a file’s active control taggings.

• Parameters:

  • file_id (str) – The ID of the file to get.. (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: List[FileControlTagging]

Models

add_model()

Add a new model to the system.

This method uploads a model file from the specified path and optionally attaches metadata, including description, version name, external identifier, display name, and sources.

• Parameters:

  • path (PathLike) – Filesystem path to the model file to upload.
  • sources (list [**NewSource | str ] | None) – Optional list of sources associated with the model. Each item may be a NewSource instance or a string source name.
  • description (str | None) – Optional text describing the model’s purpose or contents.
  • version_name (str | None) – Optional user-defined version label for the model.
  • external_identifier (str | None) – Optional external system identifier for the model.
  • display_name (str | None) – Optional human-readable name for the model.

• Return Type: Model

update_model()

Update an existing model with a new file and optional metadata.

This method replaces the contents of a model by uploading a new file from the specified path. You can also update metadata such as description, version name, external identifier, and sources.

• Parameters:

  • model_id (str) – Unique identifier of the model to update.
  • path (PathLike) – Filesystem path to the new model file.
  • sources (list [**NewSource | str ] | None) – Optional list of sources associated with the model. Each item may be a NewSource instance or a string source name.
  • description (str | None) – Optional updated description of the model.
  • version_name (str | None) – Optional user-defined version label for the model.
  • external_identifier (str | None) – Optional external system identifier for the model.
  • display_name (str | None) – Optional human-readable name for the model.

• Return Type: Model

get_model()

Gets a model by id.

• Parameters:

  • model_id (str) – The model ID to get.. (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: Model

list_models()

Lists all models a user has access to.

• Parameters:

  • page (int) – Page number
  • size (int) – Page size
  • filter_by (FilterBy) – Filter results by ownership. One of: created_by_id (created by you), -created_by_id (shared with you).
  • archive_status (ArchiveStatus) – Filter results by archive status. One of: active, archived, all. Default: active.
  • sort (str)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: PageModelListItem

archive_model()

Archives a model by updating it’s archive status to Archived.

• Parameters:

  • model_id (str) – The id of the model to archive. (required)
  • archive (Archive)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: Model

restore_model()

Restores a model by updating it’s archive status to Active.

• Parameters:

  • model_id (str) – The id of the model to restore. (required)
  • restore (Restore)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: Model

get_model_control_tagging_history()

Gets the full history of control taggings added to and removed from a model.

• Parameters:

  • model_id (str) – The ID of the model to get.. (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: List[ResourceControlTagging]

get_model_control_taggings()

Gets a model’s active control taggings.

• Parameters:

  • model_id (str) – The ID of the model to get.. (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: List[ResourceControlTagging]

Artifacts

add_artifact()

Add a new artifact to a model.

This method creates a new artifact by uploading a file located at the given path and associating it with the specified model. Optionally, you can include metadata such as version name, description, external identifier, and source references.

• Parameters:

  • model_id (str) – Unique identifier of the model to which the artifact will be added.
  • path (PathLike) – Filesystem path to the artifact file to upload.
  • sources (list [**NewSource | str ] | None) – Optional list of sources associated with the artifact. Each item may be a NewSource instance or a string source name.
  • description (str | None) – Optional text describing the artifact’s contents or purpose.
  • version_name (str | None) – Optional user-defined version label for the artifact.
  • external_identifier (str | None) – Optional external system identifier for cross-referencing.
  • display_name (str | None) – Optional human-readable name for the artifact.

• Return Type: Artifact

update_artifact()

Update an existing artifact with a new file and optional metadata.

This method replaces the contents of an existing artifact by uploading a new file and optionally modifying associated metadata such as sources, version, or identifiers.

• Parameters:

  • artifact_id (str) – Unique identifier of the artifact to update.
  • path (PathLike) – Filesystem path to the new artifact file.
  • sources (list [**NewSource | str ] | None) – Optional list of sources associated with the artifact. Each item may be a NewSource instance or a string source name.
  • description (str | None) – Optional text describing the updated artifact.
  • version_name (str | None) – Optional user-defined version label for the updated artifact.
  • external_identifier (str | None) – Optional external system identifier for cross-referencing.
  • display_name (str | None) – Optional human-readable name for the updated artifact.

• Return Type: Artifact

get_artifact()

Gets an artifact from the database.

• Parameters:

  • artifact_id (str) – The id of the artifact to get.. (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: Artifact

list_artifacts()

Lists all artifacts a user has access to.

• Parameters:

  • page (int) – Page number
  • size (int) – Page size
  • filter_by (FilterBy) – Filter artifacts by ownership. One of: created_by_id (created by you), -created_by_id (shared with you).
  • archive_status (ArchiveStatus) – Filter results by archive status. One of: active, archived, all. Default: active.
  • sort (str)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: PageArtifact

list_model_artifacts()

Lists all artifacts a user has access to for a model.

• Parameters:

  • model_id (str) – The id of the model to list artifacts for. (required)
  • page (int) – Page number
  • size (int) – Page size
  • filter_by (FilterBy) – Filter model artifacts by ownership. One of: created_by_id (created by you), -created_by_id (shared with you).
  • archive_status (ArchiveStatus) – Filter results by archive status. One of: active, archived, all. Default: active.
  • sort (str)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: PageArtifact

archive_artifact()

Archives an artifact by updating it’s archive status to Archived.

• Parameters:

  • artifact_id (str) – The id of the artifact to archive.. (required)
  • archive (Archive)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: Artifact

restore_artifact()

Restores an artifact by updating it’s archive status to Active.

• Parameters:

  • artifact_id (str) – The id of the artifact to restore.. (required)
  • restore (Restore)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: Artifact

get_artifact_control_tagging_history()

Gets the full history of control taggings added to and removed from an artifact.

• Parameters:

  • artifact_id (str) – The ID of the artifact to get.. (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: List[ResourceControlTagging]

get_artifact_control_taggings()

Gets a artifact’s active control taggings.

• Parameters:

  • artifact_id (str) – The ID of the artifact to get.. (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: List[ResourceControlTagging]

Comments

add_comment()

Add a new comment to a resource.

This method uploads a file as a comment and associates it with the specified resource. An optional description can be provided to summarize or contextualize the comment content.

• Parameters:

  • resource_id (str) – Unique identifier of the resource to which the comment will be added.
  • path (PathLike) – Filesystem path to the comment file to upload.
  • description (str | None) – Optional text describing the comment or its relevance.

• Return Type: Comment

update_comment()

Update an existing comment with a new file and optional description.

This method replaces the contents of an existing comment by uploading a new file. An optional description can be provided to revise or clarify the comment’s purpose.

• Parameters:

  • comment_id (str) – Unique identifier of the comment to update.
  • path (PathLike) – Filesystem path to the new comment file.
  • description (str | None) – Optional updated description of the comment.

• Return Type: Comment

get_comment()

Gets a comment by id

• Parameters:

  • comment_id (str) – The ID of the comment to retrieve. (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: Comment

list_artifact_comments()

Lists all comments a user has access to for an artifact.

• Parameters:

  • artifact_id (str) – The id of the artifact to get comments for.. (required)
  • page (int) – Page number
  • size (int) – Page size
  • archive_status (ArchiveStatus) – Filter results by archive status. One of: active, archived, all. Default: active.
  • sort (str)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: PageComment

list_model_comments()

Lists all comments a user has access to for a model.

• Parameters:

  • model_id (str) – The model ID to which the comment belongs. (required)
  • page (int) – Page number
  • size (int) – Page size
  • archive_status (ArchiveStatus) – Filter results by archive status. One of: active, archived, all. Default: active.
  • sort (str)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: PageComment

archive_comment()

Archives a comment by updating it’s archive status to Archived.

• Parameters:

  • comment_id (str) – The ID of the comment to archive. (required)
  • archive (Archive)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: Comment

restore_comment()

Restores a comment by updating it’s archive status to Active.

• Parameters:

  • comment_id (str) – The ID of the comment to restore. (required)
  • restore (Restore)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: Comment

Revisions

create_revision()

Create a new file revision from a given file path and optional metadata.

This method uploads a file as a new revision and optionally attaches metadata such as sources, display name, description, version name, and an external identifier.

• Parameters:

  • file_path (PathLike) – Filesystem path to the file being uploaded as a revision.
  • sources (list [**NewSource | str ] | None) – Optional list of sources associated with the revision. Each item may be a NewSource instance or a string source name.
  • display_name (str | None) – Optional human-readable name for the revision.
  • description (str | None) – Optional text describing the revision’s contents or purpose.
  • version_name (str | None) – Optional user-defined version label for the revision.
  • external_identifier (str | None) – Optional external system identifier for the revision.

• Return Type: FileRevision

create_secret_revision()

Create a new secret file revision from a given file path and optional metadata.

This method uploads a file containing secret content as a new revision, and optionally associates metadata such as sources, display name, description, version name, and an external identifier.

• Parameters:

  • file_path (PathLike) – Filesystem path to the secret file being uploaded as a revision.
  • sources (list [**NewSource | str ] | None) – Optional list of sources associated with the revision. Each item may be a NewSource instance or a string source name.
  • display_name (str | None) – Optional human-readable name for the revision.
  • description (str | None) – Optional text describing the revision’s contents or purpose.
  • version_name (str | None) – Optional user-defined version label for the revision.
  • external_identifier (str | None) – Optional external system identifier for the revision.

• Return Type: FileRevision

update_revision_content()

Update the contents of an existing file revision.

This method uploads new content from the given file path to update an existing revision. A salt value must be provided to locate or identify the revision being updated. Optional metadata such as sources, display name, description, version name, and external identifier can also be modified.

• Parameters:

  • file_path (PathLike) – Filesystem path to the new file content for the revision.
  • salt (str) – Unique salt value used to identify or deduplicate the revision update.
  • sources (list [**NewSource | str ] | None) – Optional list of sources associated with the revision. Each item may be a NewSource instance or a string source name.
  • display_name (str | None) – Optional human-readable name for the revision.
  • description (str | None) – Optional text describing the updated revision content.
  • version_name (str | None) – Optional user-defined version label for the revision.
  • external_identifier (str | None) – Optional external system identifier for the revision.

• Return Type: FileRevision

update_revision_properties()

Update metadata properties of an existing file revision.

This method modifies the metadata associated with a file revision, such as display name, description, version name, or external identifier. The revision content itself is not changed.

• Parameters:

  • file_revision (FileRevision) – The file revision object whose metadata will be updated.
  • display_name (str | None) – Optional human-readable name for the revision.
  • description (str | None) – Optional text describing the revision.
  • external_identifier (str | None) – Optional external system identifier for the revision.
  • version_name (str | None) – Optional user-defined version label for the revision.

• Return Type: File

get_revision()

Gets a revision by id.

• Parameters:

  • revision_id (str) – The id of the revision to get (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: FileRevision

archive_file_revision()

Archives a FileRevision by updating it’s archive status to Archived.

• Parameters:

  • revision_id (str) – The id of the file revision to archive. (required)
  • archive (Archive)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: FileRevision

restore_file_revision()

Restores a FileRevision by updating it’s archive status to Active.

• Parameters:

  • revision_id (str) – The id of the file revision to restore. (required)
  • restore (Restore)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: FileRevision

read_contents()

Read and return the raw contents of a file associated with a token.

This method retrieves the file data as a byte stream using the specified token, which grants access to the protected resource.

• Parameters: token (Token) – Access token for retrieving the file contents.

• Return Type: bytes

read_properties()

Retrieve metadata properties for a file associated with a token.

This method returns descriptive metadata about the file identified by the provided access token. The returned Properties object includes non-content attributes such as file name, extension, size, MIME type, and optional descriptive metadata.

Fields include:

• name: Full file name with extension (e.g., “foo.JPG”).
• stem: File name without extension (e.g., “foo”).
• extension: Lowercased file extension without the dot (e.g., “jpg”).
• suffix: File suffix with original casing and a leading dot (e.g., “.JPG”).
• size: File size in bytes.
• mime_type: MIME type of the file (e.g., “image/jpeg”).
• description: Optional description set on the file.
• version_name: Optional version label.
• external_identifier: Optional external reference ID.
• display_name: Optional user-facing display name.

• Parameters: token (Token) – Access token used to retrieve file properties.

• Return Type: Properties

copy_revision_to_existing_file()

Copies a revision to an existing file.

• Parameters:

  • revision_id (str) – The id of the revision to copy (required)
  • file_id (str) – The id of the file to copy the revision to (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: File

copy_revision_to_new_file()

Copies a revision to a new file.

• Parameters:

  • revision_id (str) – The id of the revision to copy (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: File

transfer_revision_to_existing_file()

Transfers a file revision to an existing file. The original revision that was copied will be archived and no longer active.

• Parameters:

  • revision_id (str) – The id of the revision to transfer (required)
  • file_id (str) – The id of the file to transfer the revision to (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: File

transfer_revision_to_new_file()

Transfers a file revision to a new file. The original revision that was copied will be archived and no longer active.

• Parameters:

  • revision_id (str) – The id of the revision to transfer (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: File

transfer_revision_to_existing_artifact()

Transfers a revision to an existing artifact. The original revision that was copied will be archived and no longer active.

• Parameters:

  • revision_id (str) – The id of the revision to transfer (required)
  • artifact_id (str) – The id of the artifact to transfer the revision to (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: FileRevision

transfer_revision_to_new_artifact()

Transfers a revision to a new artifact. The original revision that was copied will be archived and no longer active.

• Parameters:

  • revision_id (str) – The id of the revision to transfer (required)
  • model_id (str) – The id of the model to transfer the revision to (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: FileRevision

Search

get_resource()

Retrieve a resource by type and ID.

This method fetches a resource of the specified type using its unique identifier. It dispatches to the appropriate get_* method based on the resource type.

• Parameters:

  • resource_type (str) – Type of the resource to retrieve. Must be one of: Artifact, Comment, Model, Job, FunctionAuthSecretEntity. (required)
  • resource_id (str) – Unique identifier of the resource. (required)

• Return Type: Artifact | Comment | Model | Job | FunctionAuthSecret

• Raises: TypeError if resource_type is not one of the supported values.

list_resources()

Lists all resources a user has access to.

• Parameters:

  • page (int) – Page number
  • size (int) – Page size
  • id (List [**Optional [**str ] ]) – A list of resource IDs to filter on
  • file_name (List [**Optional [**str ] ]) – A list of file names to filter on (single value performs a like comparison)
  • type_name (List [**ResourceType ]) – A list of resource types to filter on. Values: model, artifact, comment, job, document, resource.
  • description (List [**str ]) – A list of file descriptions to filter on (single value performs a like comparison)
  • version_name (List [**str ]) – A list of file version names to filter on (single value performs a like comparison)
  • external_identifier (List [**str ]) – A list of file external identifiers to filter on (single value performs a like comparison)
  • display_name (List [**str ]) – A list of file display names to filter on (single value performs a like comparison)
  • mime_type (List [**str ]) – A list of file mime types to filter on
  • file_size (List [**int ]) – A list of file sizes to filter on
  • created_timestamp (List [**Optional [**datetime ] ]) – A list of file creation timestamps to filter on
  • updated_timestamp (List [**datetime ]) – A list of file update timestamps to filter on
  • created_by_id (List [**str ]) – A list of user IDs that created the file to filter on
  • updated_by_id (List [**str ]) – A list of user IDs that updated the file to filter on
  • archive_status (List [**ArchiveStatusName ]) – A list of archive statuses to filter on. Values: Archived, Active.
  • access_type (BulkSharingAccessRelation) – Filter resources by access type. One of: viewer, editor.
  • sort (str)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: PageResourceSearchItem

search_resources()

Performs a full-text search across resources.

• Parameters:

  • full_text_search (FullTextSearch) – The search query. The search_term field must be at least 1 character. Results are paginated (default page size: 10, max: 100). (required)
  • http_request_timeout_secs (int , optional) – timeout setting for this request

• Return Type: PageTypeVarCustomizedResourceSearchItem