# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness Registry V3 - Versions API
  version: 1.0.0
extends: openapi/harness-registry-v3-versions-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 16
- target: $.paths['/har/api/v3/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List package versions in the artifact registry
      effect: read
      questions:
      - Which package versions are stored in my Harness Artifact Registry?
      - Can I list only the versions that were soft-deleted?
      - What versions of a given package were uploaded by a particular user?
      instructions:
      - text: List package versions in account {account}.
        slots:
          account: query.account_identifier
      - text: List versions of packages {packages} in registry {registry} for account {account}.
        slots:
          packages: query.package_ids
          registry: query.registry_ids
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/versions/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a package version
      effect: destructive
      questions:
      - How do I delete one version of a package from the registry?
      - Can I permanently remove a version rather than soft-deleting it?
      instructions:
      - text: Delete package version {version} in account {account}.
        slots:
          version: path.id
          account: query.account_identifier
      - text: Hard delete version {version} with force set to {force} in account {account}.
        slots:
          version: path.id
          force: query.force
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/versions/{id}/conan/recipe-revisions'].get
  update:
    x-apievangelist-phrasing:
      intent: List Conan recipe revisions for a version
      effect: read
      questions:
      - What Conan recipe revisions (RREVs) exist for this package version?
      - Can I page through finalized recipe revisions of a Conan version?
      instructions:
      - text: List Conan recipe revisions of version {version} in account {account}.
        slots:
          version: path.id
          account: query.account_identifier
      - text: Show page {page} of recipe revisions for Conan version {version} (account {account}).
        slots:
          page: query.page
          version: path.id
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/versions/{id}/conan/recipe-revisions/{recipe_revision_id}/details'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of a Conan recipe revision
      effect: read
      questions:
      - What's recorded about a specific Conan recipe revision?
      - Can I inspect one RREV of a Conan package version?
      instructions:
      - text: Get details of recipe revision {rrev} for version {version} in account {account}.
        slots:
          rrev: path.recipe_revision_id
          version: path.id
          account: query.account_identifier
      - text: Show the Conan RREV {rrev} under version {version} for account {account}.
        slots:
          rrev: path.recipe_revision_id
          version: path.id
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/versions/{id}/conan/recipe-revisions/{recipe_revision_id}/packages'].get
  update:
    x-apievangelist-phrasing:
      intent: List Conan packages under a recipe revision
      effect: read
      questions:
      - Which binary packages (PKGIDs) were built for a Conan recipe revision?
      - How many Conan packages sit under one recipe revision?
      instructions:
      - text: List packages under recipe revision {rrev} of version {version} in account {account}.
        slots:
          rrev: path.recipe_revision_id
          version: path.id
          account: query.account_identifier
      - text: Show the PKGIDs built for Conan recipe revision {rrev}, version {version}, account {account}.
        slots:
          rrev: path.recipe_revision_id
          version: path.id
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/versions/{id}/conan/recipe-revisions/{recipe_revision_id}/packages/{package_id}/details'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Conan package and its revisions
      effect: read
      questions:
      - What details and package revisions are attached to a specific Conan PKGID?
      - Can I look up one Conan binary package by its package ID?
      instructions:
      - text: Get details of Conan package {package} in recipe revision {rrev}, version {version}, account {account}.
        slots:
          package: path.package_id
          rrev: path.recipe_revision_id
          version: path.id
          account: query.account_identifier
      - text: Show PKGID {package} with its revisions for RREV {rrev} of version {version} (account {account}).
        slots:
          package: path.package_id
          rrev: path.recipe_revision_id
          version: path.id
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/versions/{id}/conan/recipe-revisions/{recipe_revision_id}/packages/{package_id}/package-revisions'].get
  update:
    x-apievangelist-phrasing:
      intent: List revisions of a Conan package
      effect: read
      questions:
      - What package revisions (PREVs) exist for a Conan binary package?
      - Can I page through the PREVs of one Conan PKGID?
      instructions:
      - text: List package revisions of {package} under RREV {rrev}, version {version}, account {account}.
        slots:
          package: path.package_id
          rrev: path.recipe_revision_id
          version: path.id
          account: query.account_identifier
      - text: Page through PREVs for Conan package {package} (RREV {rrev}, version {version}, account {account}).
        slots:
          package: path.package_id
          rrev: path.recipe_revision_id
          version: path.id
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/versions/{id}/conan/recipe-revisions/{recipe_revision_id}/packages/{package_id}/package-revisions/{package_revision_id}/details'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of a Conan package revision
      effect: read
      questions:
      - What's recorded for one specific Conan package revision (PREV)?
      - Can I drill all the way down to a single PREV of a Conan binary?
      instructions:
      - text: Get PREV {prev} of package {package}, RREV {rrev}, version {version} in account {account}.
        slots:
          prev: path.package_revision_id
          package: path.package_id
          rrev: path.recipe_revision_id
          version: path.id
          account: query.account_identifier
      - text: Show detail for Conan package revision {prev} under package {package} (RREV {rrev}, version {version}, account {account}).
        slots:
          prev: path.package_revision_id
          package: path.package_id
          rrev: path.recipe_revision_id
          version: path.id
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/versions/{id}/deployments'].get
  update:
    x-apievangelist-phrasing:
      intent: See where a package version is deployed
      effect: read
      questions:
      - Which environments and services are currently running this artifact version?
      - Is this version deployed to production, or only to non-prod environments?
      - Can I filter a version's deployments by a specific image tag?
      instructions:
      - text: List the deployments running version {version} in account {account}.
        slots:
          version: path.id
          account: query.account_identifier
      - text: Show {env_type} environments where version {version} is deployed (account {account}).
        slots:
          env_type: query.env_type
          version: path.id
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/versions/{id}/metadata'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the metadata of a package version
      effect: read
      questions:
      - What key-value metadata is attached to this package version?
      - Can I read all custom metadata on a registry version?
      instructions:
      - text: Get all metadata for version {version} in account {account}.
        slots:
          version: path.id
          account: query.account_identifier
      - text: Show the metadata labels on package version {version} for account {account}.
        slots:
          version: path.id
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/versions/{id}/metadata'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace all metadata on a package version
      effect: write
      questions:
      - How do I overwrite every metadata entry on a version with a fresh set?
      - Does replacing version metadata drop keys I leave out?
      instructions:
      - text: Replace all metadata on version {version} with {metadata} in account {account}.
        slots:
          version: path.id
          metadata: requestBody.metadata
          account: query.account_identifier
      - text: Wipe and reset the metadata of version {version} to {metadata} (account {account}).
        slots:
          version: path.id
          metadata: requestBody.metadata
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/versions/{id}/metadata'].post
  update:
    x-apievangelist-phrasing:
      intent: Add or update metadata keys on a version
      effect: write
      questions:
      - Can I add a new metadata key to a version without replacing the existing ones?
      - How do I set or overwrite individual metadata values on a package version?
      instructions:
      - text: Upsert metadata {metadata} onto version {version} in account {account}.
        slots:
          metadata: requestBody.metadata
          version: path.id
          account: query.account_identifier
      - text: Add or overwrite the keys {metadata} on package version {version} for account {account}.
        slots:
          metadata: requestBody.metadata
          version: path.id
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/versions/{id}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a soft-deleted package version
      effect: write
      questions:
      - Can I bring back a package version I soft-deleted by mistake?
      - How do I undelete a version in the artifact registry?
      instructions:
      - text: Restore soft-deleted version {version} in account {account}.
        slots:
          version: path.id
          account: query.account_identifier
      - text: Undelete package version {version} for account {account}.
        slots:
          version: path.id
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/versions/{id}/tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Add tags to an OCI package version
      effect: write
      questions:
      - How do I add extra tags to an existing container image version in the registry?
      - Which package types support adding tags to a version?
      instructions:
      - text: Add tags {tags} to version {version} in account {account}.
        slots:
          tags: requestBody.tags
          version: path.id
          account: query.account_identifier
      - text: Tag OCI image version {version} as {tags} for account {account}.
        slots:
          version: path.id
          tags: requestBody.tags
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/versions/rebuild-metadata'].post
  update:
    x-apievangelist-phrasing:
      intent: Rebuild metadata for every version in a registry
      effect: write
      questions:
      - Can I regenerate the metadata for all versions in a registry at once?
      - How do I trigger a registry-wide metadata rebuild?
      instructions:
      - text: Rebuild metadata for all versions in registry {registry}, account {account}.
        slots:
          registry: requestBody.registryId
          account: query.account_identifier
      - text: Trigger a full version metadata rebuild on registry {registry} (account {account}).
        slots:
          registry: requestBody.registryId
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/har/api/v3/versions/stats'].post
  update:
    x-apievangelist-phrasing:
      intent: Get download, size and scan stats for versions
      effect: read
      questions:
      - How many times have these package versions been downloaded, and how big are they?
      - What's the scan status for a batch of versions by UUID?
      instructions:
      - text: Get statistics for versions {versions} in account {account}.
        slots:
          versions: requestBody.versionIds
          account: query.account_identifier
      - text: Show download counts, file counts and scan status for versions {versions} (account {account}).
        slots:
          versions: requestBody.versionIds
          account: query.account_identifier
      method: generated
      generated: '2026-09-26'