Sign in

v51

latestOpenAPI 3.0.3Apache 2.0raw.githubusercontent.com2026-08-01131107332.8 KB
Artifacts

Create artifact

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.

post/groups/{groupId}/artifacts

Query parameters

ifExists'FAIL' | 'CREATE_VERSION' | 'FIND_OR_CREATE_VERSION'

Set this option to instruct the server on what to do if the artifact already exists.

canonicalboolean

Used only when the ifExists query parameter is set to RETURN_OR_UPDATE, this parameter can be set to true to indicate that the server should "canonicalize" the content when searching for a matching version. The canonicalization algorithm is unique to each artifact type, but typically involves removing extra whitespace and formatting the content in a consistent manner.

dryRunboolean

When set to true, the operation will not result in any changes. Instead, it will return a result based on whether the operation would have succeeded.

Request body

artifactIdstring required

The ID of a single artifact.

artifactTypestring
namestring
descriptionstring
labelsLabels

User-defined name-value pairs. Name and value must be strings.

Example request

{
  "artifactId": "mytopic-value",
  "artifactType": "AVRO",
  "name": "Invoice",
  "description": "A standard Acme invoice payload.",
  "labels": {
    "label-1": "value-1",
    "label-2": "value-2"
  },
  "firstVersion": {
    "version": "1.0.0",
    "content": {
      "content": "{\"type\":\"record\",\"name\":\"ExampleType\",\"fields\":[{\"name\":\"sdfgfsdgsdg\",\"type\":\"string\"}]}",
      "contentType": "application/json",
      "references": []
    },
    "name": "ExampleType",
    "description": "A simple example of an Avro type.",
    "labels": {}
  }
}

Response

Artifact was successfully created.

Example response

{
  "artifact": {
    "groupId": "My-Group",
    "artifactId": "Procurement-Invoice",
    "name": "Artifact Name",
    "description": "Description of the artifact",
    "artifactType": "AVRO",
    "owner": "user1",
    "createdOn": "2019-03-22T12:51:19Z",
    "modifiedBy": "user2",
    "modifiedOn": "2019-07-19T15:09:00Z",
    "labels": {
      "custom-1": "foo",
      "custom-2": "bar"
    }
  },
  "version": {
    "groupId": "My-Group",
    "artifactId": "my-artifact-id",
    "version": 1221432,
    "artifactType": "PROTOBUF",
    "name": "Artifact Name",
    "description": "The description of the artifact",
    "owner": "user1",
    "createdOn": "2019-05-17T12:00:00Z",
    "globalId": 183282932983,
    "contentId": 12347,
    "labels": {
      "custom-1": "foo",
      "custom-2": "bar"
    }
  }
}