---
title: "Import an artifact from a registry, repository or URL"
canonical: "https://admiral.io/docs/api/components/RegistryAPI_ImportComponent"
---

# Import an artifact from a registry, repository or URL

`POST https://api.admiral.io/v1/components/import`

Scope: `component:publish`

### Request body

- `name` (string): Empty means the artifact's own name: the chart's, the module's, the repository's or directory's. Pattern `^([a-z]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63.
- `source` (ImportSource, required): ImportSource names an artifact to import. One variant. The kind of the resulting component follows from it: a chart from OCI or a Helm repository, a module from a module registry, whatever inspection finds in a git tree or an archive.
  - At most one of `archive`, `git_tree`, `helm_chart`, `oci_chart`, `registry_module` is set.
  - `archive` (Archive): An archive at a URL, unpacked by its extension.
    - `url` (string (uri), required): Length at most 512.
  - `git_tree` (GitTree): A git repository at a ref, optionally a directory of it.
    - `url` (string (uri), required): `https://github.com/acme/infra.git`, `ssh://git@github.com/acme/infra.git`. Length at most 512.
    - `ref` (string): A branch, tag or commit. Empty is the default branch. Length at most 256.
    - `path` (string): A directory within the repository. Empty is the root. string.not_contains = ".." Length at most 512.
  - `helm_chart` (HelmChart): A chart in an HTTP repository: the repository URL, the chart's name in its index, and an exact version.
    - `repository` (string (uri), required): Length at most 512.
    - `chart` (string, required): Pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$`. Length at most 63.
    - `version` (string, required): Pattern `^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$`.
  - `oci_chart` (OCIChart): A chart in an OCI registry: `oci://ghcr.io/argoproj/argo-helm/argo-cd` at a version, which is its tag.
    - `reference` (string, required): string.prefix = "oci://" Length 7 to 512.
    - `version` (string, required): Pattern `^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$`.
  - `registry_module` (RegistryModule): A module in a module registry: the address as a module call would write it (`GoogleCloudPlatform/cloud-armor/google`, optionally host-qualified, optionally `//subdir`) and an exact version. A range is what a Source tracks, not what an import takes.
    - `address` (string, required): Length 5 to 512.
    - `version` (string, required): Pattern `^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$`.
- `credential_ids` (array of string): The credentials this import may present, chosen by the caller. Each is presented only where its type fits and its `allowed_hosts` permit. A fetch that reaches a host none of them covers fails naming the host. Items at most 16.
- `tags` (array of string): Tags to set on the resulting version. A chart's version and a module's version are applied as tags whether or not named. Items at most 16.
- `description` (string): Applied when the import creates the component; ignored otherwise. Length at most 1024.
- `labels` (map of string to string)
- `baseline_values_json` (string): The organization's defaults for this artifact, as a JSON object: values laid over the artifact's own defaults (a chart's values.yaml, a module's variable defaults) before any environment's values. Stored with the artifact as one version under one digest, so changing them is a new version, which environments move to like any other. Empty means the artifact's own defaults. Length at most 1048576.

### Response 200

Success

- `component` (Component): Component is a registry entry: a name, and the versions and tags beneath it.
  - `id` (string): Unique identifier. Pattern `^cmp-[0-9a-z]+$`. Read-only.
  - `name` (string): Unique within the tenant, never changed: `cloud-sql`. Team grouping, when it lands, is a `team/` segment of the name (`payments/cloud-sql`); moving a component means publishing under the new name and deprecating the old one with it as the successor. Read-only.
  - `description` (string): Length at most 1024.
  - `labels` (map of string to string): Key-value metadata for filtering (e.g. `{"team": "payments", "runtime": "terraform"}`), the same labels every Admiral resource carries.
  - `tags` (array of Tag): Every tag on the component, by name. Read-only.
    - `name` (string): As written after the colon in `cloud-sql:v1.2.0`. Read-only.
    - `digest` (string): The version it names, as `sha256:<hex>`. Read-only.
    - `immutable` (boolean): True for a semver tag: it never moves once assigned. Decided from the name, so two tags with the same name are always the same class. Read-only.
    - `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.
    - `updated_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.
  - `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.
  - `updated_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.
  - `status` (Status): Status is whether a component is still recommended. Removing one is DeleteComponent. One of `STATUS_UNSPECIFIED`, `STATUS_ACTIVE`, `STATUS_DEPRECATED`. Read-only.
  - `status_reason` (string): Why, and when, the status last changed. Unset on a component that has only ever been ACTIVE. Read-only.
  - `status_changed_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.
  - `successor_component_id` (string): The component to use instead, `cmp-`; set only while DEPRECATED. Read-only.
- `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_IMPORT`.
    - `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 IMPORT: which secret reached which hosts. Lineage, not a grant; a later import 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 import.
    - `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.
- `unchanged` (boolean): The resolution was already published under this name; nothing was written.