Skip to main content
Version: 2026.10

Packages and libraries

Availability

Each deployment turns two kinds of packaging write on or off separately: publishing (creating package versions) and resolution (recording which package versions a System branch installs). get_package_capabilities() reports each one as publishing_writes_enabled and resolution_writes_enabled; call it before you publish. Contact your administrator if the one you need is off.

Publish a System's Resources as versioned packages, find the packages your team uses, and trace which Systems hold them. Methods are on V3Client.

  • A library is a named, access-controlled catalog of packages in your tenant. Members have the role reader, publisher, or maintainer, and each role includes the ones before it. An archived library stays readable but accepts no new versions.
  • A package is a named entry in a library, such as a set of models other Systems depend on.
  • A package version is one immutable release of a package: its files, release notes, dependencies, and marking (classification and control tags). Its lifecycle is active, yanked, or scrubbed.
  • A publication creates a package version, either from a package that a System branch's publications.yaml names or from loose Resource revisions.

Library, package, version, and file DTOs carry allowed_actions, a list of PackageAction values the caller may perform on that object: create_library, edit_library, archive_library, restore_library, delete_library, transfer_library, publish, manage_members, yank, restore, scrub, manage_control_tags, change_marking, download, open_source.

List calls page with cursor (pass the previous page's next_page), size (0–100; the server returns 50 when omitted), and include_total (set False to skip the count). Every call also takes http_request_timeout_secs (int, optional).

Capabilities​

get_package_capabilities()​

Reports whether packaging writes are on for this deployment and what the caller may do. GET /api/v3/package-capabilities.

  • Parameters:

    • http_request_timeout_secs (int, optional)

  • Return Type: PackageCapabilitiesDto — publishing_writes_enabled, resolution_writes_enabled, and allowed_actions.

Libraries​

list_libraries()​

Lists the libraries the caller may view, by key.

  • Parameters:

    • search (str, optional) – Case-insensitive search on library key or description.
    • archived (bool, optional) – List archived libraries instead of active ones.
    • cursor (str, optional)
    • size (int, optional)
    • include_total (bool, optional)
    • http_request_timeout_secs (int, optional)

  • Return Type: CursorPageLibraryDto

get_library()​

Returns one library the caller may view.

  • Parameters:

    • library_id (str) – (required)
    • http_request_timeout_secs (int, optional)

  • Return Type: LibraryDto

create_library()​

Creates a library in the caller's tenant. Tenant administrators only.

  • Parameters:

    • library_create_dto (LibraryCreateDto) – (required). key is required. Optional description (max 1024 characters), infosec_level_id, and owner_user_id.
    • http_request_timeout_secs (int, optional)

  • Return Type: LibraryDto

from istari_digital_client.v3.models import LibraryCreateDto

library = v3.create_library(
    LibraryCreateDto(key="{library_key}", description="{description}")
)

update_library()​

Changes a library's description, sharing, marking, or owner. Library stewards only. Fields you leave out keep their value. Send description or infosec_level_id as None to clear them; the other fields refuse None.

  • Parameters:

    • library_id (str) – (required)
    • library_update_dto (LibraryUpdateDto) – (required). Optional description (max 1024 characters), shared_with_tenant, control_tag_ids, infosec_level_id, and owner_user_id.
    • http_request_timeout_secs (int, optional)

  • Return Type: LibraryDto

preview_library_marking()​

Reports what giving the library a new marking would affect, without applying it. Only the library's stewards may call it.

  • Parameters:

    • library_id (str) – (required)
    • marking_dto (MarkingDto) – (required). Optional infosec_level_id and control_tag_ids. No classification and no tags leave the library open to its readers.
    • http_request_timeout_secs (int, optional)

  • Return Type: MarkingImpactDto — system_count and people_losing_access.

delete_library()​

Deletes a library that is empty or whose versions are all scrubbed. Library stewards only. Otherwise the call fails with 409.

  • Parameters:

    • library_id (str) – (required)
    • http_request_timeout_secs (int, optional)

  • Return Type: None

archive_library()​

Stops new publishing to a library. Its packages stay readable.

  • Parameters:

    • library_id (str) – (required)
    • http_request_timeout_secs (int, optional)

  • Return Type: LibraryDto

restore_library()​

Allows publishing to an archived library again.

  • Parameters:

    • library_id (str) – (required)
    • http_request_timeout_secs (int, optional)

  • Return Type: LibraryDto

Library members​

list_library_members()​

Lists the library's members and their roles.

  • Parameters:

    • library_id (str) – (required)
    • http_request_timeout_secs (int, optional)

  • Return Type: list of LibraryMembershipDto — user_id, role (LibraryRole), and owner.

set_library_members()​

Adds, changes, or removes members' roles in one change. Library stewards only. A change with role=None removes that member.

  • Parameters:

    • library_id (str) – (required)
    • library_membership_batch_update_dto (LibraryMembershipBatchUpdateDto) – (required). members is a list of 1 to 500 LibraryMembershipChangeDto, each with user_id and role (LibraryRole: reader, publisher, or maintainer).
    • http_request_timeout_secs (int, optional)

  • Return Type: list of LibraryMembershipDto

from istari_digital_client.v3.models import (
    LibraryMembershipBatchUpdateDto,
    LibraryMembershipChangeDto,
    LibraryRole,
)

v3.set_library_members(
    "{library_id}",
    LibraryMembershipBatchUpdateDto(
        members=[
            LibraryMembershipChangeDto(user_id="{user_id}", role=LibraryRole.PUBLISHER),
            LibraryMembershipChangeDto(user_id="{former_member_id}", role=None),
        ]
    ),
)

Packages​

list_packages()​

Lists packages in every library the caller may view, by key.

  • Parameters:

    • search (str, optional) – Case-insensitive search on package key.
    • published_from_revision_id (str, optional) – Only packages with a file from any revision of this revision's Resource.
    • cursor (str, optional)
    • size (int, optional)
    • include_total (bool, optional)
    • http_request_timeout_secs (int, optional)

  • Return Type: CursorPagePackageCatalogItemDto

list_library_packages()​

Lists the packages in one library.

  • Parameters:

    • library_id (str) – (required)
    • search (str, optional) – Case-insensitive search on package key.
    • sort_bys (list of str, optional) – Sort criteria as field | direction, where direction is asc or desc. The endpoint sorts by key (default) or published (latest version).
    • cursor (str, optional)
    • size (int, optional)
    • include_total (bool, optional)
    • http_request_timeout_secs (int, optional)

  • Return Type: CursorPagePackageCatalogItemDto

get_package()​

Returns one package the caller may open, with its newest_release.

  • Parameters:

    • package_id (str) – (required)
    • http_request_timeout_secs (int, optional)

  • Return Type: PackageDto

Package versions​

list_package_versions()​

Lists a package's versions, most recently published first.

  • Parameters:

    • package_id (str) – (required)
    • after (str, optional) – Only versions above this one.
    • through (str, optional) – Only versions up to and including this one.
    • cursor (str, optional)
    • size (int, optional)
    • include_total (bool, optional)
    • http_request_timeout_secs (int, optional)

  • Return Type: CursorPagePackageVersionDto

get_package_version()​

Returns one version the caller may open, including its lifecycle, marking, dependencies, and source.

  • Parameters:

    • version_id (str) – (required)
    • http_request_timeout_secs (int, optional)

  • Return Type: PackageVersionDto

preview_package_version_marking()​

Reports what giving the version a new marking would affect, without applying it. Only the package's stewards may call it.

  • Parameters:

    • version_id (str) – (required)
    • marking_dto (MarkingDto) – (required). Optional infosec_level_id and control_tag_ids.
    • http_request_timeout_secs (int, optional)

  • Return Type: MarkingImpactDto — system_count and people_losing_access.

set_package_version_marking()​

Replaces a published version's classification and control tags. Access changes at once.

  • Parameters:

    • version_id (str) – (required)
    • marking_dto (MarkingDto) – (required). Optional infosec_level_id and control_tag_ids.
    • http_request_timeout_secs (int, optional)

  • Return Type: PackageVersionDto

yank_package_version()​

Withdraws a version so updates no longer move to it. Systems that already hold it keep it.

  • Parameters:

    • version_id (str) – (required)
    • http_request_timeout_secs (int, optional)

  • Return Type: PackageVersionDto

scrub_package_version()​

Stops serving a version's content permanently. The version record stays. Repeat the version ID in the request body to confirm.

  • Parameters:

    • version_id (str) – (required)
    • package_scrub_request_dto (PackageScrubRequestDto) – (required). confirm_version_id must repeat version_id.
    • http_request_timeout_secs (int, optional)

  • Return Type: PackageVersionDto

from istari_digital_client.v3.models import PackageScrubRequestDto

v3.scrub_package_version(
    "{version_id}",
    PackageScrubRequestDto(confirm_version_id="{version_id}"),
)

restore_package_version()​

Makes a yanked version selectable by updates again.

  • Parameters:

    • version_id (str) – (required)
    • http_request_timeout_secs (int, optional)

  • Return Type: PackageVersionDto

Package files​

list_package_version_files()​

Lists the files the caller may view in one folder of a version: sub-folders with file counts first, then files.

  • Parameters:

    • version_id (str) – (required)
    • under (str, optional) – Folder to list. The version's root when empty.
    • recursive (bool, optional) – List every file under the folder, without sub-folders.
    • search (str, optional) – Only files whose path contains this string, ignoring case.
    • cursor (str, optional)
    • size (int, optional)
    • include_total (bool, optional)
    • http_request_timeout_secs (int, optional)

  • Return Type: CursorPagePackageVersionNodeDto — each PackageVersionNodeDto has kind, name, path, file_count, and, for files, file (PackageFileDto, whose id is the file_id the calls below take).

read_package_version_file()​

Returns the bytes of one package file the caller may view. It calls download_package_version_file() and fetches the short-lived link for you, so the link never reaches your code.

  • Parameters:

    • file_id (str) – (required)

  • Return Type: bytes

download_package_version_file()​

Returns a short-lived download link for one package file the caller may view.

  • Parameters:

    • file_id (str) – (required)
    • http_request_timeout_secs (int, optional)

  • Return Type: PackageDownloadDto — url and expires.

download_package_version_archive()​

Downloads a version's files as a zip, at their package paths, leaving out files withheld from the caller. The metadata sizes of the readable files must not exceed the deployment's archive limit (default 3 GiB); larger requests fail with 413.

  • Parameters:

    • version_id (str) – (required)
    • http_request_timeout_secs (int, optional)

  • Return Type: bytearray

get_package_file_provenance()​

Returns the Resource revision a package file was published from. The source is named only when the caller may view it.

  • Parameters:

    • file_id (str) – (required)
    • http_request_timeout_secs (int, optional)

  • Return Type: PackageFileProvenanceDto — kind, source_id, resource_id, and visible.

set_package_file_control_tags()​

Replaces a package file's control tags. Package stewards and publishers only.

  • Parameters:

    • file_id (str) – (required)
    • package_control_tags_dto (PackageControlTagsDto) – (required). control_tag_ids is the full list of tags to set.
    • http_request_timeout_secs (int, optional)

  • Return Type: PackageControlTagsDto

Publishing​

list_system_package_publications()​

Lists the packages published from a System, with their newest versions.

  • Parameters:

    • system_id (str) – (required)
    • cursor (str, optional)
    • size (int, optional)
    • include_total (bool, optional)
    • http_request_timeout_secs (int, optional)

  • Return Type: CursorPageSystemPackagePublicationDto

preview_package_publication()​

Works out what publishing would do without writing anything: the suggested version, the file and requirement counts, and what changed since the last version.

  • Parameters:

    • package_publication_dto (PackagePublicationDto) – (required). Same body as publish_package().
    • http_request_timeout_secs (int, optional)

  • Return Type: PackagePublicationPreviewDto — includes suggested_version, package_exists, file_count, requirement_count, changes, and warnings.

publish_package()​

Publishes a new version of a package. The call fails with 403, listing each missing permission, when the caller lacks one, and with 409 when the target conflicts with published versions, which cannot change.

  • Parameters:

    • package_publication_dto (PackagePublicationDto) – (required).
      • source (Source) – (required). Wraps one of:
        • SystemPublicationSourceDto – library, package, and branch_id. Publishes a package that the branch's publications.yaml names, at the branch head.
        • FilesPublicationSourceDto – library_id, package, revision_ids, and optional description (max 1024 characters). Publishes Resource revisions as a package, each file at its name in the package root.
      • version (str, optional) – Version to publish. Call preview_package_publication() to see the suggested version.
      • release_notes (str, optional) – Max 10,000 characters.
      • marking (MarkingDto, optional)
    • http_request_timeout_secs (int, optional)

  • Return Type: PackageVersionDto

from istari_digital_client.v3.models import (
    PackagePublicationDto,
    Source,
    SystemPublicationSourceDto,
)

publication = PackagePublicationDto(
    source=Source(
        SystemPublicationSourceDto(
            library="{library}",
            package="{package}",
            branch_id="{branch_id}",
        )
    ),
    release_notes="{release_notes}",
)

preview = v3.preview_package_publication(publication)
publication.version = preview.suggested_version
version = v3.publish_package(publication)

Consumers and lineage​

list_package_consuming_systems()​

Lists the System branches whose current resolution selects the package, one row per branch. The response has no total.

  • Parameters:

    • package_id (str) – (required)
    • version_id (str, optional) – Only branches that hold this version.
    • cursor (str, optional)
    • size (int, optional)
    • include_total (bool, optional)
    • http_request_timeout_secs (int, optional)

  • Return Type: CursorPagePackageConsumerDto — each PackageConsumerDto names the System, branch, and snapshot, the versions it holds, and whether the dependency is direct.

list_package_consumer_references()​

Lists every place a package is selected: one row per dependency of a current branch resolution, with the folder it installs into.

  • Parameters:

    • package_id (str) – (required)
    • system_id (str, optional) – Only places within this System.
    • cursor (str, optional)
    • size (int, optional)
    • include_total (bool, optional)
    • http_request_timeout_secs (int, optional)

  • Return Type: CursorPagePackageConsumerReferenceDto

list_package_lineage_commits()​

Lists a branch's commits that changed its packages or published versions, newest first, with the branch's head_snapshot_id.

  • Parameters:

    • system_id (str) – (required)
    • branch_id (str) – (required)
    • http_request_timeout_secs (int, optional)

  • Return Type: PackageLineageCommitsDto

get_package_lineage_of_system()​

Returns a graph of the packages a System branch head requires and the versions it published that other Systems' branch heads hold. Expanding a package draws the packages it requires; expanding a published version draws the Systems that hold it. The graph contains only what the caller may see.

  • Parameters:

    • system_id (str) – (required)
    • branch_id (str) – (required)
    • expanded (list of str, optional) – Node IDs from an earlier response to draw one step further. Each step draws up to 12 nodes and a more node; expanding the more node draws the next 12.
    • at (str, optional) – A snapshot the branch pointed at, from list_package_lineage_commits(). The branch head when absent.
    • http_request_timeout_secs (int, optional)

  • Return Type: PackageLineageGraphDto — focus, nodes, links, and summary.

get_package_lineage_of_version()​

Returns a graph of the versions a package version requires, the System it was published from, and the Systems whose branch heads hold it. Expanding a version draws the versions it requires.

  • Parameters:

    • version_id (str) – (required)
    • expanded (list of str, optional) – Node IDs from an earlier response to draw one step further, 12 nodes at a time.
    • http_request_timeout_secs (int, optional)

  • Return Type: PackageLineageGraphDto