---
title: "Register a new Artefact Version with your organization."
method: POST
path: "/orgs/{orgId}/artefact-versions"
tags: ["public", "ArtefactVersion"]
---

# Register a new Artefact Version with your organization.

`POST /orgs/{orgId}/artefact-versions`

## Path parameters

- `orgId` string, required

## Query parameters

- `vcs` string
- `dry_run` boolean

## Headers

- `Accept` string

## Request body

- union — The details of a new Artefact Version to register. The type field is required and dictates the type of Artefact to register.
  - object — Details for creating a new Container Artefact Version
    - `type` string, required — The Artefact Version type.
    - `name` string, required — The Artefact name.
    - `version` string — (Optional) The Artefact Version.
    - `ref` string — (Optional) The ref the Artefact Version was built from.
    - `commit` string — (Optional) The commit ID the Artefact Version was built on.
    - `digest` string — (Optional) The Artefact Version digest.
  - object — Details for creating a new Workload Artefact Version
    - `type` string, required — The Artefact Version type.
    - `name` string, required — The Artefact name.
    - `version` string — (Optional) The Artefact Version.
    - `ref` string — (Optional) The ref the Artefact Version was built from.
    - `commit` string — (Optional) The commit ID the Artefact Version was built on.
    - `spec` object, required — A Json object containing the workload specification. Score v1b1 is expected.
    - `image` string — An optional default image to assign to any containers in the workload that do not have an image set or whose image is '.'
    - `overrides` object — An optional Json object containing the workload overrides. Score v1b1 is expected.
    - `property_overrides` object — An optional set of path overrides that will be applied to the workload.
    - `resource_type_aliases` object — An optional set of resource types overrides that will be applied in the deployment set.
    - `extensions` ScoreHumanitecExtensions — Humanitec workload extensions for the Workload Artefact Version. These can be used to override the profile, or workload module spec and resource attributes.
      - `apiVersion` string, required — The api version describing the format of the extensions.
      - `profile` string — An optional override for the workload profile
      - `spec` object — A map of additional workload spec fields that will be merged.
      - `deploy` object — An optional deploy condition for the workload.
        - `when` 'before' | 'deploy' | 'after' — The stage the deployment should occur. "deploy", deployed in-parallel with other workloads (the default). "before", deployed before other workloads. "after", deployed after other workloads.
        - `success` 'deploy' | 'available' | 'complete' — The success criteria for the deployment. "deploy", workload deployed. "available", workload available. "complete", workload complete (often used with jobs).
        - `timeout` integer — The timeout in seconds for the deployment to reach it's success condition.

## Response `200`

An Artefact Version.

- union — The details of an Artefact Version. The type field dictates the type of Artefact along with any additional fields.
  - object — Details of a Container Artefact Version
    - `type` string, required — The Artefact Version type.
    - `archived` boolean, required — If the Artefact Version is archived.
    - `artefact_id` string, required — The UUID of the Artefact.
    - `commit` string, required — (Optional) The commit ID the Artefact Version was built on.
    - `created_at` string — The time when the Artefact Version was added to Humanitec.
    - `created_by` string — The user ID of the user who added the Artefact Version to Humanitec.
    - `id` string, required — The UUID of the Artefact Version.
    - `name` string, required — The name of the Artefact.
    - `ref` string, required — (Optional) The ref the Artefact Version was built from.
    - `updated_at` string — The time when the Artefact Version was updated for the last time.
    - `updated_by` string — The user ID of the user who performed the last updated on the Artefact Version.
    - `version` string — (Optional) The version of the Artefact Version.
    - `digest` string, required — (Optional) The Artefact Version digest.
  - object — Details of a Workload Artefact Version
    - `type` string, required — The Artefact Version type.
    - `archived` boolean, required — If the Artefact Version is archived.
    - `artefact_id` string, required — The UUID of the Artefact.
    - `commit` string — (Optional) The commit ID the Artefact Version was built on.
    - `created_at` string — The time when the Artefact Version was added to Humanitec.
    - `created_by` string — The user ID of the user who added the Artefact Version to Humanitec.
    - `id` string, required — The UUID of the Artefact Version.
    - `name` string, required — The name of the Artefact.
    - `ref` string — (Optional) The ref the Artefact Version was built from.
    - `updated_at` string — The time when the Artefact Version was updated for the last time.
    - `updated_by` string — The user ID of the user who performed the last updated on the Artefact Version.
    - `version` string — (Optional) The version of the Artefact Version.

## Other responses

- `204` — The request was valid, but no Artefact Version was created.
- `400` — Either one or more request body parameters are missing or invalid, or the requested payload is not provided or malformed.
- `401` — Request unauthorised.

---

[API](https://skmtc.net/humanitec/apis/humanitec-api.md) · [All operations](https://skmtc.net/humanitec/apis/humanitec-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/humanitec/humanitec-api/revisions/e21ad140ec3c/schema)