---
title: "Create artifact version"
method: POST
path: "/groups/{groupId}/artifacts/{artifactId}/versions"
tags: ["Versions"]
---

# Create artifact version

`POST /groups/{groupId}/artifacts/{artifactId}/versions`

Creates a new version of the artifact by uploading new content.  The configured rules for
the artifact are applied, and if they all pass, the new content is added as the most recent 
version of the artifact.  If any of the rules fail, an error is returned.

The body of the request can be the raw content of the new artifact version, or the raw content 
and a set of references pointing to other artifacts, and the type
of that content should match the artifact's type (for example if the artifact type is `AVRO`
then the content of the request should be an Apache Avro document).

This operation can fail for the following reasons:

* Provided content (request body) was empty (HTTP error `400`)
* An invalid version number was provided (HTTP error `400`)
* No artifact with this `artifactId` exists (HTTP error `404`)
* The new content violates one of the rules configured for the artifact (HTTP error `400`)
* A server error occurred (HTTP error `500`)

## Query parameters

- `dryRun` boolean

## Request body

- CreateVersion
  - `version` string — A single version of an artifact. Can be provided by the client when creating a new version, or it can be server-generated. The value can be any string unique to the artifact, but it is recommended to use a simple integer or a semver value.
  - `content` VersionContent, required
    - `content` string, required — Raw content of the artifact version or a valid (and accessible) URL where the content can be found.
    - `references` ArtifactReference[] — Collection of references to other artifacts.
      - `groupId` string, required
      - `artifactId` string, required
      - `version` string
      - `name` string, required
    - `contentType` string, required — The content-type, such as `application/json` or `text/xml`.
    - `encoding` 'base64' — Optional encoding for the content property. When set to 'base64', the content value will be base64-decoded by the server before processing.
  - `name` string
  - `description` string
  - `labels` Labels — User-defined name-value pairs. Name and value must be strings.
  - `branches` string[]
  - `isDraft` boolean

## Response `200`

The artifact version was successfully created.

- VersionMetaData
  - `version` string, required — A single version of an artifact. Can be provided by the client when creating a new version, or it can be server-generated. The value can be any string unique to the artifact, but it is recommended to use a simple integer or a semver value.
  - `name` string
  - `description` string
  - `owner` string, required
  - `createdOn` string, date-time, required
  - `artifactType` string, required
  - `globalId` integer, required
  - `state` 'ENABLED' | 'DISABLED' | 'DEPRECATED' | 'DRAFT' | 'SUNSET' — Describes the state of an artifact or artifact version. * ENABLED * DISABLED * DEPRECATED * DRAFT * SUNSET — Signals that a migration deadline has passed and the version will be removed. Requires transitioning through DEPRECATED first. Added in 3.3.0.
  - `labels` Labels — User-defined name-value pairs. Name and value must be strings.
  - `groupId` string — An ID of a single artifact group.
  - `contentId` integer, required
  - `artifactId` string, required — The ID of a single artifact.
  - `modifiedBy` string
  - `modifiedOn` string, date-time

## Other responses

- `400` — Common response used when the content of the request violates one or more configured rules.
- `401` — Common response for all operations that can return a `401` error indicating authentication is required.
- `403` — Common response for all operations that can return a `403` error indicating the user is authenticated but not authorized.
- `404` — Common response for all operations that can return a `404` error.
- `409` — Common response used when an input conflicts with existing data.
- `422` — The artifact content is not valid for one of the following reasons: * Schema validation failed * References could not be validated * Required references are missing
- `500` — Common response for all operations that can fail with an unexpected server error.

---

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