---
title: "Retrieve a version"
canonical: "https://admiral.io/docs/api/components/RegistryAPI_GetVersion"
---

# Retrieve a version

`GET https://api.admiral.io/v1/components/{component_id}/versions/{reference}`

Scope: `component:read`

### Path parameters

- `component_id` (string, required): The component_id path parameter. Pattern `^cmp-[0-9a-z]+$`.
- `reference` (string, required): A tag (`v1.2.0`, `latest`), a digest (`sha256:<hex>`) or a version id (`ver-…`). A digest and an id are recognised by their prefix; anything else is a tag, and no tag starts with `ver-`. Pattern `^(sha256:[0-9a-f]{64}|ver-[0-9a-z]+|[A-Za-z0-9][A-Za-z0-9._+-]{0,127})$`. Length 1 to 128.

### Response 200

Success

- `version` (Version): Version is one published artifact. Immutable except for its status.
  - `id` (string): `ver-` and twelve base36 characters. A change set holds it beside the digest, which is the identity of the bytes. Pattern `^ver-[0-9a-z]+$`. Read-only.
  - `component_id` (string): The component this version belongs to, `cmp-`. Read-only.
  - `digest` (string): The identity: SHA-256 of the normalized bundle, as `sha256:<hex>`. Read-only.
  - `kind` (ComponentKind): ComponentKind is what a version's bundle is, detected by inspection at publish: a Chart.yaml means HELM, .tf files mean TERRAFORM, anything else that is Kubernetes YAML means MANIFESTS. One of `COMPONENT_KIND_UNSPECIFIED`, `COMPONENT_KIND_TERRAFORM`, `COMPONENT_KIND_HELM`, `COMPONENT_KIND_MANIFESTS`. Read-only.
  - `size_bytes` (string (int64)): Size of the stored bundle in bytes. Read-only.
  - `contract` (Contract): The inputs and outputs the bundle exposes. Inferred from the bundle at publish; curated by a publisher once the contract format lands. Read-only.
    - `inputs` (array of ContractInput)
      - `name` (string)
      - `type` (string): The type as the bundle declares it: a Terraform type expression, or for a chart one of bool, number, string, list, object or null. A chart's full constraint is in schema.
      - `description` (string)
      - `required` (boolean): True when the bundle gives it no default.
      - `default` (Value): The declared default, when there is one.
      - `sensitive` (boolean): The bundle marks the value sensitive: it is masked in artifacts and review, as GetArtifact describes.
      - `ephemeral` (boolean): The value must not land in plan or state (Terraform 1.10+ ephemeral inputs). Implies sensitive.
      - `nullable` (boolean): Whether null is an accepted value. Unset when the bundle does not say, which is a chart input with no schema.
      - `deprecated` (string): The bundle's own deprecation message for this input.
      - `validations` (array of ContractValidation): A Terraform variable's validation blocks, in declaration order.
        - `condition` (string)
        - `error_message` (string)
      - `schema` (map of string to Value): The JSON Schema a chart's values.schema.json declares for this input, verbatim, so a value can be checked the way Helm will check it.
    - `outputs` (array of ContractOutput)
      - `name` (string)
      - `description` (string)
      - `sensitive` (boolean)
  - `provenance` (Provenance): Where the bytes came from. Read-only.
    - `kind` (Kind): Kind is the on-ramp a version arrived by: whose code it is and who triggered the publish, not which way the bytes travelled. One of `KIND_UNSPECIFIED`, `KIND_PUSH`, `KIND_PULL`.
    - `uri` (string): The repository or location the bytes were read from: a git remote URL, a Helm repository URL, an OCI reference. For a push, as the publisher reported it; empty when it named no remote.
    - `ref` (string): The ref that was asked for (tag, branch, chart version), when any.
    - `commit` (string): What the ref resolved to: a commit SHA, or the exact chart version.
    - `path` (string): The path within the source the bundle was taken from. Empty means the root.
    - `dependencies` (array of Dependency): Every remote module or chart the closure step copied into the bundle, at what it resolved to.
      - `source` (string): The source as the bundle declared it, before rewriting.
      - `constraint` (string): The constraint that was asked for, when any.
      - `resolved` (string): What it resolved to: an exact version or commit.
    - `credentials` (array of PresentedCredential): The credentials the platform presented while fetching, for PULL: which secret reached which hosts. Lineage, not a grant; a later pull attaches its own. Set by the server; ignored on a publish request. Read-only.
      - `id` (string): Pattern `^cred-[0-9a-z]+$`.
      - `name` (string)
      - `hosts` (array of string): The hosts it was presented to during this pull.
    - `commit_message` (string): The message of the commit that produced these bytes, as written, so a reader deciding whether to move to this version can see what changed. Captured at publish because it cannot be recovered after a force-push or once the source is gone. Empty when there is no commit, or upstream carried no notes. Length at most 4096.
    - `commit_author` (string): Who wrote that commit, by name. Not the email address. Length at most 256.
  - `findings` (array of Finding): What the publish gate found. Informational findings do not block a publish; a version with findings is published with them attached, and the findings delta between two versions is what an upgrade review reads. Read-only.
    - `severity` (FindingSeverity): FindingSeverity ranks what the publish gate found. One of `FINDING_SEVERITY_UNSPECIFIED`, `FINDING_SEVERITY_INFO`, `FINDING_SEVERITY_LOW`, `FINDING_SEVERITY_MEDIUM`, `FINDING_SEVERITY_HIGH`, `FINDING_SEVERITY_CRITICAL`.
    - `source` (string): What produced it: `provider-constraint`, `checkov`, `trivy`, `image-ref`.
    - `code` (string): The producer's own identifier for the rule, when it has one (e.g. `CKV_AWS_18`).
    - `message` (string)
    - `path` (string): Where in the bundle, when it applies.
  - `status` (Status): Status is a version's lifecycle. There is no deleted state. One of `STATUS_UNSPECIFIED`, `STATUS_PUBLISHED`, `STATUS_DEPRECATED`, `STATUS_REVOKED`. Read-only.
  - `status_changed_at` (Timestamp): When and why the status last changed. Unset on a version that has only ever been PUBLISHED. Read-only.
  - `status_reason` (string): Read-only.
  - `tags` (array of string): The tags currently naming this version. Read-only.
  - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this. Read-only.
    - `id` (string): The actor's typed id: a `usr-` user id or an `sa-` service account id.
    - `display_name` (string): Human-readable name (e.g., "John Smith", "deploy-bot").
    - `email` (string): Email address (empty for non-human actors).
  - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only.
  - `providers` (array of string): The Terraform providers the bundle's root and vendored modules require, as `namespace/type` addresses without a registry host, read offline at publish. Empty for a Kubernetes component. A provider some agent in the tenant serves is a need: adding the component, setting its version or settings, or changing an assignment is refused unless the plan and apply profiles serve every need. Read-only.
  - `baseline_values_json` (string): The organization's defaults stored with this version, as a JSON object; empty when there are none. The contract's defaults already include them. Read-only.