openapi: 3.1.0 info: title: Apicurio Registry Admin Versions 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: Versions paths: /groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}: summary: Manage a single version of a single artifact 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 - 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 - name: versionExpression description: "An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:\n\n - If the expression is in the form \"branch={branchId}\", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.\n - Otherwise: The expression is resolved to a version with the same ID, which must follow the \"[a-zA-Z0-9._\\\\-+]{1,256}\" pattern." schema: type: string in: path required: true delete: tags: - Versions responses: '204': description: The artifact version was successfully deleted. '400': $ref: '#/components/responses/BadRequest' '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: deleteArtifactVersion summary: Delete artifact version description: "Deletes a single version of the artifact. Parameters `groupId`, `artifactId` and the unique `version`\nare needed. If this is the only version of the artifact, this operation is the same as \ndeleting the entire artifact.\n\nThis feature is disabled by default and it's discouraged for normal usage. To enable it, set the `registry.rest.artifact.deletion.enabled` property to true. This operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* No version with this `version` exists (HTTP error `404`)\n * Feature is disabled (HTTP error `405`)\n * A server error occurred (HTTP error `500`)\n" /groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/references: summary: Manage the references for a single version of an artifact 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 - 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 - name: versionExpression description: "An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:\n\n - If the expression is in the form \"branch={branchId}\", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.\n - Otherwise: The expression is resolved to a version with the same ID, which must follow the \"[a-zA-Z0-9._\\\\-+]{1,256}\" pattern." schema: type: string 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 required: false get: tags: - Versions responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/ArtifactReference' description: List of all the artifact references for this artifact. '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' operationId: getArtifactVersionReferences summary: Get artifact version references description: 'Retrieves all references for a single version of an artifact. Both the `artifactId` and the unique `version` number must be provided. Using the `refType` query parameter, it is possible to retrieve an array of either the inbound or outbound references. This operation can fail for the following reasons: * No artifact with this `artifactId` exists (HTTP error `404`) * No version with this `version` exists (HTTP error `404`) * A server error occurred (HTTP error `500`) ' /groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/references/graph: summary: Get a graph representation of artifact references. 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 - name: versionExpression description: An expression resolvable to a specific version ID within the given group and artifact. schema: type: string in: path required: true - name: direction description: The direction of references to include in the graph. Can be OUTBOUND (artifacts this version references), INBOUND (artifacts that reference this version), or BOTH. Defaults to OUTBOUND. schema: $ref: '#/components/schemas/ReferenceGraphDirection' in: query required: false - name: depth description: The maximum depth of the reference graph to traverse. Can be 1, 2, 3, or 0 for unlimited. Defaults to 3. schema: type: integer minimum: 0 maximum: 10 default: 3 in: query required: false get: tags: - Versions responses: '200': content: application/json: schema: $ref: '#/components/schemas/ReferenceGraph' description: A graph representation of all artifact references. '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' operationId: getArtifactVersionReferencesGraph summary: Get artifact version references as a graph description: 'Retrieves a graph representation of all references for a single version of an artifact. The graph includes nodes representing artifacts, edges representing references between them, and metadata about the graph structure including cycle detection. This operation can fail for the following reasons: * No artifact with this `artifactId` exists (HTTP error `404`) * No version with this `version` exists (HTTP error `404`) * A server error occurred (HTTP error `500`) ' /groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/comments: summary: Manage a collection of comments for an artifact version 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 - name: versionExpression description: "An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:\n\n - If the expression is in the form \"branch={branchId}\", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.\n - Otherwise: The expression is resolved to a version with the same ID, which must follow the \"[a-zA-Z0-9._\\\\-+]{1,256}\" pattern." schema: type: string in: path required: true get: tags: - Versions responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/Comment' description: List of all the comments for this artifact. '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' operationId: getArtifactVersionComments summary: Get artifact version comments description: 'Retrieves all comments for a version of an artifact. Both the `artifactId` and the unique `version` number must be provided. This operation can fail for the following reasons: * No artifact with this `artifactId` exists (HTTP error `404`) * No version with this `version` exists (HTTP error `404`) * A server error occurred (HTTP error `500`) ' post: requestBody: content: application/json: schema: $ref: '#/components/schemas/NewComment' required: true tags: - Versions responses: '200': content: application/json: schema: $ref: '#/components/schemas/Comment' description: The comment was successfully created. '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' operationId: addArtifactVersionComment summary: Add new comment description: 'Adds a new comment to the artifact version. Both the `artifactId` and the unique `version` number must be provided. This operation can fail for the following reasons: * No artifact with this `artifactId` exists (HTTP error `404`) * No version with this `version` exists (HTTP error `404`) * A server error occurred (HTTP error `500`) ' /groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/comments/{commentId}: summary: Manage a single comment 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 - name: versionExpression description: "An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:\n\n - If the expression is in the form \"branch={branchId}\", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.\n - Otherwise: The expression is resolved to a version with the same ID, which must follow the \"[a-zA-Z0-9._\\\\-+]{1,256}\" pattern." schema: type: string in: path required: true - name: commentId description: The unique identifier of a single comment. schema: type: string in: path required: true put: requestBody: content: application/json: schema: $ref: '#/components/schemas/NewComment' required: true tags: - Versions responses: '204': description: The value of the comment was successfully changed. '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' operationId: updateArtifactVersionComment summary: Update a comment description: "Updates the value of a single comment in an artifact version. Only the owner of the\ncomment can modify it. The `artifactId`, unique `version` number, and `commentId` \nmust be provided.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* No version with this `version` exists (HTTP error `404`)\n* No comment with this `commentId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" delete: tags: - Versions responses: '204': description: The comment was successfully deleted. '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' operationId: deleteArtifactVersionComment summary: Delete a single comment description: "Deletes a single comment in an artifact version. Only the owner of the\ncomment can delete it. The `artifactId`, unique `version` number, and `commentId` \nmust be provided.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* No version with this `version` exists (HTTP error `404`)\n* No comment with this `commentId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" /groups/{groupId}/artifacts/{artifactId}/versions: summary: Manage all the versions of an artifact 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 - 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 get: tags: - Versions parameters: - name: offset description: The number of versions to skip before starting to collect the result set. Defaults to 0. schema: type: integer in: query required: false - name: limit description: The number of versions to return. Defaults to 20. schema: 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` * `version` * `createdOn` ' schema: $ref: '#/components/schemas/VersionSortBy' in: query responses: '200': content: application/json: schema: $ref: '#/components/schemas/VersionSearchResults' description: List of all artifact versions. '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' operationId: listArtifactVersions summary: List artifact versions description: 'Returns a list of all versions of the artifact. The result set is paged. This operation can fail for the following reasons: * No artifact with this `artifactId` exists (HTTP error `404`) * A server error occurred (HTTP error `500`) ' post: requestBody: description: The version to be created. content: application/json: schema: $ref: '#/components/schemas/CreateVersion' required: true tags: - Versions parameters: - 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/VersionMetaData' description: The artifact version 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: createArtifactVersion summary: Create artifact version description: "Creates a new version of the artifact by uploading new content. The configured rules for\nthe artifact are applied, and if they all pass, the new content is added as the most recent \nversion of the artifact. If any of the rules fail, an error is returned.\n\nThe body of the request can be the raw content of the new artifact version, or the raw content \nand a set of references pointing to other artifacts, and the type\nof that content should match the artifact's type (for example if the artifact type is `AVRO`\nthen the content of the request should be an Apache Avro document).\n\nThis operation can fail for the following reasons:\n\n* Provided content (request body) was empty (HTTP error `400`)\n* An invalid version number was provided (HTTP error `400`)\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* The new content violates one of the rules configured for the artifact (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n" /groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/content: summary: Manage a single version of a single artifact 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 - 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 - name: versionExpression description: "An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:\n\n - If the expression is in the form \"branch={branchId}\", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.\n - Otherwise: The expression is resolved to a version with the same ID, which must follow the \"[a-zA-Z0-9._\\\\-+]{1,256}\" pattern." schema: type: string in: path required: true get: tags: - Versions parameters: - name: references description: Allows the user to specify how references in the content should be treated. schema: $ref: '#/components/schemas/HandleReferencesType' in: query responses: '200': $ref: '#/components/responses/ArtifactContent' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' operationId: getArtifactVersionContent summary: Get artifact version description: "Retrieves a single version of the artifact content. Both the `artifactId` and the\nunique `version` number must be provided. The `Content-Type` of the response depends \non the artifact type. In most cases, this is `application/json`, but for some types \nit may be different (for example, `PROTOBUF`).\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* No version with this `version` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" put: requestBody: description: The new artifact version content. content: application/json: schema: $ref: '#/components/schemas/VersionContent' required: true tags: - Versions responses: '204': description: The artifact version content was successfully updated. '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/ServerError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' operationId: updateArtifactVersionContent summary: Update artifact version content description: 'Updates the content of a single version of an artifact. NOTE: the artifact must be in `DRAFT` status. Both the `artifactId` and the unique `version` number must be provided to identify the version to update. This operation can fail for the following reasons: * No artifact with this `artifactId` exists (HTTP error `404`) * No version with this `version` exists (HTTP error `404`) * Artifact version not in `DRAFT` status (HTTP error `409`) * A server error occurred (HTTP error `500`) ' /groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/export: summary: Export a Protobuf artifact version with dependencies as a ZIP file. 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 - name: versionExpression description: An expression resolvable to a specific version ID within the given group and artifact. schema: type: string in: path required: true get: tags: - Versions responses: '200': description: The Protobuf artifact and its dependencies exported as a ZIP file with package-structured directories. content: application/zip: schema: type: string format: binary '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' operationId: exportArtifactVersion summary: Export artifact version as ZIP description: 'Exports a Protobuf artifact version with all its transitive dependencies as a ZIP file. The files in the ZIP are organized by their package names to match the expected directory structure for protoc compilation. Import statements are rewritten to use canonical package-based paths. This operation is only supported for PROTOBUF artifact types. This operation can fail for the following reasons: * No artifact with this `artifactId` exists (HTTP error `404`) * No version with this `version` exists (HTTP error `404`) * Artifact is not of type PROTOBUF (HTTP error `400`) * A server error occurred (HTTP error `500`) ' /search/versions: summary: Search for versions in the registry. get: tags: - Versions parameters: - name: version description: Filter by version number. schema: $ref: '#/components/schemas/Version' in: query - name: offset description: The number of versions 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 versions 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/VersionSortBy' 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: $ref: '#/components/schemas/GroupId' 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: $ref: '#/components/schemas/ArtifactId' in: query - name: name description: Filter by name. schema: type: string in: query - name: state description: Filter by version state. schema: $ref: '#/components/schemas/VersionState' in: query - name: artifactType description: Filter by artifact type (`AVRO`, `JSON`, etc). schema: $ref: '#/components/schemas/ArtifactType' in: query - name: content description: Full-text search of artifact content. Requires the Lucene search index to be enabled. schema: type: string in: query - name: structure description: 'Search by structured content elements (schemas, paths, fields, etc.) using a faceted format. Supports three formats: `type:kind:name` for exact match (e.g. `openapi:schema:Pet`), `kind:name` for cross-type match (e.g. `schema:Pet`), or just `name` for plain text search. Requires the Lucene search index to be enabled.' schema: type: string in: query responses: '200': content: application/json: schema: $ref: '#/components/schemas/VersionSearchResults' description: 'On a successful response, returns a result set of versions - one for each version in the registry that matches the criteria.' '500': $ref: '#/components/responses/ServerError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' operationId: searchVersions summary: Search for versions description: 'Returns a paginated list of all versions 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: - Versions 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 versions. schema: $ref: '#/components/schemas/ArtifactType' in: query - name: offset description: The number of versions 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 versions 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/VersionSortBy' in: query - name: groupId description: Filter by group Id. schema: $ref: '#/components/schemas/GroupId' in: query - name: artifactId description: Filter by artifact Id. schema: $ref: '#/components/schemas/ArtifactId' in: query responses: '200': content: application/json: schema: $ref: '#/components/schemas/VersionSearchResults' description: 'On a successful response, returns a result set of versions - one for each version 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: searchVersionsByContent summary: Search for versions by content description: 'Returns a paginated list of all versions that match 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`) ' /groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/render: summary: Render a prompt template artifact by substituting variables. 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 - name: versionExpression description: "An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:\n\n - If the expression is in the form \"branch={branchId}\", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.\n - Otherwise: The expression is resolved to a version with the same ID, which must follow the \"[a-zA-Z0-9._\\\\-+]{1,256}\" pattern." schema: type: string in: path required: true post: tags: - Versions requestBody: description: The variables to use for rendering the prompt template. content: application/json: schema: $ref: '#/components/schemas/RenderPromptRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/RenderPromptResponse' description: The rendered prompt template. '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' operationId: renderPromptTemplate summary: Render a prompt template description: 'Renders a prompt template artifact by substituting the provided variables into the template. The artifact must be of type `PROMPT_TEMPLATE`. Variables are validated against the template''s variable schema before rendering. This operation can fail for the following reasons: * No artifact with this `artifactId` exists (HTTP error `404`) * No version with this `version` exists (HTTP error `404`) * The artifact is not a PROMPT_TEMPLATE (HTTP error `400`) * Required variables are missing or have invalid types (HTTP error `400`) * A server error occurred (HTTP error `500`) ' /groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/state: summary: Manage the state of an artifact version. 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 - name: versionExpression description: "An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:\n\n - If the expression is in the form \"branch={branchId}\", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.\n - Otherwise: The expression is resolved to a version with the same ID, which must follow the \"[a-zA-Z0-9._\\\\-+]{1,256}\" pattern." schema: type: string in: path required: true get: tags: - Versions responses: '200': content: application/json: schema: $ref: '#/components/schemas/WrappedVersionState' description: The current artifact version state. '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' operationId: getArtifactVersionState summary: Get artifact version state description: 'Gets the current state of an artifact version. This operation can fail for the following reasons: * No artifact with this `artifactId` exists (HTTP error `404`) * No version with this `version` exists (HTTP error `404`) * A server error occurred (HTTP error `500`) ' put: requestBody: description: The new state. content: application/json: schema: $ref: '#/components/schemas/WrappedVersionState' required: true tags: - Versions parameters: - 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: '204': description: The state was successfully updated. '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/ServerError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' operationId: updateArtifactVersionState summary: Update the artifact version state description: "Updates the state of an artifact version.\n\nNOTE: There are some restrictions on state transitions. Notably a version \ncannot be transitioned to the `DRAFT` state from any other state. The `DRAFT` \nstate can only be entered (optionally) when creating a new artifact/version.\nA version in `DRAFT` state can only be transitioned to `ENABLED`. When this\nhappens, any configured content rules will be applied. This may result in a\nfailure to change the state.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* No version with this `version` exists (HTTP error `404`)\n* An invalid new state was provided (HTTP error `400`)\n* The draft content violates one or more of the rules configured for the artifact (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n" components: schemas: RenderPromptResponse: title: Root Type for RenderPromptResponse description: Response from rendering a prompt template. required: - rendered type: object properties: rendered: description: The rendered prompt with all variables substituted. type: string groupId: description: The group ID of the artifact. type: string artifactId: description: The artifact ID. type: string version: description: The version of the artifact that was rendered. type: string validationErrors: description: Any validation errors encountered when validating variables against the template schema. type: array items: $ref: '#/components/schemas/RenderValidationError' example: rendered: 'Style: concise Maximum length: 100 words Document: The quick brown fox jumps over the lazy dog.' groupId: default artifactId: summarization-v1 version: '1.2' validationErrors: [] 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 WrappedVersionState: title: Root Type for WrappedVersionState description: '' required: - state type: object properties: state: $ref: '#/components/schemas/VersionState' example: state: ENABLED Comment: title: Root Type for NewComment description: '' required: - owner - createdOn - value - commentId type: object properties: value: maxLength: 1024 type: string createdOn: format: date-time type: string owner: description: '' type: string commentId: description: '' type: string example: commentId: '12345' value: This is a comment on an artifact version. owner: bwayne createdOn: '2023-07-01T15:22:01Z' 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"' ReferenceType: description: '' enum: - OUTBOUND - INBOUND type: string example: '"INBOUND"' x-codegen-package: io.apicurio.registry.types VersionSearchResults: description: Describes the response received when searching for artifacts. required: - count - versions type: object properties: count: description: 'The total number of versions that matched the query (may be more than the number of versions returned in the result set).' type: integer versions: description: The collection of artifact versions returned in the result set. type: array items: $ref: '#/components/schemas/SearchedVersion' ReferenceGraphMetadata: title: Root Type for ReferenceGraphMetadata description: Metadata about the reference graph. type: object properties: totalNodes: description: The total number of nodes in the graph. type: integer totalEdges: description: The total number of edges in the graph. type: integer maxDepth: description: The maximum depth reached in the graph. type: integer hasCycles: description: Whether the graph contains circular references. type: boolean example: totalNodes: 5 totalEdges: 4 maxDepth: 3 hasCycles: false 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 ReferenceGraphDirection: description: The direction of references to include in the graph. enum: - OUTBOUND - INBOUND - BOTH type: string example: '"OUTBOUND"' 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"' ReferenceGraphEdge: title: Root Type for ReferenceGraphEdge description: An edge in the reference graph representing a reference from one artifact to another. required: - sourceNodeId - targetNodeId type: object properties: sourceNodeId: description: The ID of the source node (the artifact that has the reference). type: string targetNodeId: description: The ID of the target node (the artifact being referenced). type: string name: description: The name of the reference as defined in the source artifact. type: string example: sourceNodeId: node-1 targetNodeId: node-2 name: sample.proto 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: int32 description: The HTTP status code. type: integer instance: description: A URI reference that identifies the specific occurrence of the problem. type: string name: description: The name of the error (typically a server exception class name). type: string example: status: 500 name: NullPointerException title: An error occurred somewhere. HandleReferencesType: description: 'How to handle references when retrieving content. References can either be left unchanged (`PRESERVE`), re-written so they are valid in the context of the registry (`REWRITE`), or fully dereferenced such that all externally referenced content is internalized (`DEREFERENCE`).' enum: - PRESERVE - DEREFERENCE - REWRITE type: string RuleViolationProblemDetails: title: Root Type for Error description: 'All error responses, whether `4xx` or `5xx` will include one of these as the response body.' type: object allOf: - required: - causes type: object properties: causes: description: List of rule violation causes. type: array items: $ref: '#/components/schemas/RuleViolationCause' - $ref: '#/components/schemas/ProblemDetails' example: error_code: 409 message: Artifact failed validation causes: - description: API is missing a title context: /info[title] - description: Operation IDs must be unique context: /paths[/invoices]/put[operationId] x-codegen-extendsClass: io.apicurio.registry.rest.v3.beans.ProblemDetails VersionSortBy: description: '' enum: - groupId - artifactId - version - name - createdOn - modifiedOn - globalId type: string SortOrder: description: '' enum: - asc - desc type: string CreateVersion: description: '' required: - content type: object properties: version: $ref: '#/components/schemas/Version' description: '' content: $ref: '#/components/schemas/VersionContent' description: '' name: description: '' type: string description: description: '' type: string labels: $ref: '#/components/schemas/Labels' description: '' branches: description: '' type: array items: type: string isDraft: description: '' type: boolean example: version: 1.0.1 content: content: '{"type":"record","name":"ExampleType","fields":[{"name":"foo","type":"string"}]}' contentType: application/json name: Version 1.0.1 description: The latest version of this artifact. isDraft: false RuleViolationCause: title: Root Type for RuleViolationCause description: '' type: object properties: description: type: string context: type: string example: description: External documentation URL is not valid (it must be formatted as a URL). context: /info/externalDocs[url] RenderPromptRequest: title: Root Type for RenderPromptRequest description: Request body for rendering a prompt template with variable substitution. required: - variables type: object properties: variables: description: A map of variable names to their values. These will be substituted into the prompt template. type: object additionalProperties: {} example: variables: document: The quick brown fox jumps over the lazy dog. max_words: 100 style: concise RenderValidationError: title: Root Type for RenderValidationError description: A validation error encountered when validating template variables. required: - variableName - message type: object properties: variableName: description: The name of the variable that failed validation. type: string message: description: A description of the validation error. type: string expectedType: description: The expected type of the variable. type: string actualType: description: The actual type that was provided. type: string example: variableName: max_words message: Expected integer but got string expectedType: integer actualType: string SearchedVersion: description: Models a single artifact from the result set returned when searching for artifacts. required: - owner - createdOn - artifactType - state - globalId - version - contentId - artifactId 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: '' state: $ref: '#/components/schemas/VersionState' description: '' globalId: format: int64 description: '' type: integer version: $ref: '#/components/schemas/Version' description: '' contentId: format: int64 description: '' type: integer artifactId: $ref: '#/components/schemas/ArtifactId' description: '' groupId: $ref: '#/components/schemas/GroupId' description: '' modifiedBy: description: '' type: string modifiedOn: format: date-time description: '' type: string labels: $ref: '#/components/schemas/Labels' description: '' example: groupId: DemoGroup artifactId: demo-artifact-id name: Artifact Version Name description: Description of the artifact version artifactType: AVRO state: ENABLED createdOn: 2018-02-10T09:30Z owner: some text globalId: 37 version: 1.0.7 contentId: 62 ReferenceGraphNode: title: Root Type for ReferenceGraphNode description: A node in the reference graph representing an artifact version. required: - id - groupId - artifactId - version type: object properties: id: description: A unique identifier for this node within the graph. type: string groupId: description: The group ID of the artifact. type: string artifactId: description: The artifact ID. type: string version: description: The version of the artifact. type: string artifactType: description: The type of the artifact. type: string name: description: The name of the artifact version. type: string isRoot: description: Whether this node is the root node of the graph. type: boolean isCycleNode: description: Whether this node is part of a circular reference. type: boolean example: id: node-1 groupId: mygroup artifactId: my-artifact version: '1.0' artifactType: PROTOBUF name: My Artifact isRoot: false isCycleNode: false ReferenceGraph: title: Root Type for ReferenceGraph description: A graph representation of artifact references. required: - root - nodes - edges - metadata type: object properties: root: description: The root node of the graph (the artifact for which references were requested). $ref: '#/components/schemas/ReferenceGraphNode' nodes: description: All nodes in the graph, including the root. type: array items: $ref: '#/components/schemas/ReferenceGraphNode' edges: description: All edges (references) in the graph. type: array items: $ref: '#/components/schemas/ReferenceGraphEdge' metadata: description: Metadata about the graph structure. $ref: '#/components/schemas/ReferenceGraphMetadata' example: root: id: root groupId: mygroup artifactId: my-artifact version: '1.0' isRoot: true nodes: - id: root groupId: mygroup artifactId: my-artifact version: '1.0' isRoot: true - id: node-1 groupId: mygroup artifactId: referenced-artifact version: '2.0' isRoot: false edges: - sourceNodeId: root targetNodeId: node-1 name: common.proto metadata: totalNodes: 2 totalEdges: 1 maxDepth: 1 hasCycles: false NewComment: title: Root Type for NewComment description: '' required: - value type: object properties: value: type: string example: value: This is a new comment on an existing artifact version. VersionMetaData: title: Root Type for ArtifactVersionMetaData description: '' required: - createdOn - owner - version - artifactType - globalId - artifactId - contentId type: object properties: version: $ref: '#/components/schemas/Version' name: type: string description: type: string owner: type: string createdOn: format: date-time type: string artifactType: $ref: '#/components/schemas/ArtifactType' description: '' globalId: format: int64 description: '' type: integer state: $ref: '#/components/schemas/VersionState' description: '' labels: $ref: '#/components/schemas/Labels' description: '' groupId: $ref: '#/components/schemas/GroupId' description: '' contentId: format: int64 description: '' type: integer artifactId: $ref: '#/components/schemas/ArtifactId' description: '' modifiedBy: description: '' type: string modifiedOn: format: date-time description: '' type: string example: 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 responses: Forbidden: content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' examples: ForbiddenExample: value: detail: 'ForbiddenException: User is not authorized to perform this operation.' title: User is not authorized to perform this operation. status: 403 name: ForbiddenException description: Common response for all operations that can return a `403` error indicating the user is authenticated but not authorized. Unauthorized: content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' examples: UnauthorizedExample: value: detail: 'UnauthorizedException: User is not authenticated.' title: User is not authenticated. status: 401 name: UnauthorizedException description: Common response for all operations that can return a `401` error indicating authentication is required. Conflict: content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' examples: ConflictExample: value: error_code: 409 message: The artifact content was invalid. description: Common response used when an input conflicts with existing data. NotFound: content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' examples: NotFoundExample: value: error_code: 404 message: No artifact with id 'Topic-1/Inbound' could be found. description: Common response for all operations that can return a `404` error. ArtifactContent: headers: X-Registry-ArtifactType: schema: $ref: '#/components/schemas/ArtifactType' content: '*/*': schema: $ref: '#/components/schemas/FileContent' examples: OpenAPI: value: openapi: 3.0.2 info: title: Empty API version: 1.0.0 description: An example API design using OpenAPI. description: The content of one version of one artifact. RuleViolationConflict: content: application/json: schema: $ref: '#/components/schemas/RuleViolationProblemDetails' examples: RuleViolationConflictExample: value: error_code: 409 message: The artifact content was invalid causes: - description: API is missing a title context: /info[title] - description: Operation IDs must be unique context: /paths[/invoices]/put[operationId] description: Common response used when an input conflicts with existing data. ServerError: content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' examples: ErrorExample: value: error_code: 500 message: Lost connection to the database. description: Common response for all operations that can fail with an unexpected server error. BadRequest: content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' description: Common response for all operations that can return a `400` error. MethodNotAllowed: content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' examples: MethodNotAllowedExample: value: error_code: 405 message: Method is currently not supported or disabled. description: Common response for all operations that can fail due to method not allowed or disabled. UnprocessableEntity: content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' examples: UnprocessableEntityExample: value: error_code: 422 message: 'The artifact content is invalid: Schema validation failed' name: SchemaValidationException description: 'The artifact content is not valid for one of the following reasons: * Schema validation failed * References could not be validated * Required references are missing' securitySchemes: BasicAuth: type: http scheme: basic OAuth2: type: oauth2 flows: clientCredentials: tokenUrl: https://example.com/realms/apicurio/protocol/openid-connect/token scopes: read: Read access write: Write access admin: Admin access x-codegen: suppress-date-time-formatting: true bean-annotations: - io.quarkus.runtime.annotations.RegisterForReflection - annotation: lombok.experimental.SuperBuilder excludeEnums: true - annotation: lombok.AllArgsConstructor excludeEnums: true - annotation: lombok.NoArgsConstructor excludeEnums: true - annotation: lombok.EqualsAndHashCode excludeEnums: true - annotation: lombok.ToString(callSuper = true) excludeEnums: true