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

# Create artifact version

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

## Request

- The document declares no server URL.
- Auth: none declared

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`)
* No artifact with this `artifactId` exists (HTTP error `404`)
* The new content violates one of the rules configured for the artifact (HTTP error `409`)
* A server error occurred (HTTP error `500`)

## Headers

- `X-Registry-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.
- `X-Registry-Name` string: Name of the artifact.
- `X-Registry-Description` string: Description of the artifact.
- `X-Registry-Description-Encoded` string: Base64 encoded description of the artifact.
- `X-Registry-Name-Encoded` string: Base64 encoded name of the artifact.

## Request body

- ArtifactContent
  - `content` string, required: Raw content of the artifact or a valid (and accessible) URL where the content can be found.
  - `references` ArtifactReference[], required: Collection of references to other artifacts.
    - `groupId` string, required
    - `artifactId` string, required
    - `version` string
    - `name` string, required

## Response `200`

The artifact version was successfully created.

- VersionMetaData
  - `version` string, required
  - `name` string
  - `description` string
  - `createdBy` string, required
  - `createdOn` string, date-time, required
  - `type` string, required
  - `globalId` integer, required
  - `state` 'ENABLED' | 'DISABLED' | 'DEPRECATED': Describes the state of an artifact or artifact version. The following states are possible: * ENABLED * DISABLED * DEPRECATED
  - `id` string, required: The ID of a single artifact.
  - `labels` string[]
  - `properties` Properties: User-defined name-value pairs. Name and value must be strings.
  - `groupId` string: An ID of a single artifact group.
  - `contentId` integer, required

## Other responses

- `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.
- `500`: Common response for all operations that can fail with an unexpected server error.

## Changes

> 65 revisions in range; 1 not diffed.

- **2023-02-02** (v2) `5152639bee96`: 2 info
  - added the media type `application/vnd.create.extended+json` to the request body
  - the request's body type was generalized from no type to `string`, and format from no format to `binary`
- **2022-11-24** (v2) `29b79a1c2c74`: 10 info
  - removed the `ASYNCAPI` enum value from the `type` response property for the response status `200`
  - removed the `AVRO` enum value from the `type` response property for the response status `200`
  - removed the `GRAPHQL` enum value from the `type` response property for the response status `200`
  - removed the `JSON` enum value from the `type` response property for the response status `200`
  - …6 more
- **2022-04-25** (v2) `d1a3061ccc48`: 1 info
  - the request's body type was generalized from `string` to no type, and format from `binary` to no format
- **2022-04-01** (v2) `79156695de01`: 1 info
  - added the media type `application/create.extended+json` to the request body
- **2021-07-26** (v2) `12cf6280cd02`: 4 info
  - added the new optional `header` request parameter `X-Registry-Description`
  - added the new optional `header` request parameter `X-Registry-Description-Encoded`
  - added the new optional `header` request parameter `X-Registry-Name`
  - added the new optional `header` request parameter `X-Registry-Name-Encoded`

[Operation history](https://skmtc.dev/apicurio/apis/apicurio-registry-api-v2/changes/groups/:groupId/artifacts/:artifactId/versions/post.md)

---

[API](https://skmtc.dev/apicurio/apis/apicurio-registry-api-v2.md) - [All operations](https://skmtc.dev/apicurio/apis/apicurio-registry-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/apicurio/apis/apicurio-registry-api-v2/revisions/8c48f413fa1f?raw)