---
title: "Create artifact"
method: POST
path: "/groups/{groupId}/artifacts"
tags: ["Artifacts"]
---

# Create artifact

`POST /groups/{groupId}/artifacts`

Creates a new artifact by posting the artifact content.  The body of the request should
be the raw content of the artifact.  This is typically in JSON format for *most* of the 
supported types, but may be in another format for a few (for example, `PROTOBUF`).

The registry attempts to figure out what kind of artifact is being added from the
following supported list:

* Avro (`AVRO`)
* Protobuf (`PROTOBUF`)
* JSON Schema (`JSON`)
* Kafka Connect (`KCONNECT`)
* OpenAPI (`OPENAPI`)
* AsyncAPI (`ASYNCAPI`)
* GraphQL (`GRAPHQL`)
* Web Services Description Language (`WSDL`)
* XML Schema (`XSD`)

Alternatively, you can specify the artifact type using the `X-Registry-ArtifactType` 
HTTP request header, or include a hint in the request's `Content-Type`.  For example:

```
Content-Type: application/json; artifactType=AVRO
```

An artifact is created using the content provided in the body of the request.  This
content is created under a unique artifact ID that can be provided in the request
using the `X-Registry-ArtifactId` request header.  If not provided in the request,
the server generates a unique ID for the artifact.  It is typically recommended
that callers provide the ID, because this is typically a meaningful identifier, 
and for most use cases should be supplied by the caller.

If an artifact with the provided artifact ID already exists, the default behavior
is for the server to reject the content with a 409 error.  However, the caller can
supply the `ifExists` query parameter to alter this default behavior. The `ifExists`
query parameter can have one of the following values:

* `FAIL` (*default*) - server rejects the content with a 409 error
* `UPDATE` - server updates the existing artifact and returns the new metadata
* `RETURN` - server does not create or add content to the server, but instead 
returns the metadata for the existing artifact
* `RETURN_OR_UPDATE` - server returns an existing **version** that matches the 
provided content if such a version exists, otherwise a new version is created

This operation may fail for one of the following reasons:

* An invalid `ArtifactType` was indicated (HTTP error `400`)
* No `ArtifactType` was indicated and the server could not determine one from the content (HTTP error `400`)
* Provided content (request body) was empty (HTTP error `400`)
* An artifact with the provided ID already exists (HTTP error `409`)
* The content violates one of the configured global rules (HTTP error `409`)
* A server error occurred (HTTP error `500`)

## Query parameters

- `ifExists` 'FAIL' | 'UPDATE' | 'RETURN' | 'RETURN_OR_UPDATE'
- `canonical` boolean

## Headers

- `X-Registry-ArtifactType` string
- `X-Registry-ArtifactId` string
- `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-Description` string — Description of the artifact.
- `X-Registry-Description-Encoded` string — Base64 encoded description of the artifact.
- `X-Registry-Name` string — Name of the artifact.
- `X-Registry-Name-Encoded` string — Base64 encoded name of the artifact.
- `X-Registry-Content-Hash` string
- `X-Registry-Hash-Algorithm` 'SHA256' | 'MD5'

## Response `200`

Artifact was successfully created.

- ArtifactMetaData
  - `name` string
  - `description` string
  - `createdBy` string, required
  - `createdOn` string, date-time, required
  - `modifiedBy` string, required
  - `modifiedOn` string, date-time, required
  - `id` string, required — The ID of a single artifact.
  - `version` string, required
  - `type` string, required
  - `globalId` integer, required
  - `state` 'ENABLED' | 'DISABLED' | 'DEPRECATED', required — Describes the state of an artifact or artifact version. The following states are possible: * ENABLED * DISABLED * DEPRECATED
  - `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
  - `references` ArtifactReference[]
    - `groupId` string, required
    - `artifactId` string, required
    - `version` string
    - `name` string, required

## Other responses

- `400` — Common response for all operations that can return a `400` error.
- `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.
- `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.

---

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