Apicurio Artifacts API
The Artifacts API from Apicurio — 9 operation(s) for artifacts.
OpenAPI Specification
openapi: 3.1.0
info:
title: Apicurio Registry Admin Artifacts API
version: 3.1.x
description: Apicurio Registry is a high-performance, runtime registry for schemas and API designs. It stores and manages OpenAPI, AsyncAPI, Avro, JSON Schema, Protobuf, and other artifact types, providing a REST API for schema management with compatibility checking and content versioning.
contact:
name: Apicurio
url: https://www.apicur.io/
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:8080/apis/registry/v3
description: Local Apicurio Registry
tags:
- name: Artifacts
paths:
/ids/globalIds/{globalId}:
summary: Access artifact content utilizing an artifact version's globally unique identifier.
parameters:
- name: globalId
description: Global identifier for an artifact version.
schema:
format: int64
type: integer
in: path
required: true
get:
tags:
- Artifacts
parameters:
- name: references
description: Allows the user to specify how references in the content should be treated.
schema:
$ref: '#/components/schemas/HandleReferencesType'
in: query
- name: returnArtifactType
description: 'When set to `true`, the HTTP response will include a header named `X-Registry-ArtifactType`
that contains the type of the artifact being returned.'
schema:
type: boolean
in: query
responses:
'200':
$ref: '#/components/responses/ArtifactContent'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: getContentByGlobalId
summary: Get artifact by global ID
description: 'Gets the content for an artifact version in the registry using its globally unique
identifier.
This operation may fail for one of the following reasons:
* No artifact version with this `globalId` exists (HTTP error `404`)
* A server error occurred (HTTP error `500`)
'
/search/artifacts:
summary: Search for artifacts in the registry.
get:
tags:
- Artifacts
parameters:
- name: name
description: Filter by artifact name.
schema:
type: string
in: query
- name: offset
description: The number of artifacts to skip before starting to collect the result set. Defaults to 0.
schema:
default: 0
type: integer
in: query
required: false
- name: limit
description: The number of artifacts to return. Defaults to 20.
schema:
default: 20
type: integer
in: query
required: false
- name: order
description: Sort order, ascending (`asc`) or descending (`desc`).
schema:
$ref: '#/components/schemas/SortOrder'
in: query
- name: orderby
description: 'The field to sort by. Can be one of:
* `name`
* `createdOn`
'
schema:
$ref: '#/components/schemas/ArtifactSortBy'
in: query
- name: labels
description: 'Filter by one or more name/value label. Separate each name/value pair using a colon. For
example `labels=foo:bar` will return only artifacts with a label named `foo`
and value `bar`.'
schema:
type: array
items:
type: string
in: query
- name: description
description: Filter by description.
schema:
type: string
in: query
- name: groupId
description: Filter by artifact group.
schema:
type: string
in: query
- name: globalId
description: Filter by globalId.
schema:
format: int64
type: integer
in: query
- name: contentId
description: Filter by contentId.
schema:
format: int64
type: integer
in: query
required: false
- name: artifactId
description: Filter by artifactId.
schema:
type: string
in: query
- name: artifactType
description: Filter by artifact type (`AVRO`, `JSON`, etc).
schema:
$ref: '#/components/schemas/ArtifactType'
in: query
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ArtifactSearchResults'
description: 'On a successful response, returns a result set of artifacts - one for each artifact
in the registry that matches the criteria.'
'500':
$ref: '#/components/responses/ServerError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: searchArtifacts
summary: Search for artifacts
description: 'Returns a paginated list of all artifacts that match the provided filter criteria.
This operation can fail for the following reasons:
* A server error occurred (HTTP error `500`)
'
post:
requestBody:
description: The content to search for.
content:
'*/*':
schema:
$ref: '#/components/schemas/FileContent'
required: true
tags:
- Artifacts
parameters:
- name: canonical
description: Parameter that can be set to `true` to indicate that the server should "canonicalize" the content when searching for matching artifacts. Canonicalization is unique to each artifact type, but typically involves removing any extra whitespace and formatting the content in a consistent manner. Must be used along with the `artifactType` query parameter.
schema:
type: boolean
in: query
- name: artifactType
description: Indicates the type of artifact represented by the content being used for the search. This is only needed when using the `canonical` query parameter, so that the server knows how to canonicalize the content prior to searching for matching artifacts.
schema:
$ref: '#/components/schemas/ArtifactType'
in: query
- name: groupId
description: Filter by artifact group.
schema:
type: string
in: query
- name: offset
description: The number of artifacts to skip before starting to collect the result set. Defaults to 0.
schema:
default: 0
type: integer
in: query
required: false
- name: limit
description: The number of artifacts to return. Defaults to 20.
schema:
default: 20
type: integer
in: query
required: false
- name: order
description: Sort order, ascending (`asc`) or descending (`desc`).
schema:
$ref: '#/components/schemas/SortOrder'
in: query
- name: orderby
description: 'The field to sort by. Can be one of:
* `name`
* `createdOn`
'
schema:
$ref: '#/components/schemas/ArtifactSortBy'
in: query
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ArtifactSearchResults'
description: 'On a successful response, returns a result set of artifacts - one for each artifact
in the registry that matches the criteria.'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/ServerError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: searchArtifactsByContent
summary: Search for artifacts by content
description: 'Returns a paginated list of all artifacts with at least one version that matches the
posted content.
This operation can fail for the following reasons:
* Provided content (request body) was empty (HTTP error `400`)
* A server error occurred (HTTP error `500`)
'
/ids/contentIds/{contentId}/references:
parameters:
- name: contentId
description: Global identifier for a single artifact content.
schema:
format: int64
type: integer
in: path
required: true
get:
tags:
- Artifacts
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ArtifactReference'
description: A list containing all the references for the artifact with the given content id.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: referencesByContentId
summary: List artifact references by content ID
description: 'Returns a list containing all the artifact references using the artifact content ID.
This operation may fail for one of the following reasons:
* A server error occurred (HTTP error `500`)'
/ids/globalIds/{globalId}/references:
parameters:
- name: globalId
description: Global identifier for an artifact version.
schema:
format: int64
type: integer
in: path
required: true
- name: refType
description: Determines the type of reference to return, either INBOUND or OUTBOUND. Defaults to OUTBOUND.
schema:
$ref: '#/components/schemas/ReferenceType'
in: query
get:
tags:
- Artifacts
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ArtifactReference'
description: A list containing all the references for the artifact with the given global id.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: referencesByGlobalId
summary: List artifact references by global ID
description: 'Returns a list containing all the artifact references using the artifact global ID.
This operation may fail for one of the following reasons:
* A server error occurred (HTTP error `500`)'
/groups/{groupId}/artifacts:
summary: Manage the collection of artifacts within a single group in the registry.
parameters:
- name: groupId
description: The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.
schema:
$ref: '#/components/schemas/GroupId'
in: path
required: true
get:
tags:
- Artifacts
parameters:
- name: limit
description: The number of artifacts to return. Defaults to 20.
schema:
type: integer
in: query
- name: offset
description: The number of artifacts to skip before starting the result set. Defaults to 0.
schema:
type: integer
in: query
- name: order
description: Sort order, ascending (`asc`) or descending (`desc`).
schema:
$ref: '#/components/schemas/SortOrder'
in: query
- name: orderby
description: 'The field to sort by. Can be one of:
* `name`
* `createdOn`
'
schema:
$ref: '#/components/schemas/ArtifactSortBy'
in: query
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ArtifactSearchResults'
description: On a successful response, returns a bounded set of artifacts.
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: listArtifactsInGroup
summary: List artifacts in group
description: Returns a list of all artifacts in the group. This list is paged.
post:
requestBody:
description: The artifact being created.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateArtifact'
required: true
tags:
- Artifacts
parameters:
- name: ifExists
description: Set this option to instruct the server on what to do if the artifact already exists.
schema:
$ref: '#/components/schemas/IfArtifactExists'
in: query
- name: canonical
description: 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.
schema:
type: boolean
in: query
- name: dryRun
description: '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**.'
schema:
type: boolean
in: query
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateArtifactResponse'
description: Artifact was successfully created.
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/RuleViolationConflict'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'500':
$ref: '#/components/responses/ServerError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: createArtifact
summary: Create artifact
description: "Creates a new artifact. The body of the request should be a `CreateArtifact` \nobject, which includes the metadata of the new artifact and, optionally, the \nmetadata and content of the first version.\n\nIf the artifact type is not provided, the registry attempts to figure out what \nkind of artifact is being added from the\nfollowing supported list:\n\n* Avro (`AVRO`)\n* Protobuf (`PROTOBUF`)\n* JSON Schema (`JSON`)\n* Kafka Connect (`KCONNECT`)\n* OpenAPI (`OPENAPI`)\n* AsyncAPI (`ASYNCAPI`)\n* GraphQL (`GRAPHQL`)\n* Web Services Description Language (`WSDL`)\n* XML Schema (`XSD`)\n\nAn artifact will be created using the unique artifact ID that can optionally be \nprovided in the request body. If not provided in the request, the server will\ngenerate a unique ID for the artifact. It is typically recommended that callers\nprovide the ID, because it is typically a meaningful identifier, and as such\nfor most use cases should be supplied by the caller.\n\nIf an artifact with the provided artifact ID already exists, the default behavior\nis for the server to reject the content with a 409 error. However, the caller can\nsupply the `ifExists` query parameter to alter this default behavior. The `ifExists`\nquery parameter can have one of the following values:\n\n* `FAIL` (*default*) - server rejects the content with a 409 error\n* `CREATE_VERSION` - server creates a new version of the existing artifact and returns it\n* `FIND_OR_CREATE_VERSION` - server returns an existing **version** that matches the \nprovided content if such a version exists, otherwise a new version is created\n\nThis operation may fail for one of the following reasons:\n\n* An invalid `ArtifactType` was indicated (HTTP error `400`)\n* No `ArtifactType` was indicated and the server could not determine one from the content (HTTP error `400`)\n* Provided content (request body) was empty (HTTP error `400`)\n* An invalid version number was used for the optional included first version (HTTP error `400`)\n* The group does not exist and automatic-group-creation is not enabled (HTTP error `404`)\n* An artifact with the provided ID already exists (HTTP error `409`)\n* The content violates one of the configured global rules (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n\nNote that if the `dryRun` query parameter is set to `true`, then this operation\nwill not actually make any changes. Instead it will succeed or fail based on \nwhether it **would have worked**. Use this option to, for example, check if an\nartifact is valid or if a new version passes configured compatibility checks."
delete:
tags:
- Artifacts
responses:
'204':
description: When the delete operation is successful, a simple 204 is returned.
'500':
$ref: '#/components/responses/ServerError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: deleteArtifactsInGroup
summary: Delete artifacts in group
description: Deletes all of the artifacts that exist in a given group.
/ids/contentHashes/{contentHash}/references:
parameters:
- name: contentHash
description: SHA-256 content hash for a single artifact content.
schema:
type: string
in: path
required: true
get:
tags:
- Artifacts
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ArtifactReference'
description: A list containing all the references for the artifact with the given content hash.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: referencesByContentHash
summary: List artifact references by hash
description: 'Returns a list containing all the artifact references using the artifact content hash.
This operation may fail for one of the following reasons:
* A server error occurred (HTTP error `500`)
'
/ids/contentHashes/{contentHash}:
summary: Access artifact content utilizing the SHA-256 hash of the content.
parameters:
- name: contentHash
description: SHA-256 content hash for a single artifact content.
schema:
type: string
in: path
required: true
get:
tags:
- Artifacts
responses:
'200':
$ref: '#/components/responses/ArtifactContent'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: getContentByHash
summary: Get artifact content by SHA-256 hash
description: "Gets the content for an artifact version in the registry using the \nSHA-256 hash of the content. This content hash may be shared by multiple artifact\nversions in the case where the artifact versions have identical content.\n\nThis operation may fail for one of the following reasons:\n\n* No content with this `contentHash` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n"
/ids/contentIds/{contentId}:
summary: Access artifact content utilizing the unique content identifier for that content.
parameters:
- name: contentId
description: Global identifier for a single artifact content.
schema:
format: int64
type: integer
in: path
required: true
get:
tags:
- Artifacts
responses:
'200':
$ref: '#/components/responses/ArtifactContent'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: getContentById
summary: Get artifact content by ID
description: 'Gets the content for an artifact version in the registry using the unique content
identifier for that content. This content ID may be shared by multiple artifact
versions in the case where the artifact versions are identical.
This operation may fail for one of the following reasons:
* No content with this `contentId` exists (HTTP error `404`)
* A server error occurred (HTTP error `500`)
'
/groups/{groupId}/artifacts/{artifactId}:
summary: Manage a single artifact.
parameters:
- name: groupId
description: The artifact group ID. Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.
schema:
$ref: '#/components/schemas/GroupId'
in: path
required: true
- name: artifactId
description: The artifact ID. Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.
schema:
$ref: '#/components/schemas/ArtifactId'
in: path
required: true
delete:
tags:
- Artifacts
responses:
'204':
description: Returned when the artifact was successfully deleted.
'404':
$ref: '#/components/responses/NotFound'
'405':
$ref: '#/components/responses/MethodNotAllowed'
'500':
$ref: '#/components/responses/ServerError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
operationId: deleteArtifact
summary: Delete artifact
description: 'Deletes an artifact completely, resulting in all versions of the artifact also being
deleted. This may fail for one of the following reasons:
* No artifact with the `artifactId` exists (HTTP error `404`)
* A server error occurred (HTTP error `500`)'
components:
schemas:
CreateArtifact:
description: Data sent when creating a new artifact.
required:
- artifactId
type: object
properties:
artifactId:
$ref: '#/components/schemas/ArtifactId'
description: ''
artifactType:
$ref: '#/components/schemas/ArtifactType'
description: ''
name:
description: ''
type: string
description:
description: ''
type: string
labels:
$ref: '#/components/schemas/Labels'
description: ''
firstVersion:
$ref: '#/components/schemas/CreateVersion'
description: ''
example:
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: {}
ContractMetadata:
title: ContractMetadata
description: Contract metadata for an artifact.
type: object
properties:
status:
description: The contract lifecycle status.
type: string
enum:
- DRAFT
- STABLE
- DEPRECATED
ownerTeam:
description: The team that owns the contract.
type: string
ownerDomain:
description: The domain the contract belongs to.
type: string
supportContact:
description: Support contact email.
type: string
classification:
description: Data classification level.
type: string
enum:
- PUBLIC
- INTERNAL
- CONFIDENTIAL
- RESTRICTED
stage:
description: Promotion stage.
type: string
enum:
- DEV
- STAGE
- PROD
stableDate:
description: ISO-8601 date when contract became stable.
type: string
deprecatedDate:
description: ISO-8601 date when contract was deprecated.
type: string
deprecationReason:
description: Reason for deprecation.
type: string
compatibilityGroup:
description: Compatibility group for schema evolution scoping.
type: string
FileContent:
format: binary
type: string
x-codegen-inline: true
Version:
description: '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.'
pattern: ^[a-zA-Z0-9._\-+]{1,256}$
type: string
example: '"3.1.6"'
Labels:
description: User-defined name-value pairs. Name and value must be strings.
type: object
additionalProperties:
type: string
x-codegen-inline: true
x-codegen-type: StringMap
ArtifactMetaData:
title: Root Type for ArtifactMetaData
description: ''
required:
- artifactId
- owner
- createdOn
- modifiedBy
- modifiedOn
- artifactType
- groupId
type: object
properties:
name:
type: string
description:
type: string
owner:
type: string
createdOn:
format: date-time
type: string
modifiedBy:
type: string
modifiedOn:
format: date-time
type: string
artifactType:
$ref: '#/components/schemas/ArtifactType'
description: ''
labels:
$ref: '#/components/schemas/Labels'
description: ''
groupId:
$ref: '#/components/schemas/GroupId'
description: ''
artifactId:
$ref: '#/components/schemas/ArtifactId'
description: ''
contractMetadata:
$ref: '#/components/schemas/ContractMetadata'
description: Contract metadata projected from the artifact labels. Only present when data contracts are enabled and contract labels exist.
example:
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
IfArtifactExists:
description: ''
enum:
- FAIL
- CREATE_VERSION
- FIND_OR_CREATE_VERSION
type: string
ArtifactReference:
title: Root Type for ArtifactReference
description: A reference to a different artifact. Typically used with artifact types that can have dependencies like Protobuf.
required:
- artifactId
- groupId
- name
type: object
properties:
groupId:
type: string
artifactId:
type: string
version:
type: string
name:
type: string
example:
groupId: mygroup
artifactId: 13842090-2ce3-11ec-8d3d-0242ac130003
version: '2'
name: foo.bar.Open
GroupId:
description: An ID of a single artifact group.
pattern: ^.{1,512}$
type: string
example: '"my-group"'
SearchedArtifact:
description: Models a single artifact from the result set returned when searching for artifacts.
required:
- owner
- createdOn
- artifactId
- artifactType
- groupId
- modifiedBy
- modifiedOn
type: object
properties:
name:
description: ''
type: string
description:
description: ''
type: string
createdOn:
format: date-time
description: ''
type: string
owner:
description: ''
type: string
artifactType:
$ref: '#/components/schemas/ArtifactType'
description: ''
modifiedOn:
format: date-time
description: ''
type: string
modifiedBy:
description: ''
type: string
groupId:
$ref: '#/components/schemas/GroupId'
description: ''
artifactId:
$ref: '#/components/schemas/ArtifactId'
description: ''
labels:
$ref: '#/components/schemas/Labels'
description: ''
example:
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-04-01T12:51:19Z'
ReferenceType:
description: ''
enum:
- OUTBOUND
- INBOUND
type: string
example: '"INBOUND"'
x-codegen-package: io.apicurio.registry.types
VersionContent:
description: ''
required:
- content
- contentType
type: object
properties:
content:
description: Raw content of the artifact version or a valid (and accessible) URL where the content can be found.
type: string
example: ''
references:
description: Collection of references to other artifacts.
type: array
items:
$ref: '#/components/schemas/ArtifactReference'
contentType:
description: The content-type, such as `application/json` or `text/xml`.
type: string
encoding:
description: Optional encoding for the content property. When set to 'base64', the content value will be base64-decoded by the server before processing.
type: string
enum:
- base64
ArtifactType:
description: ''
type: string
example: AVRO
x-codegen-package: io.apicurio.registry.types
VersionState:
description: '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.
'
enum:
- ENABLED
- DISABLED
- DEPRECATED
- DRAFT
- SUNSET
type: string
x-codegen-package: io.apicurio.registry.types
ArtifactId:
description: The ID of a single artifact.
pattern: ^.{1,512}$
type: string
example: '"example-artifact"'
ProblemDetails:
title: Root Type for Error
description: 'All error responses, whether `4xx` or `5xx` will include one of these as the response
body.'
required:
- title
- status
type: object
properties:
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
type:
description: A URI reference [RFC3986] that identifies the problem type.
type: string
title:
description: A short, human-readable summary of the problem type.
type: string
status:
format:
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apicurio/refs/heads/main/openapi/apicurio-artifacts-api-openapi.yml