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

# Create artifact

`POST /groups/{groupId}/artifacts`

Creates a new artifact.  The body of the request should be a `CreateArtifact` 
object, which includes the metadata of the new artifact and, optionally, the 
metadata and content of the first version.

If the artifact type is not provided, 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`)

An artifact will be created using the unique artifact ID that can optionally be 
provided in the request body.  If not provided in the request, the server will
generate a unique ID for the artifact.  It is typically recommended that callers
provide the ID, because it is typically a meaningful identifier, and as such
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
* `CREATE_VERSION` - server creates a new version of the existing artifact and returns it
* `FIND_OR_CREATE_VERSION` - 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 invalid version number was used for the optional included first version (HTTP error `400`)
* The group does not exist and automatic-group-creation is not enabled (HTTP error `404`)
* An artifact with the provided ID already exists (HTTP error `409`)
* The content violates one of the configured global rules (HTTP error `400`)
* A server error occurred (HTTP error `500`)

Note that if the `dryRun` query parameter is set to `true`, then this operation
will not actually make any changes.  Instead it will succeed or fail based on 
whether it **would have worked**.  Use this option to, for example, check if an
artifact is valid or if a new version passes configured compatibility checks.

## Query parameters

- `ifExists` 'FAIL' | 'CREATE_VERSION' | 'FIND_OR_CREATE_VERSION'
- `canonical` boolean
- `dryRun` boolean

## Request body

- CreateArtifact — Data sent when creating a new artifact.
  - `artifactId` string, required — The ID of a single artifact.
  - `artifactType` string
  - `name` string
  - `description` string
  - `labels` Labels — User-defined name-value pairs. Name and value must be strings.
  - `firstVersion` 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`

Artifact was successfully created.

- CreateArtifactResponse
  - `artifact` ArtifactMetaData, required
    - `name` string
    - `description` string
    - `owner` string, required
    - `createdOn` string, date-time, required
    - `modifiedBy` string, required
    - `modifiedOn` string, date-time, required
    - `artifactType` string, required
    - `labels` Labels — User-defined name-value pairs. Name and value must be strings.
    - `groupId` string, required — An ID of a single artifact group.
    - `artifactId` string, required — The ID of a single artifact.
    - `contractMetadata` ContractMetadata — Contract metadata for an artifact.
      - `status` 'DRAFT' | 'STABLE' | 'DEPRECATED' — The contract lifecycle status.
      - `ownerTeam` string — The team that owns the contract.
      - `ownerDomain` string — The domain the contract belongs to.
      - `supportContact` string — Support contact email.
      - `classification` 'PUBLIC' | 'INTERNAL' | 'CONFIDENTIAL' | 'RESTRICTED' — Data classification level.
      - `stage` 'DEV' | 'STAGE' | 'PROD' — Promotion stage.
      - `stableDate` string — ISO-8601 date when contract became stable.
      - `deprecatedDate` string — ISO-8601 date when contract was deprecated.
      - `deprecationReason` string — Reason for deprecation.
      - `compatibilityGroup` string — Compatibility group for schema evolution scoping.
  - `version` 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)