{ "openapi": "3.0.3", "info": { "title": "Apicurio Registry API [v3]", "version": "3.3.x", "description": "Apicurio Registry is a datastore for standard event schemas and API designs. Apicurio Registry enables developers to manage and share the structure of their data using a REST interface. For example, client applications can dynamically push or pull the latest updates to or from the registry without needing to redeploy. Apicurio Registry also enables developers to create rules that govern how registry content can evolve over time. For example, this includes rules for content validation and version compatibility.\n\nThe Apicurio Registry REST API enables client applications to manage the artifacts in the registry. This API provides create, read, update, and delete operations for schema and API artifacts, rules, versions, and metadata. \n\nThe supported artifact types include:\n- Apache Avro schema\n- AsyncAPI specification\n- Google protocol buffers\n- GraphQL schema\n- JSON Schema\n- Kafka Connect schema\n- OpenAPI specification\n- Web Services Description Language\n- XML Schema Definition\n\n\n**Important**: The Apicurio Registry REST API is available from `https://MY-REGISTRY-URL/apis/registry/v3` by default. Therefore you must prefix all API operation paths with `/apis/registry/v3` in this case. For example: `/apis/registry/v3/ids/globalIds/{globalId}`.\n", "contact": { "name": "Apicurio", "url": "https://github.com/apicurio/apicurio-registry", "email": "apicurio@lists.jboss.org" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" } }, "paths": { "/ids/globalIds/{globalId}": { "summary": "Access artifact content utilizing an artifact version's globally unique identifier.", "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`\nthat 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\nidentifier.\n\nThis operation may fail for one of the following reasons:\n\n* No artifact version with this `globalId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "parameters": [ { "name": "globalId", "description": "Global identifier for an artifact version.", "schema": { "format": "int64", "type": "integer" }, "in": "path", "required": true } ] }, "/admin/rules": { "summary": "Manage the global rules that apply to all artifacts if not otherwise configured.", "get": { "tags": [ "Global rules", "Admin" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RuleType" } } } }, "description": "The list of names of the globally configured rules." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "listGlobalRules", "summary": "List global rules", "description": "Gets a list of all the currently configured global rules (if any).\n\nThis operation can fail for the following reasons:\n\n* A server error occurred (HTTP error `500`)\n" }, "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRule" } } }, "required": true }, "tags": [ "Global rules", "Admin" ], "responses": { "204": { "description": "The global rule was added." }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "createGlobalRule", "summary": "Create global rule", "description": "Adds a rule to the list of globally configured rules.\n\nThis operation can fail for the following reasons:\n\n* The rule type is unknown (HTTP error `400`)\n* The rule already exists (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n" }, "delete": { "tags": [ "Global rules", "Admin" ], "responses": { "204": { "description": "All global rules have been removed successfully." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "deleteAllGlobalRules", "summary": "Delete all global rules", "description": "Deletes all globally configured rules.\n\nThis operation can fail for the following reasons:\n\n* A server error occurred (HTTP error `500`)\n" } }, "/admin/rules/{ruleType}": { "summary": "Manage the configuration of a single global artifact rule.", "get": { "tags": [ "Global rules", "Admin" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } }, "description": "The global rule's configuration." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getGlobalRuleConfig", "summary": "Get global rule configuration", "description": "Returns information about the named globally configured rule.\n\nThis operation can fail for the following reasons:\n\n* Invalid rule name/type (HTTP error `400`)\n* No rule with name/type `rule` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "put": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } }, "required": true }, "tags": [ "Global rules", "Admin" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } }, "description": "The global rule's configuration was successfully updated." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "updateGlobalRuleConfig", "summary": "Update global rule configuration", "description": "Updates the configuration for a globally configured rule.\n\nThis operation can fail for the following reasons:\n\n* Invalid rule name/type (HTTP error `400`)\n* No rule with name/type `rule` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "delete": { "tags": [ "Global rules", "Admin" ], "responses": { "204": { "description": "The global rule was successfully deleted." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "deleteGlobalRule", "summary": "Delete global rule", "description": "Deletes a single global rule. If this is the only rule configured, this is the same\nas deleting **all** rules.\n\nThis operation can fail for the following reasons:\n\n* Invalid rule name/type (HTTP error `400`)\n* No rule with name/type `rule` exists (HTTP error `404`)\n* Rule cannot be deleted (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n" }, "parameters": [ { "name": "ruleType", "description": "The unique name/type of a rule.", "schema": { "$ref": "#/components/schemas/RuleType" }, "in": "path", "required": true } ] }, "/system/info": { "summary": "Retrieve system information", "get": { "tags": [ "System" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemInfo" } } }, "description": "On success, returns the system information." }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "getSystemInfo", "summary": "Get system information", "description": "This operation retrieves information about the running registry system, such as the version\nof the software and when it was built." } }, "/search/artifacts": { "summary": "Search for artifacts in the registry.", "get": { "tags": [ "Search", "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:\n\n* `name`\n* `createdOn`\n", "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\nexample `labels=foo:bar` will return only artifacts with a label named `foo`\nand 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" }, { "name": "skipCount", "description": "Indicates whether to skip the total count query. When true, the total count is not computed and count will be 0 in the response. This can improve performance for large datasets.", "schema": { "default": false, "type": "boolean" }, "in": "query", "required": false } ], "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\nin 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.\n\nThis operation can fail for the following reasons:\n\n* A server error occurred (HTTP error `500`)\n" }, "post": { "requestBody": { "description": "The content to search for.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/FileContent" } } }, "required": true }, "tags": [ "Search", "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:\n\n* `name`\n* `createdOn`\n", "schema": { "$ref": "#/components/schemas/ArtifactSortBy" }, "in": "query" }, { "name": "skipCount", "description": "Indicates whether to skip the total count query. When true, the total count is not computed and count will be 0 in the response. This can improve performance for large datasets.", "schema": { "default": false, "type": "boolean" }, "in": "query", "required": false } ], "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\nin 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\nposted content.\n\nThis operation can fail for the following reasons:\n\n* Provided content (request body) was empty (HTTP error `400`)\n* A server error occurred (HTTP error `500`)\n" } }, "/admin/export": { "summary": "Provides a way to export registry data.", "get": { "tags": [ "Admin" ], "parameters": [ { "name": "forBrowser", "description": "Indicates if the operation is done for a browser. If true, the response will be a JSON payload with a property called `href`. This `href` will be a single-use, naked download link suitable for use by a web browser to download the content.", "schema": { "type": "boolean" }, "in": "query" }, { "name": "groupId", "description": "If specified, only data belonging to this group will be exported. Global rules will be excluded.", "schema": { "type": "string" }, "in": "query" } ], "responses": { "200": { "content": { "application/zip": { "schema": { "$ref": "#/components/schemas/FileContent" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DownloadRef" } } }, "description": "Response when the export is successful." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "exportData", "summary": "Export registry data", "description": "Exports registry data as a ZIP archive. If a `groupId` query parameter is provided, only data belonging to the specified group will be exported and global rules will be excluded." } }, "/admin/import": { "summary": "Provides a way to import data into the registry.", "post": { "requestBody": { "description": "The ZIP file representing the previously exported registry data.", "content": { "application/zip": { "schema": { "$ref": "#/components/schemas/FileContent" } } }, "required": true }, "tags": [ "Admin" ], "parameters": [ { "name": "X-Registry-Preserve-GlobalId", "description": "If this header is set to false, global ids of imported data will be ignored and replaced by next id in global id sequence. This allows to import any data even thought the global ids would cause a conflict.", "schema": { "type": "boolean" }, "in": "header" }, { "name": "X-Registry-Preserve-ContentId", "description": "If this header is set to false, content ids of imported data will be ignored and replaced by next id in content id sequence. The mapping between content and artifacts will be preserved. This allows to import any data even thought the content ids would cause a conflict.", "schema": { "type": "boolean" }, "in": "header", "required": false }, { "name": "requireEmptyRegistry", "description": "Query parameter indicating whether the registry must be empty before allowing\ndata to be imported. Defaults to `true` if omitted.", "schema": { "type": "boolean" }, "in": "query", "required": false } ], "responses": { "201": { "description": "Indicates that the import was successful." }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "importData", "summary": "Import registry data", "description": "Imports registry data that was previously exported using the `/admin/export` operation." } }, "/groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}": { "summary": "Manage a single version of a single artifact in the registry.", "get": { "tags": [ "Metadata" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionMetaData" } } }, "description": "The artifact version's metadata." }, "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": "getArtifactVersionMetaData", "summary": "Get artifact version metadata", "description": "Retrieves the metadata for a single version of the artifact. The version metadata is \na subset of the artifact metadata and only includes the metadata that is specific to\nthe version (for example, this doesn't include `modifiedOn`).\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": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditableVersionMetaData" } } }, "required": true }, "tags": [ "Metadata" ], "responses": { "204": { "description": "The artifact version's metadata was successfully updated." }, "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": "updateArtifactVersionMetaData", "summary": "Update artifact version metadata", "description": "Updates the user-editable portion of the artifact version's metadata. Only some of \nthe metadata fields are editable by the user. For example, `description` is editable, \nbut `createdOn` is not.\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" }, "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" }, "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 } ] }, "/groups/{groupId}/artifacts/{artifactId}/rules": { "summary": "Manage the rules for a single artifact.", "get": { "tags": [ "Artifact rules" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RuleType" } } } }, "description": "Returns the names of the rules configured for the artifact." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "listArtifactRules", "summary": "List artifact rules", "description": "Returns a list of all rules configured for the artifact. The set of rules determines\nhow the content of an artifact can evolve over time. If no rules are configured for\nan artifact, then the rules configured for the group is used. If no rules are \nconfigured at the group level, then the set of globally configured rules are used. \nIf no global rules are defined, there are no restrictions on content evolution.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)" }, "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRule" } } }, "required": true }, "tags": [ "Artifact rules" ], "responses": { "204": { "description": "The rule was added." }, "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": "createArtifactRule", "summary": "Create artifact rule", "description": "Adds a rule to the list of rules that get applied to the artifact when adding new\nversions. All configured rules must pass to successfully add a new artifact version.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* Rule (named in the request body) is unknown (HTTP error `400`)\n* Rule is already configured (HTTP error `409`)\n* A server error occurred (HTTP error `500`)" }, "delete": { "tags": [ "Artifact rules" ], "responses": { "204": { "description": "The rules were successfully deleted." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "deleteArtifactRules", "summary": "Delete artifact rules", "description": "Deletes all of the rules configured for the artifact. After this is done, the global\nrules apply to the artifact again.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)" }, "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 } ] }, "/groups/{groupId}/artifacts/{artifactId}/rules/{ruleType}": { "summary": "Manage the configuration of a single artifact rule.", "get": { "tags": [ "Artifact rules" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } }, "description": "Information about a rule." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getArtifactRuleConfig", "summary": "Get artifact rule configuration", "description": "Returns information about a single rule configured for an artifact. This is useful\nwhen you want to know what the current configuration settings are for a specific rule.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* No rule with this name/type is configured for this artifact (HTTP error `404`)\n* Invalid rule type (HTTP error `400`)\n* A server error occurred (HTTP error `500`)" }, "put": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } }, "required": true }, "tags": [ "Artifact rules" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } }, "description": "Rule configuration was updated." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "updateArtifactRuleConfig", "summary": "Update artifact rule configuration", "description": "Updates the configuration of a single rule for the artifact. The configuration data\nis specific to each rule type, so the configuration of the `COMPATIBILITY` rule \nis in a different format from the configuration of the `VALIDITY` rule.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* No rule with this name/type is configured for this artifact (HTTP error `404`)\n* Invalid rule type (HTTP error `400`)\n* A server error occurred (HTTP error `500`)\n" }, "delete": { "tags": [ "Artifact rules" ], "responses": { "204": { "description": "The rule was successfully deleted." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "deleteArtifactRule", "summary": "Delete artifact rule", "description": "Deletes a rule from the artifact. This results in the rule no longer applying for\nthis artifact. If this is the only rule configured for the artifact, this is the \nsame as deleting **all** rules, and the globally configured rules now apply to\nthis artifact.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* No rule with this name/type is configured for this artifact (HTTP error `404`)\n* Invalid rule type (HTTP error `400`)\n* A server error occurred (HTTP error `500`)" }, "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": "ruleType", "description": "The unique name/type of a rule.", "schema": { "enum": [ "VALIDITY", "COMPATIBILITY", "INTEGRITY" ], "type": "string" }, "in": "path", "required": true } ] }, "/admin/roleMappings/{principalId}": { "summary": "Manage the configuration of a single role mapping.", "get": { "tags": [ "Admin" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleMapping" } } }, "description": "When successful, returns the details of a role mapping." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getRoleMapping", "summary": "Return a single role mapping", "description": "Gets the details of a single role mapping (by `principalId`).\n\nThis operation can fail for the following reasons:\n\n* No role mapping for the `principalId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "put": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRole" } } }, "required": true }, "tags": [ "Admin" ], "responses": { "204": { "description": "Response when the update is successful." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "updateRoleMapping", "summary": "Update a role mapping", "description": "Updates a single role mapping for one user/principal.\n\nThis operation can fail for the following reasons:\n\n* No role mapping for the principalId exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "delete": { "tags": [ "Admin" ], "responses": { "204": { "description": "Response returned when the delete was successful." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "deleteRoleMapping", "summary": "Delete a role mapping", "description": "Deletes a single role mapping, effectively denying access to a user/principal.\n\nThis operation can fail for the following reasons:\n\n* No role mapping for the principalId exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "parameters": [ { "name": "principalId", "description": "Unique id of a principal (typically either a user or service account).", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/users/me": { "summary": "Retrieves information about the current user", "get": { "tags": [ "Users" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfo" } } }, "description": "Response when the endpoint is successfully invoked." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getCurrentUserInfo", "summary": "Get current user", "description": "Returns information about the currently authenticated user." } }, "/ids/contentIds/{contentId}/references": { "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.\n\nThis operation may fail for one of the following reasons:\n\n* A server error occurred (HTTP error `500`)" }, "parameters": [ { "name": "contentId", "description": "Global identifier for a single artifact content.", "schema": { "format": "int64", "type": "integer" }, "in": "path", "required": true } ] }, "/ids/globalIds/{globalId}/references": { "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.\n\nThis operation may fail for one of the following reasons:\n\n* A server error occurred (HTTP error `500`)" }, "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" } ] }, "/groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/references": { "summary": "Manage the references for a single version of an artifact in the registry.", "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\nunique `version` number must be provided. Using the `refType` query parameter, it is possible\nto retrieve an array of either the inbound or outbound references.\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" }, "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 } ] }, "/groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/references/graph": { "summary": "Get a graph representation of artifact references.", "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.\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" }, "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 } ] }, "/admin/config/properties": { "summary": "Manage configuration properties.", "get": { "tags": [ "Admin" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationProperty" } } } }, "description": "On a successful response, returns a list of configuration properties." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "listConfigProperties", "summary": "List all configuration properties", "description": "Returns a list of all configuration properties that have been set. The list is not paged.\n\nThis operation may fail for one of the following reasons:\n\n* A server error occurred (HTTP error `500`)\n" } }, "/admin/config/properties/{propertyName}": { "summary": "Manage a single configuration property (by name).", "get": { "tags": [ "Admin" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationProperty" } } }, "description": "The configuration property value." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getConfigProperty", "summary": "Get configuration property value", "description": "Returns the value of a single configuration property.\n\nThis operation may fail for one of the following reasons:\n\n* Property not found or not configured (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "put": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConfigurationProperty" } } }, "required": true }, "tags": [ "Admin" ], "responses": { "204": { "description": "The configuration property was updated." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "updateConfigProperty", "summary": "Update a configuration property", "description": "Updates the value of a single configuration property.\n\nThis operation may fail for one of the following reasons:\n\n* Property not found or not configured (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "delete": { "tags": [ "Admin" ], "responses": { "204": { "description": "The configuration property was deleted." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "resetConfigProperty", "summary": "Reset a configuration property", "description": "Resets the value of a single configuration property. This will return the property to\nits default value (see external documentation for supported properties and their default\nvalues).\n\nThis operation may fail for one of the following reasons:\n\n* Property not found or not configured (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "parameters": [ { "name": "propertyName", "description": "The name of a configuration property.", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/groups/{groupId}/artifacts": { "summary": "Manage the collection of artifacts within a single group in the registry.", "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:\n\n* `name`\n* `createdOn`\n", "schema": { "$ref": "#/components/schemas/ArtifactSortBy" }, "in": "query" }, { "name": "skipCount", "description": "Indicates whether to skip the total count query. When true, the total count is not computed and count will be 0 in the response. This can improve performance for large datasets.", "schema": { "default": false, "type": "boolean" }, "in": "query", "required": false } ], "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\nwill 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/RuleViolationBadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "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 `400`)\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." }, "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 } ] }, "/groups": { "summary": "Collection of the groups in the registry.", "get": { "tags": [ "Groups" ], "parameters": [ { "name": "limit", "description": "The number of groups to return. Defaults to 20.", "schema": { "type": "integer" }, "in": "query" }, { "name": "offset", "description": "The number of groups 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:\n\n* `name`\n* `createdOn`\n", "schema": { "$ref": "#/components/schemas/GroupSortBy" }, "in": "query" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupSearchResults" } } }, "description": "On a successful response, returns a bounded set of groups." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "listGroups", "summary": "List groups", "description": "Returns a list of all groups. This list is paged." }, "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGroup" } } }, "required": true }, "tags": [ "Groups" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMetaData" } } }, "description": "The group has been successfully created." }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "createGroup", "summary": "Create a new group", "description": "Creates a new group.\n\nThis operation can fail for the following reasons:\n\n* A server error occurred (HTTP error `500`)\n* The group already exist (HTTP error `409`)\n* Invalid group ID (e.g., reserved name 'default') (HTTP error `400`)\n" } }, "/groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/comments": { "summary": "Manage a collection of comments for an artifact version", "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\nunique `version` number must 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* A server error occurred (HTTP error `500`)\n" }, "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\nunique `version` number must 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* A server error occurred (HTTP error `500`)\n" }, "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 } ] }, "/groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/comments/{commentId}": { "summary": "Manage a single comment", "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" }, "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 } ] }, "/groups/{groupId}/artifacts/{artifactId}/branches": { "summary": "Manage branches of an artifact.", "get": { "tags": [ "Branches" ], "parameters": [ { "name": "offset", "description": "The number of branches 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 branches to return. Defaults to 20.", "schema": { "type": "integer" }, "in": "query", "required": false } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchSearchResults" } } }, "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": "listBranches", "summary": "List branches", "description": "Returns a list of all branches in the artifact. Each branch is a list of version identifiers,\nordered from the latest (tip of the branch) to the oldest.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBranch" } } }, "required": true }, "tags": [ "Branches" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchMetaData" } } }, "description": "Branch successfully created." }, "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": "createBranch", "summary": "Create a new branch", "description": "Creates a new branch for the artifact. A new branch consists of metadata and a\nlist of versions.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)\n* A branch with the given `branchId` already exists (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n" }, "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 } ] }, "/groups/{groupId}/artifacts/{artifactId}/versions": { "summary": "Manage all the versions of an artifact in the registry.", "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:\n\n* `name`\n* `version`\n* `createdOn`\n", "schema": { "$ref": "#/components/schemas/VersionSortBy" }, "in": "query" }, { "name": "skipCount", "description": "Indicates whether to skip the total count query. When true, the total count is not computed and count will be 0 in the response. This can improve performance for large datasets.", "schema": { "default": false, "type": "boolean" }, "in": "query", "required": false } ], "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.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "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\nwill 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/RuleViolationBadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "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 `400`)\n* A server error occurred (HTTP error `500`)\n" }, "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 } ] }, "/groups/{groupId}/artifacts/{artifactId}/branches/{branchId}": { "summary": "Manage a single branch.", "get": { "tags": [ "Branches" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchMetaData" } } }, "description": "List of versions in an artifact branch." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getBranchMetaData", "summary": "Get branch metaData", "description": "Returns the metaData of a branch.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)\n* No branch with this `branchId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "put": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditableBranchMetaData" } } }, "required": true }, "tags": [ "Branches" ], "responses": { "204": { "description": "List of versions in an artifact branch." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "updateBranchMetaData", "summary": "Update branch metaData", "description": "Updates the metadata of a branch.\n\nThis operation can fail for the following reasons:\n* No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)\n* No branch with this `branchId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "delete": { "tags": [ "Branches" ], "responses": { "204": { "description": "Artifact branch was successfully deleted." }, "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": "deleteBranch", "summary": "Delete branch.", "description": "Deletes a single branch in the artifact.\n\nThis operation can fail for the following reasons:\n* No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)\n* No branch with this `branchId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "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": "branchId", "description": "Artifact branch ID. Must follow the \"[a-zA-Z0-9._\\\\-+]{1,256}\" pattern.", "schema": { "$ref": "#/components/schemas/BranchId" }, "in": "path", "required": true } ] }, "/system/uiConfig": { "summary": "Get UI configuration", "description": "This endpoint is used by the user interface to retrieve UI specific configuration\nin a JSON payload. This allows the UI and the backend to be configured in the \nsame place (the backend process/pod). When the UI loads, it will make an API call\nto this endpoint to determine what UI features and options are configured.", "get": { "tags": [ "System" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInterfaceConfig" } } }, "description": "The UI config." }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "getUIConfig", "summary": "Get UI config", "description": "Returns the UI configuration properties for this server. The registry UI can be\nconnected to a backend using just a URL. The rest of the UI configuration can then\nbe fetched from the backend using this operation. This allows UI and backend to\nboth be configured in the same place.\n\nThis operation may fail for one of the following reasons:\n\n* A server error occurred (HTTP error `500`)\n" } }, "/ids/contentHashes/{contentHash}/references": { "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.\n\nThis operation may fail for one of the following reasons:\n\n* A server error occurred (HTTP error `500`)\n" }, "parameters": [ { "name": "contentHash", "description": "SHA-256 content hash for a single artifact content.", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/ids/contentHashes/{contentHash}": { "summary": "Access artifact content utilizing the SHA-256 hash of the content.", "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" }, "parameters": [ { "name": "contentHash", "description": "SHA-256 content hash for a single artifact content.", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/ids/contentIds/{contentId}": { "summary": "Access artifact content utilizing the unique content identifier for that content.", "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\nidentifier for that content. This content ID may be shared by multiple artifact\nversions in the case where the artifact versions are identical.\n\nThis operation may fail for one of the following reasons:\n\n* No content with this `contentId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "parameters": [ { "name": "contentId", "description": "Global identifier for a single artifact content.", "schema": { "format": "int64", "type": "integer" }, "in": "path", "required": true } ] }, "/groups/{groupId}": { "summary": "Collection to manage a single group in the registry.", "get": { "tags": [ "Groups" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMetaData" } } }, "description": "The group's metadata." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getGroupById", "summary": "Get a group by the specified ID.", "description": "Returns a group using the specified id.\n\nThis operation can fail for the following reasons:\n\n* No group exists with the specified ID (HTTP error `404`)\n* A server error occurred (HTTP error `500`)" }, "put": { "requestBody": { "description": "The new group metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditableGroupMetaData" } } }, "required": true }, "tags": [ "Groups" ], "responses": { "204": { "description": "Empty response when the metadata is successfully updated." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "updateGroupById", "summary": "Update group metadata", "description": "Updates the metadata of a group using the specified id.\n\nThis operation can fail for the following reasons:\n\n* No group exists with the specified ID (HTTP error `404`)\n* A server error occurred (HTTP error `500`)" }, "delete": { "tags": [ "Groups" ], "responses": { "204": { "description": "Empty content indicates a successful deletion." }, "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": "deleteGroupById", "summary": "Delete a group by the specified ID.", "description": "Deletes a group by identifier. This operation also deletes all artifacts within\nthe group, so should be used very carefully.\n\nThis operation can fail for the following reasons:\n\n* A server error occurred (HTTP error `500`)\n* The group does not exist (HTTP error `404`)\n" }, "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 } ] }, "/admin/roleMappings": { "summary": "Collection to manage role mappings for authenticated principals", "get": { "tags": [ "Admin" ], "parameters": [ { "name": "limit", "description": "The number of role mappings to return. Defaults to 20.", "schema": { "type": "integer" }, "in": "query" }, { "name": "offset", "description": "The number of role mappings to skip before starting the result set. Defaults to 0.", "schema": { "type": "integer" }, "in": "query" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleMappingSearchResults" } } }, "description": "A successful response will return the list of role mappings." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "listRoleMappings", "summary": "List all role mappings", "description": "Gets a list of all role mappings configured in the registry (if any).\n\nThis operation can fail for the following reasons:\n\n* A server error occurred (HTTP error `500`)\n" }, "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleMapping" } } }, "required": true }, "tags": [ "Admin" ], "responses": { "204": { "description": "Returned when the role mapping was successfully created." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "createRoleMapping", "summary": "Create a new role mapping", "description": "Creates a new mapping between a user/principal and a role.\n\nThis operation can fail for the following reasons:\n\n* A server error occurred (HTTP error `500`)\n\n" } }, "/admin/config/artifactTypes": { "summary": "The list of artifact types supported by this instance of Registry.", "get": { "tags": [ "Artifact Type", "Admin" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactTypeInfo" } } } }, "description": "The list of available artifact types." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "listArtifactTypes", "summary": "List artifact types", "description": "Gets a list of all the configured artifact types.\n\nThis operation can fail for the following reasons:\n\n* A server error occurred (HTTP error `500`)\n" } }, "/admin/contracts/ruleset": { "summary": "Manage the global contract ruleset.", "get": { "tags": [ "Admin", "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractRuleSet" } } }, "description": "The global contract ruleset." }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "getGlobalContractRuleset", "summary": "Get global contract ruleset", "description": "Returns the global contract ruleset that applies to all artifacts." }, "put": { "tags": [ "Admin", "Contracts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractRuleSet" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractRuleSet" } } }, "description": "The global contract ruleset was set." }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "setGlobalContractRuleset", "summary": "Set global contract ruleset", "description": "Sets the global contract ruleset that applies to all artifacts." }, "delete": { "tags": [ "Admin", "Contracts" ], "responses": { "204": { "description": "The global contract ruleset was deleted." }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "deleteGlobalContractRuleset", "summary": "Delete global contract ruleset", "description": "Deletes the global contract ruleset." } }, "/admin/snapshots": { "summary": "Triggers a snapshot of the Registry storage. Only supported in KafkaSQL storage", "post": { "tags": [ "KafkaSQL", "Admin", "Snapshot" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotMetaData" } } }, "description": "The snapshot has been successfully triggered." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "triggerSnapshot", "summary": "Trigger storage snapshot", "description": "Triggers the creation of a snapshot of the internal database for compatible storages.\n\nThis operation can fail for the following reasons:\n\n* A server error occurred (HTTP error `500`)\n" } }, "/admin/gitops/status": { "summary": "Get the current GitOps synchronization status.", "get": { "tags": [ "GitOps", "Admin" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitOpsStatus" } } }, "description": "The current GitOps synchronization status." }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getGitOpsStatus", "summary": "Get GitOps synchronization status", "description": "**Experimental.** Returns the current synchronization status of the GitOps storage, including the current commit SHA, sync state, load statistics, and any errors from the last sync attempt.\n\nThis endpoint is only available when GitOps storage is enabled (`apicurio.storage.kind=gitops`). Returns HTTP 409 (Conflict) if a different storage backend is active.\n\nThis operation can fail for the following reasons:\n\n* GitOps storage is not enabled (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n" } }, "/admin/gitops/sync": { "summary": "Trigger an immediate GitOps synchronization.", "post": { "tags": [ "GitOps", "Admin" ], "responses": { "204": { "description": "Synchronization has been requested. The sync will happen asynchronously on the next scheduler cycle." }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "triggerGitOpsSync", "summary": "Trigger GitOps synchronization", "description": "**Experimental.** Requests an immediate synchronization of the GitOps storage. This resets the poll timer so the next scheduler cycle will poll the Git repository without waiting for the configured poll period.\n\nThe synchronization happens asynchronously \u2014 this endpoint returns immediately and the actual sync occurs on the next scheduler cycle.\n\nThis endpoint is only available when GitOps storage is enabled (`apicurio.storage.kind=gitops`). Returns HTTP 409 (Conflict) if a different storage backend is active.\n\nThis operation can fail for the following reasons:\n\n* GitOps storage is not enabled (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n" } }, "/admin/gitops/validate": { "summary": "Manage dry-run validation tasks.", "post": { "tags": [ "GitOps", "Admin" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitOpsValidateRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitOpsValidateTask" } } }, "description": "Validation task created. Poll the task status to get the result." }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "description": "Dry-run validation is disabled. Enable it by setting `apicurio.gitops.validate.enabled=true`." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "createGitOpsValidateTask", "summary": "Create a dry-run validation task", "description": "**Experimental.** Creates a dry-run validation task that fetches a git ref and validates the data without affecting the live registry. The sidecar fetches the ref, and the registry loads and validates the data in the inactive storage (no swap).\n\nReturns a task object with a `taskId` that can be used to poll for results.\n\nThis endpoint is only available when GitOps storage is enabled.\n\nThis operation can fail for the following reasons:\n\n* GitOps storage is not enabled (HTTP error `409`)\n* Dry-run validation is disabled (HTTP error `503`)\n* A server error occurred (HTTP error `500`)\n" }, "get": { "tags": [ "GitOps", "Admin" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GitOpsValidateTask" } } } }, "description": "List of active validation tasks." }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "description": "Dry-run validation is disabled." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "listGitOpsValidateTasks", "summary": "List validation tasks", "description": "**Experimental.** Returns a list of all active dry-run validation tasks." } }, "/admin/gitops/validate/{taskId}": { "summary": "Manage a specific validation task.", "get": { "tags": [ "GitOps", "Admin" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitOpsValidateTask" } } }, "description": "The validation task details and results." }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "description": "Dry-run validation is disabled." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getGitOpsValidateTask", "summary": "Get validation task status", "description": "**Experimental.** Returns the status and results of a specific dry-run validation task." }, "delete": { "tags": [ "GitOps", "Admin" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Validation task deleted." }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "description": "Dry-run validation is disabled." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "deleteGitOpsValidateTask", "summary": "Delete a validation task", "description": "**Experimental.** Deletes a validation task and cleans up its checkout directory." } }, "/groups/{groupId}/artifacts/{artifactId}": { "summary": "Manage a single artifact.", "get": { "tags": [ "Metadata" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactMetaData" } } }, "description": "The artifact's metadata." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getArtifactMetaData", "summary": "Get artifact metadata", "description": "Gets the metadata for an artifact in the registry, based on the latest version. If the latest version of the artifact is marked as `DISABLED`, the next available non-disabled version will be used. The returned metadata includes\nboth generated (read-only) and editable metadata (such as name and description).\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists or all versions are `DISABLED` (HTTP error `404`)\n* A server error occurred (HTTP error `500`)" }, "put": { "requestBody": { "description": "Updated artifact metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditableArtifactMetaData" } } }, "required": true }, "tags": [ "Metadata" ], "responses": { "204": { "description": "The artifact's metadata was updated." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "updateArtifactMetaData", "summary": "Update artifact metadata", "description": "Updates the editable parts of the artifact's metadata. Not all metadata fields can\nbe updated. Note that only the properties included will be updated. You can update\nonly the name by including only the `name` property in the payload of the request.\nProperties that are allowed but not present will result in the artifact's metadata\nnot being changed.\n\nThis operation can fail for the following reasons:\n\n* No artifact with the `artifactId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)" }, "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\ndeleted. This may fail for one of the following reasons:\n\n* No artifact with the `artifactId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)" }, "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 } ] }, "/groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/content": { "summary": "Manage a single version of a single artifact in the registry.", "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" }, { "name": "canonical", "description": "Parameter that can be set to `true` to indicate that the server should return the canonicalized form of the artifact content. Canonicalization is unique to each artifact type, but typically involves removing any extra whitespace and formatting the content in a consistent manner. When `canonical=true`, the server resolves artifact references internally for canonicalization regardless of the `references` query parameter value. The `references` parameter still controls how references appear in the returned content (e.g. preserved, dereferenced, or rewritten).", "schema": { "type": "boolean" }, "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.\n\nNOTE: the artifact must be in `DRAFT` status.\n\nBoth the `artifactId` and the unique `version` number must be provided to identify\nthe version to update.\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* Artifact version not in `DRAFT` status (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n" }, "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 } ] }, "/groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/export": { "summary": "Export a Protobuf artifact version with dependencies as a ZIP file.", "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.\nThe files in the ZIP are organized by their package names to match the expected directory\nstructure for protoc compilation. Import statements are rewritten to use canonical\npackage-based paths.\n\nThis operation is only supported for PROTOBUF artifact types.\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* Artifact is not of type PROTOBUF (HTTP error `400`)\n* A server error occurred (HTTP error `500`)\n" }, "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 } ] }, "/search/groups": { "summary": "Search for groups in the registry.", "get": { "tags": [ "Search", "Groups" ], "parameters": [ { "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:\n\n* `name`\n* `createdOn`\n", "schema": { "$ref": "#/components/schemas/GroupSortBy" }, "in": "query" }, { "name": "labels", "description": "Filter by one or more name/value label. Separate each name/value pair using a colon. For\nexample `labels=foo:bar` will return only artifacts with a label named `foo`\nand 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 group name.", "schema": { "type": "string" }, "in": "query" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupSearchResults" } } }, "description": "On a successful response, returns a result set of groups - one for each group\nin the registry that matches the criteria." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "searchGroups", "summary": "Search for groups", "description": "Returns a paginated list of all groups that match the provided filter criteria.\n\nThis operation can fail for the following reasons:\n\n* A server error occurred (HTTP error `500`)\n" } }, "/search/versions": { "summary": "Search for versions in the registry.", "get": { "tags": [ "Search", "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:\n\n* `name`\n* `createdOn`\n", "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\nexample `labels=foo:bar` will return only artifacts with a label named `foo`\nand 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" }, { "name": "skipCount", "description": "Indicates whether to skip the total count query. When true, the total count is not computed and count will be 0 in the response. This can improve performance for large datasets.", "schema": { "default": false, "type": "boolean" }, "in": "query", "required": false } ], "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\nin 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.\n\nThis operation can fail for the following reasons:\n\n* A server error occurred (HTTP error `500`)\n" }, "post": { "requestBody": { "description": "The content to search for.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/FileContent" } } }, "required": true }, "tags": [ "Search", "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:\n\n* `name`\n* `createdOn`\n", "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" }, { "name": "skipCount", "description": "Indicates whether to skip the total count query. When true, the total count is not computed and count will be 0 in the response. This can improve performance for large datasets.", "schema": { "default": false, "type": "boolean" }, "in": "query", "required": false } ], "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\nin 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.\n\nThis operation can fail for the following reasons:\n\n* Provided content (request body) was empty (HTTP error `400`)\n* A server error occurred (HTTP error `500`)\n" } }, "/search/contract/rules": { "summary": "Search for contract rules by tag.", "get": { "tags": [ "Search", "Contracts" ], "parameters": [ { "name": "tag", "description": "The tag value to search for in contract rules.", "schema": { "type": "string" }, "in": "query", "required": true } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContractRuleSearchResult" } } } }, "description": "A list of contract rules matching the specified tag, with their artifact coordinates." }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "searchContractRulesByTag", "summary": "Search contract rules by tag", "description": "Returns all contract rules across all artifacts that contain the specified tag." } }, "/search/contracts": { "summary": "Search for contracts.", "get": { "tags": [ "Search", "Contracts" ], "parameters": [ { "name": "status", "description": "Filter by contract status (DRAFT, STABLE, DEPRECATED).", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "ownerTeam", "description": "Filter by owner team.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "compatibilityGroup", "description": "Filter by compatibility group.", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "offset", "description": "Number of results to skip.", "schema": { "type": "integer", "default": 0 }, "in": "query", "required": false }, { "name": "limit", "description": "Maximum number of results to return.", "schema": { "type": "integer", "default": 20 }, "in": "query", "required": false }, { "name": "order", "description": "Sort order (asc or desc).", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "required": false }, { "name": "orderby", "description": "Field to sort by.", "schema": { "type": "string", "enum": [ "name", "createdOn", "modifiedOn" ] }, "in": "query", "required": false } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactSearchResults" } } }, "description": "A paginated list of artifacts that have contract metadata." }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "searchContracts", "summary": "Search contracts", "description": "Searches for artifacts that have contract metadata labels. Filters by status, owner team, and compatibility group." } }, "/groups/{groupId}/artifacts/{artifactId}/branches/{branchId}/versions": { "summary": "Manage the versions in a branch.", "get": { "tags": [ "Branches" ], "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 } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionSearchResults" } } }, "description": "The list of versions in the branch." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "listBranchVersions", "summary": "Get versions in branch", "description": "Get a list of all versions in the branch. Returns a list of version identifiers in the branch, \nordered from the latest (tip of the branch) to the oldest.\n\nThis operation can fail for the following reasons:\n* No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)\n* No branch with this `branchId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "put": { "requestBody": { "description": "A new list of versions that should be on the branch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceBranchVersions" } } }, "required": true }, "tags": [ "Branches" ], "responses": { "204": { "description": "The list of versions was replaced successfully." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "replaceBranchVersions", "summary": "Replace list of versions in branch", "description": "Add a new version to an artifact branch. Branch is created if it does not exist. Returns a list of version identifiers in the artifact branch, ordered from the latest (tip of the branch) to the oldest.\nThis operation can fail for the following reasons:\n* No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)\n* No branch with this `branchId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n" }, "post": { "requestBody": { "description": "The version to add to the branch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddVersionToBranch" } } }, "required": true }, "tags": [ "Branches" ], "responses": { "204": { "description": "The version was successfully added to the branch." }, "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": "addVersionToBranch", "summary": "Add a new version to a branch.", "description": "Add a new version to an artifact branch. Returns a list of version identifiers in the branch, ordered from the latest (tip of the branch) to the oldest.\n\nThis operation can fail for the following reasons:\n* No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)\n* No branch with this `branchId` exists (HTTP error `404`)\n* Branch already contains the given version. Artifact branches are append-only, cycles and history rewrites, except by replacing the entire branch using the replaceBranchVersions operation, are not supported. (HTTP error `409`)\n* A server error occurred (HTTP error `500`)\n" }, "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": "branchId", "description": "Artifact branch ID. Must follow the \"[a-zA-Z0-9._\\\\-+]{1,256}\" pattern.", "schema": { "$ref": "#/components/schemas/BranchId" }, "in": "path", "required": true } ] }, "/groups/{groupId}/rules": { "summary": "Manage the rules for a group.", "get": { "tags": [ "Group rules" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RuleType" } } } }, "description": "Returns the names of the rules configured for the group." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "listGroupRules", "summary": "List group rules", "description": "Returns a list of all rules configured for the group. The set of rules determines\nhow the content of an artifact in the group can evolve over time. If no rules are \nconfigured for a group, the set of globally configured rules are used.\n\nThis operation can fail for the following reasons:\n\n* No group with this `groupId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)" }, "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRule" } } }, "required": true }, "tags": [ "Group rules" ], "responses": { "204": { "description": "The rule was added." }, "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": "createGroupRule", "summary": "Create group rule", "description": "Adds a rule to the list of rules that get applied to an artifact in the group when adding new\nversions. All configured rules must pass to successfully add a new artifact version.\n\nThis operation can fail for the following reasons:\n\n* No group with this `groupId` exists (HTTP error `404`)\n* Rule (named in the request body) is unknown (HTTP error `400`)\n* Rule is already configured (HTTP error `409`)\n* A server error occurred (HTTP error `500`)" }, "delete": { "tags": [ "Group rules" ], "responses": { "204": { "description": "The rules were successfully deleted." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "deleteGroupRules", "summary": "Delete group rules", "description": "Deletes all of the rules configured for the group. After this is done, the global\nrules apply to artifacts in the group again.\n\nThis operation can fail for the following reasons:\n\n* No group with this `groupId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)" }, "parameters": [ { "name": "groupId", "description": "The 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 } ] }, "/groups/{groupId}/rules/{ruleType}": { "summary": "Manage the configuration of a single group rule.", "get": { "tags": [ "Group rules" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } }, "description": "Information about a rule." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getGroupRuleConfig", "summary": "Get group rule configuration", "description": "Returns information about a single rule configured for a group. This is useful\nwhen you want to know what the current configuration settings are for a specific rule.\n\nThis operation can fail for the following reasons:\n\n* No group with this `groupId` exists (HTTP error `404`)\n* No rule with this name/type is configured for this artifact (HTTP error `404`)\n* Invalid rule type (HTTP error `400`)\n* A server error occurred (HTTP error `500`)" }, "put": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } }, "required": true }, "tags": [ "Group rules" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } }, "description": "Rule configuration was updated." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "updateGroupRuleConfig", "summary": "Update group rule configuration", "description": "Updates the configuration of a single rule for the group. The configuration data\nis specific to each rule type, so the configuration of the `COMPATIBILITY` rule \nis in a different format from the configuration of the `VALIDITY` rule.\n\nThis operation can fail for the following reasons:\n\n* No group with this `groupId` exists (HTTP error `404`)\n* No rule with this name/type is configured for this artifact (HTTP error `404`)\n* Invalid rule type (HTTP error `400`)\n* A server error occurred (HTTP error `500`)\n" }, "delete": { "tags": [ "Group rules" ], "responses": { "204": { "description": "The rule was successfully deleted." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "deleteGroupRule", "summary": "Delete group rule", "description": "Deletes a rule from the group. This results in the rule no longer applying for\nthis group. If this is the only rule configured for the group, this is the \nsame as deleting **all** rules, and the globally configured rules now apply to\nthis group.\n\nThis operation can fail for the following reasons:\n\n* No group with this `groupId` exists (HTTP error `404`)\n* No rule with this name/type is configured for this group (HTTP error `404`)\n* Invalid rule type (HTTP error `400`)\n* A server error occurred (HTTP error `500`)" }, "parameters": [ { "name": "groupId", "description": "The 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": "ruleType", "description": "The unique name/type of a rule.", "schema": { "enum": [ "VALIDITY", "COMPATIBILITY", "INTEGRITY" ], "type": "string" }, "in": "path", "required": true } ] }, "/groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/render": { "summary": "Render a prompt template artifact by substituting variables.", "post": { "tags": [ "Versions", "AI" ], "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.\nThe artifact must be of type `PROMPT_TEMPLATE`. Variables are validated against the template's\nvariable schema before rendering.\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* The artifact is not a PROMPT_TEMPLATE (HTTP error `400`)\n* Required variables are missing or have invalid types (HTTP error `400`)\n* A server error occurred (HTTP error `500`)\n" }, "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 } ] }, "/groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/state": { "summary": "Manage the state of an artifact version.", "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.\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 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\nwill 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" }, "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 } ] }, "/content/references": { "summary": "Detect external references in artifact content.", "post": { "tags": [ "Content" ], "parameters": [ { "name": "artifactType", "description": "The type of artifact represented by the content. If not provided, the server will attempt to auto-detect the type from the content.", "schema": { "type": "string" }, "in": "query" } ], "requestBody": { "description": "The content to analyze for external references.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionContent" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactReference" } } } }, "description": "List of references detected in the provided content. Each reference will have only the `name` field populated. The `name` value corresponds to the reference string found in the content (e.g. a JSON Schema `$ref` value, a Protobuf import path, or an Avro type name)." }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "detectContentReferences", "summary": "Detect references in content", "description": "Analyzes the provided content and returns a list of external references found within it. The artifact type is used to determine the appropriate reference detection strategy. If no artifact type is provided, the system will attempt to auto-detect it from the content." } }, "/content/canonicalize": { "summary": "Canonicalize content", "post": { "requestBody": { "description": "The content to canonicalize.", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/FileContent" } } }, "required": true }, "tags": [ "Content" ], "parameters": [ { "name": "artifactType", "description": "Indicates the type of artifact represented by the content. The server uses this to determine how to canonicalize the content.", "schema": { "$ref": "#/components/schemas/ArtifactType" }, "in": "query", "required": true } ], "responses": { "200": { "$ref": "#/components/responses/ArtifactContent" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "canonicalizeContent", "summary": "Canonicalize content", "description": "Canonicalizes the provided content using the rules for the specified artifact type. Canonicalization is specific to each artifact type, but typically involves removing extra whitespace, sorting object keys, and formatting the content in a consistent manner. The canonicalized content is returned as the response body.\n\nNote: this endpoint operates on the content as provided and does not resolve external references (`$ref`). To canonicalize content with references resolved, use `GET /groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/content?canonical=true` on a stored artifact instead.\n\nThis operation can fail for the following reasons:\n\n* Provided content (request body) was empty (HTTP error `400`)\n* The artifact type was not provided or was invalid (HTTP error `400`)\n* A server error occurred (HTTP error `500`)\n" } }, "/groups/{groupId}/artifacts/{artifactId}/contract/metadata": { "summary": "Manage contract metadata for an artifact.", "get": { "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMetadata" } } }, "description": "The contract metadata for the artifact." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "getContractMetadata", "summary": "Get contract metadata", "description": "Returns the contract metadata for an artifact, projected from its labels." }, "put": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditableContractMetadata" } } }, "required": true }, "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMetadata" } } }, "description": "The updated contract metadata." }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "updateContractMetadata", "summary": "Update contract metadata", "description": "Creates or updates the contract metadata for an artifact." }, "parameters": [ { "name": "groupId", "description": "The artifact group ID.", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "artifactId", "description": "The artifact ID.", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/groups/{groupId}/artifacts/{artifactId}/contract/status": { "summary": "Transition the contract lifecycle status.", "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractStatusTransition" } } }, "required": true }, "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractMetadata" } } }, "description": "The updated contract metadata after the status transition." }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "transitionContractStatus", "summary": "Transition contract status", "description": "Transitions the contract status. Valid transitions: DRAFT to STABLE, DRAFT to DEPRECATED, STABLE to DEPRECATED. Reverse transitions are not allowed." }, "parameters": [ { "name": "groupId", "description": "The artifact group ID.", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "artifactId", "description": "The artifact ID.", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/groups/{groupId}/artifacts/{artifactId}/contract/ruleset": { "summary": "Manage contract ruleset for an artifact (artifact-level).", "get": { "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractRuleSet" } } }, "description": "The contract ruleset for the artifact." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "getArtifactContractRuleset", "summary": "Get artifact contract ruleset", "description": "Returns the contract ruleset for the artifact (artifact-level rules that apply to all versions)." }, "put": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractRuleSet" } } }, "required": true }, "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractRuleSet" } } }, "description": "The updated contract ruleset." }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "setArtifactContractRuleset", "summary": "Set artifact contract ruleset", "description": "Creates or replaces the contract ruleset for the artifact." }, "delete": { "tags": [ "Contracts" ], "responses": { "204": { "description": "The contract ruleset was deleted." }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "deleteArtifactContractRuleset", "summary": "Delete artifact contract ruleset", "description": "Deletes the contract ruleset for the artifact." }, "parameters": [ { "name": "groupId", "description": "The artifact group ID.", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "artifactId", "description": "The artifact ID.", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/contract/ruleset": { "summary": "Manage contract ruleset for a specific artifact version.", "get": { "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractRuleSet" } } }, "description": "The contract ruleset for the version." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "getVersionContractRuleset", "summary": "Get version contract ruleset", "description": "Returns the contract ruleset for a specific artifact version." }, "put": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractRuleSet" } } }, "required": true }, "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractRuleSet" } } }, "description": "The updated contract ruleset." }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "setVersionContractRuleset", "summary": "Set version contract ruleset", "description": "Creates or replaces the contract ruleset for a specific version." }, "delete": { "tags": [ "Contracts" ], "responses": { "204": { "description": "The contract ruleset was deleted." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "deleteVersionContractRuleset", "summary": "Delete version contract ruleset", "description": "Deletes the contract ruleset for a specific version." }, "parameters": [ { "name": "groupId", "description": "The artifact group ID.", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "artifactId", "description": "The artifact ID.", "schema": { "type": "string" }, "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 } ] }, "/groups/{groupId}/contracts": { "summary": "Manage ODCS data contracts within a group.", "post": { "requestBody": { "content": { "application/x-yaml": { "schema": { "type": "string" } } }, "required": true }, "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OdcsContractResult" } } }, "description": "The contract was created (or updated if it already exists) and projected onto the referenced schema artifact." }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "submitContract", "summary": "Submit an ODCS contract", "description": "Submits an ODCS v3.1 YAML contract. The contract is parsed, stored as an ODCS_CONTRACT artifact, and its contents are projected onto the referenced schema artifact (labels, rules, field tags)." }, "get": { "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OdcsContractSummary" } } } }, "description": "List of ODCS contracts in the group." }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "listContracts", "summary": "List ODCS contracts", "description": "Returns ODCS contracts in the specified group with pagination.", "parameters": [ { "name": "limit", "description": "Maximum number of contracts to return (default 20, max 500).", "schema": { "type": "integer", "format": "int32" }, "in": "query" }, { "name": "offset", "description": "Number of contracts to skip (for pagination).", "schema": { "type": "integer", "format": "int32" }, "in": "query" } ] }, "parameters": [ { "name": "groupId", "description": "The group ID.", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/groups/{groupId}/contracts/{contractId}": { "summary": "Manage a specific ODCS contract.", "get": { "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/x-yaml": { "schema": { "type": "string" } } }, "description": "The ODCS contract YAML." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "getContract", "summary": "Get an ODCS contract", "description": "Returns the ODCS contract YAML for the specified contract." }, "put": { "requestBody": { "content": { "application/x-yaml": { "schema": { "type": "string" } } }, "required": true }, "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OdcsContractResult" } } }, "description": "The contract was updated and re-projected." }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "updateContract", "summary": "Update an ODCS contract", "description": "Updates an ODCS contract (creates a new version) and re-projects onto the referenced schema artifact." }, "delete": { "tags": [ "Contracts" ], "responses": { "204": { "description": "The contract was deleted." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "deleteContract", "summary": "Delete an ODCS contract", "description": "Deletes the ODCS contract artifact." }, "parameters": [ { "name": "groupId", "description": "The group ID.", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "contractId", "description": "The contract ID.", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/groups/{groupId}/artifacts/{artifactId}/contract/export": { "summary": "Export contract metadata, rules, and field tags as ODCS YAML.", "get": { "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/x-yaml": { "schema": { "type": "string" } } }, "description": "The reconstructed ODCS contract YAML." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "exportContractAsOdcs", "summary": "Export as ODCS", "description": "Reconstructs an ODCS v3.1 YAML contract from the artifact's current contract.* labels, contract rules, and field-tag.* version labels." }, "parameters": [ { "name": "groupId", "description": "The artifact group ID.", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "artifactId", "description": "The artifact ID.", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/groups/{groupId}/artifacts/{artifactId}/contract/promote": { "summary": "Promote a contract to the next deployment stage.", "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "contractId": { "type": "string" }, "targetStage": { "type": "string", "enum": [ "DEV", "STAGE", "PROD" ] } }, "required": [ "contractId", "targetStage" ] } } }, "required": true }, "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "stage": { "type": "string" } } } } }, "description": "The contract was promoted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "promoteContract", "summary": "Promote contract stage", "description": "Promotes a contract to the next deployment stage (DEV -> STAGE -> PROD)." }, "parameters": [ { "name": "groupId", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "artifactId", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/groups/{groupId}/artifacts/{artifactId}/contract/quality": { "summary": "Get quality score for a contract.", "get": { "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "overall": { "type": "number", "format": "float" }, "completeness": { "type": "number", "format": "float" }, "compliance": { "type": "number", "format": "float" }, "stability": { "type": "number", "format": "float" } } } } }, "description": "The quality score." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "getContractQuality", "summary": "Get quality score", "description": "Returns the quality score for a contract, with breakdown by completeness, compliance, and stability.", "parameters": [ { "name": "contractId", "schema": { "type": "string" }, "in": "query", "required": true } ] }, "parameters": [ { "name": "groupId", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "artifactId", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/groups/{groupId}/artifacts/{artifactId}/contract/audit": { "summary": "Get the contract audit log for an artifact.", "get": { "tags": [ "Contracts" ], "parameters": [ { "name": "offset", "schema": { "type": "integer", "default": 0 }, "in": "query", "required": false }, { "name": "limit", "schema": { "type": "integer", "default": 20 }, "in": "query", "required": false } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "auditId": { "type": "integer" }, "groupId": { "type": "string" }, "artifactId": { "type": "string" }, "version": { "type": "string" }, "action": { "type": "string" }, "principal": { "type": "string" }, "details": { "type": "string" }, "createdOn": { "type": "string", "format": "date-time" } } } } } }, "description": "The audit log entries." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "getContractAuditLog", "summary": "Get contract audit log", "description": "Returns a paginated audit log of contract operations for the specified artifact." }, "parameters": [ { "name": "groupId", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "artifactId", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/groups/{groupId}/artifacts/{artifactId}/contract/compatibility-group": { "summary": "Manage the compatibility group for an artifact's contract.", "get": { "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "compatibilityGroup": { "type": "string" } } } } }, "description": "The compatibility group." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "getCompatibilityGroup", "summary": "Get compatibility group", "description": "Returns the compatibility group for the artifact's contract.", "parameters": [ { "name": "contractId", "schema": { "type": "string" }, "in": "query", "required": true } ] }, "put": { "tags": [ "Contracts" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "contractId": { "type": "string" }, "compatibilityGroup": { "type": "string" } }, "required": [ "contractId", "compatibilityGroup" ] } } }, "required": true }, "responses": { "204": { "description": "Compatibility group updated." }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "setCompatibilityGroup", "summary": "Set compatibility group", "description": "Sets the compatibility group for the artifact's contract." }, "parameters": [ { "name": "groupId", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "artifactId", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/groups/{groupId}/artifacts/{artifactId}/contract/migrate": { "summary": "Execute migration rules to transform a record between versions.", "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "fromVersion": { "type": "string" }, "toVersion": { "type": "string" }, "record": { "type": "object", "additionalProperties": true } }, "required": [ "fromVersion", "toVersion", "record" ] } } }, "required": true }, "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "passed": { "type": "boolean" }, "transformedRecord": { "type": "object", "additionalProperties": true }, "violations": { "type": "array", "items": { "type": "object", "properties": { "ruleName": { "type": "string" }, "message": { "type": "string" }, "action": { "type": "string" } } } }, "executedRules": { "type": "integer" }, "failedRules": { "type": "integer" } } } } }, "description": "The migration result." }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "migrateContractRecord", "summary": "Migrate record between versions", "description": "Executes migration rules to transform a record from one schema version to another, chaining transforms across version hops." }, "parameters": [ { "name": "groupId", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "artifactId", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/contract/execute": { "summary": "Execute contract rules against a data record.", "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "WRITE", "READ" ] }, "record": { "type": "object", "additionalProperties": true } }, "required": [ "mode", "record" ] } } }, "required": true }, "tags": [ "Contracts" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "passed": { "type": "boolean" }, "transformedRecord": { "type": "object", "additionalProperties": true }, "violations": { "type": "array", "items": { "type": "object", "properties": { "ruleName": { "type": "string" }, "message": { "type": "string" }, "action": { "type": "string" } } } }, "executedRules": { "type": "integer" }, "failedRules": { "type": "integer" } } } } }, "description": "The rule execution result." }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "executeContractRules", "summary": "Execute contract rules", "description": "Executes contract rules against a data record and returns the result." }, "parameters": [ { "name": "groupId", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "artifactId", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "versionExpression", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "x-codegen-contextRoot": "/apis/registry/v3", "/admin/usage/summary": { "summary": "Get global usage summary counts.", "get": { "tags": [ "Admin" ], "operationId": "getUsageSummary", "summary": "Get usage summary", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" } } }, "description": "The global usage summary." }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/admin/usage/artifacts/{groupId}/{artifactId}": { "summary": "Get usage metrics for an artifact.", "get": { "tags": [ "Admin" ], "operationId": "getArtifactUsageMetrics", "summary": "Get artifact usage metrics", "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactUsageMetrics" } } }, "description": "The artifact usage metrics." }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/admin/usage/artifacts/{groupId}/{artifactId}/heatmap": { "summary": "Get consumer version heatmap.", "get": { "tags": [ "Admin" ], "operationId": "getConsumerVersionHeatmap", "summary": "Get consumer version heatmap", "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerVersionHeatmap" } } }, "description": "The consumer version heatmap." }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/admin/usage/artifacts/{groupId}/{artifactId}/versions/{version}/deprecation-readiness": { "summary": "Get deprecation readiness.", "get": { "tags": [ "Admin" ], "operationId": "getDeprecationReadiness", "summary": "Get deprecation readiness report", "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeprecationReadiness" } } }, "description": "The deprecation readiness report." }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/well-known/agent.json": { "summary": "Get Agent Card.", "get": { "tags": [ "WellKnown" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCard" } } }, "description": "The Agent Card." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getAgentCard", "summary": "Get Agent Card" } }, "/well-known/a2a": { "summary": "Get Agent Card (A2A v1.0).", "get": { "tags": [ "WellKnown" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCard" } } }, "description": "The Agent Card." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getAgentCardV1", "summary": "Get Agent Card (A2A v1.0)" } }, "/well-known/agent-card.json": { "summary": "Get Agent Card (Orchestrate).", "get": { "tags": [ "WellKnown" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCard" } } }, "description": "The Agent Card." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getAgentCardForOrchestrate", "summary": "Get Agent Card (Orchestrate)" } }, "/well-known/agents": { "summary": "Search agents.", "get": { "tags": [ "WellKnown" ], "parameters": [ { "name": "offset", "schema": { "default": 0, "type": "integer" }, "in": "query", "required": false }, { "name": "limit", "schema": { "default": 20, "type": "integer" }, "in": "query", "required": false }, { "name": "name", "schema": { "type": "string" }, "in": "query" }, { "name": "skill", "schema": { "type": "array", "items": { "type": "string" } }, "in": "query" }, { "name": "capability", "schema": { "type": "array", "items": { "type": "string" } }, "in": "query" }, { "name": "inputMode", "schema": { "type": "array", "items": { "type": "string" } }, "in": "query" }, { "name": "outputMode", "schema": { "type": "array", "items": { "type": "string" } }, "in": "query" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSearchResults" } } }, "description": "Agent search results." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "searchAgents", "summary": "Search agents" } }, "/well-known/agents/public": { "summary": "Search public agents.", "get": { "tags": [ "WellKnown" ], "parameters": [ { "name": "offset", "schema": { "default": 0, "type": "integer" }, "in": "query", "required": false }, { "name": "limit", "schema": { "default": 20, "type": "integer" }, "in": "query", "required": false } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSearchResults" } } }, "description": "Public agents." }, "500": { "$ref": "#/components/responses/ServerError" } }, "operationId": "searchPublicAgents", "summary": "Search public agents" } }, "/well-known/agents/entitled": { "summary": "Search entitled agents.", "get": { "tags": [ "WellKnown" ], "parameters": [ { "name": "offset", "schema": { "default": 0, "type": "integer" }, "in": "query", "required": false }, { "name": "limit", "schema": { "default": 20, "type": "integer" }, "in": "query", "required": false } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSearchResults" } } }, "description": "Entitled agents." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "searchEntitledAgents", "summary": "Search entitled agents" } }, "/well-known/agents/search": { "summary": "Advanced agent search.", "post": { "tags": [ "WellKnown" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSearchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSearchResults" } } }, "description": "Search results." }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "searchAgentsAdvanced", "summary": "Advanced agent search" } }, "/well-known/agents/{groupId}/{artifactId}": { "summary": "Get registered agent card.", "get": { "tags": [ "WellKnown" ], "parameters": [ { "name": "version", "schema": { "type": "string" }, "in": "query" } ], "responses": { "200": { "content": { "application/json": {} }, "description": "Agent Card JSON." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getRegisteredAgentCard", "summary": "Get registered agent card" }, "parameters": [ { "name": "groupId", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "artifactId", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/well-known/mcp-tools": { "summary": "Search MCP tools.", "get": { "tags": [ "WellKnown" ], "parameters": [ { "name": "offset", "schema": { "default": 0, "type": "integer" }, "in": "query", "required": false }, { "name": "limit", "schema": { "default": 20, "type": "integer" }, "in": "query", "required": false }, { "name": "name", "schema": { "type": "string" }, "in": "query" }, { "name": "parameter", "schema": { "type": "array", "items": { "type": "string" } }, "in": "query" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolSearchResults" } } }, "description": "MCP tool search results." }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "searchMcpTools", "summary": "Search MCP tools" } }, "/well-known/mcp-tools/{groupId}/{artifactId}": { "summary": "Get registered MCP tool.", "get": { "tags": [ "WellKnown" ], "parameters": [ { "name": "version", "schema": { "type": "string" }, "in": "query" } ], "responses": { "200": { "content": { "application/json": {} }, "description": "MCP tool JSON." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getRegisteredMcpTool", "summary": "Get registered MCP tool" }, "parameters": [ { "name": "groupId", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "artifactId", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/well-known/schemas/{schemaType}/{version}": { "summary": "Get JSON Schema.", "get": { "tags": [ "WellKnown" ], "responses": { "200": { "content": { "application/json": {} }, "description": "The JSON Schema." }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "operationId": "getSchema", "summary": "Get JSON Schema" }, "parameters": [ { "name": "schemaType", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "version", "schema": { "type": "string" }, "in": "path", "required": true } ] } }, "components": { "schemas": { "Rule": { "title": "Root Type for Rule", "description": "", "required": [ "config" ], "type": "object", "properties": { "config": { "type": "string" }, "ruleType": { "$ref": "#/components/schemas/RuleType" } }, "example": { "ruleType": "VALIDITY", "config": "FULL" } }, "ProblemDetails": { "title": "Root Type for Error", "description": "All error responses, whether `4xx` or `5xx` will include one of these as the response\nbody.", "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." } }, "RuleType": { "description": "", "enum": [ "VALIDITY", "COMPATIBILITY", "INTEGRITY" ], "type": "string", "example": "VALIDITY", "x-codegen-package": "io.apicurio.registry.types" }, "ArtifactType": { "description": "", "type": "string", "example": "AVRO", "x-codegen-package": "io.apicurio.registry.types" }, "ArtifactTypeInfo": { "description": "", "type": "object", "properties": { "name": { "type": "string" } }, "example": { "name": "AVRO" } }, "ArtifactSearchResults": { "description": "Describes the response received when searching for artifacts.", "required": [ "count", "artifacts" ], "type": "object", "properties": { "artifacts": { "description": "The artifacts returned in the result set.", "type": "array", "items": { "$ref": "#/components/schemas/SearchedArtifact" } }, "count": { "description": "The total number of artifacts that matched the query that produced the result set (may be \nmore than the number of artifacts in the result set).", "type": "integer" } } }, "SortOrder": { "description": "", "enum": [ "asc", "desc" ], "type": "string" }, "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\nreturned 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" } } } }, "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]" } }, "IfArtifactExists": { "description": "", "enum": [ "FAIL", "CREATE_VERSION", "FIND_OR_CREATE_VERSION" ], "type": "string" }, "ArtifactSortBy": { "description": "", "enum": [ "groupId", "artifactId", "createdOn", "modifiedOn", "artifactType", "name" ], "type": "string" }, "GitOpsStatus": { "title": "Root Type for GitOpsStatus", "description": "Describes the current synchronization status of the GitOps storage backend. This includes the current sync state, the Git commit marker, load statistics, and any errors from the last sync attempt.", "type": "object", "properties": { "syncState": { "description": "The current synchronization state of the GitOps storage. Possible values: INITIALIZING (first load not yet completed), IDLE (serving latest data), LOADING (sync in progress), SWITCHING (data loaded, waiting for write lock to publish), ERROR (last sync or switch failed, serving previous data).", "type": "string" }, "lastSuccessfulSync": { "description": "ISO 8601 timestamp of the last successful synchronization.", "format": "date-time", "type": "string" }, "lastSyncAttempt": { "description": "ISO 8601 timestamp of the last synchronization attempt (successful or not).", "format": "date-time", "type": "string" }, "groupCount": { "description": "Number of groups loaded in the last successful sync.", "format": "int32", "type": "integer" }, "artifactCount": { "description": "Number of artifacts loaded in the last successful sync.", "format": "int32", "type": "integer" }, "versionCount": { "description": "Number of artifact versions loaded in the last successful sync.", "format": "int32", "type": "integer" }, "errors": { "description": "Errors from the last failed load attempt. Empty if the last load was successful.", "type": "array", "items": { "$ref": "#/components/schemas/GitOpsError" } }, "sources": { "description": "Per-source identifiers. Maps source ID (e.g., repository ID, Kubernetes server/namespace) to its current marker (e.g., abbreviated commit SHA, resource version).", "type": "object", "additionalProperties": { "type": "string" } } } }, "GitOpsError": { "title": "Root Type for GitOpsError", "description": "Describes an error that occurred during a GitOps sync attempt.", "type": "object", "properties": { "detail": { "description": "A human-readable description of the error.", "type": "string" }, "source": { "description": "The source ID (e.g., repository ID) where the error occurred. Absent for global errors not tied to a specific source.", "type": "string" }, "context": { "description": "The file path or location where the error occurred. Absent if the error is not file-specific.", "type": "string" } }, "required": [ "detail" ] }, "GitOpsValidateRequest": { "title": "Root Type for GitOpsValidateRequest", "description": "Request body for creating a dry-run validation task.", "type": "object", "properties": { "type": { "description": "Validation type. Currently only `pull` is supported.", "type": "string", "enum": [ "pull" ] }, "repoId": { "description": "Repository ID to validate against. Must match a configured repository.", "type": "string" }, "ref": { "description": "Git ref to validate (branch name, tag, or PR ref like `refs/pull/42/head`).", "type": "string" } }, "required": [ "repoId", "ref" ] }, "GitOpsValidateTask": { "title": "Root Type for GitOpsValidateTask", "description": "Represents a dry-run validation task with its current state and results.", "type": "object", "properties": { "taskId": { "description": "Unique identifier for the validation task.", "type": "string" }, "type": { "description": "Validation type (`pull` or `push`).", "type": "string" }, "repoId": { "description": "Repository ID being validated.", "type": "string" }, "ref": { "description": "Git ref being validated.", "type": "string" }, "state": { "description": "Current task state: `pending` (queued, waiting for capacity), `submitted` (request sent to sidecar), `fetching` (sidecar is cloning), `validating` (registry is loading and validating), `completed` (finished with results), `failed` (an error occurred).", "type": "string", "enum": [ "pending", "submitted", "fetching", "validating", "completed", "failed" ] }, "result": { "description": "Validation result: `success` (all checks passed) or `failure` (validation errors found). Only present when state is `completed`.", "type": "string", "enum": [ "success", "failure" ] }, "createdAt": { "description": "ISO 8601 timestamp of when the task was created.", "format": "date-time", "type": "string" }, "completedAt": { "description": "ISO 8601 timestamp of when the task completed. Only present when state is `completed` or `failed`.", "format": "date-time", "type": "string" }, "groupCount": { "description": "Number of groups loaded during validation. Only present when state is `completed`.", "format": "int32", "type": "integer" }, "artifactCount": { "description": "Number of artifacts loaded during validation. Only present when state is `completed`.", "format": "int32", "type": "integer" }, "versionCount": { "description": "Number of artifact versions loaded during validation. Only present when state is `completed`.", "format": "int32", "type": "integer" }, "errors": { "description": "Validation errors. Empty if validation passed.", "type": "array", "items": { "$ref": "#/components/schemas/GitOpsError" } } }, "required": [ "taskId", "state" ] }, "SystemInfo": { "title": "Root Type for SystemInfo", "description": "", "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "builtOn": { "format": "date-time", "type": "string" } }, "example": { "name": "Apicurio Registry (SQL)", "description": "The Apicurio Registry application.", "version": "2.0.0.Final", "builtOn": "2021-03-19T12:55:00Z" } }, "FileContent": { "format": "binary", "type": "string", "x-codegen-inline": true }, "RoleMapping": { "description": "The mapping between a user/principal and their role.", "required": [ "principalId", "role" ], "type": "object", "properties": { "principalId": { "description": "", "type": "string" }, "role": { "$ref": "#/components/schemas/RoleType", "description": "" }, "principalName": { "description": "A friendly name for the principal.", "type": "string" } }, "example": { "principalId": "svc_account_84874587_123484", "principalName": "famartin-svc-account", "role": "READ_ONLY" } }, "RoleType": { "description": "", "enum": [ "READ_ONLY", "DEVELOPER", "ADMIN" ], "type": "string", "x-codegen-package": "io.apicurio.registry.types" }, "UpdateRole": { "title": "Root Type for UpdateRole", "description": "", "required": [ "role" ], "type": "object", "properties": { "role": { "$ref": "#/components/schemas/RoleType" } }, "example": { "role": "READ_ONLY" } }, "UserInfo": { "title": "Root Type for UserInfo", "description": "Information about a single user.", "type": "object", "properties": { "username": { "type": "string" }, "displayName": { "type": "string" }, "admin": { "type": "boolean" }, "developer": { "type": "boolean" }, "viewer": { "type": "boolean" } }, "example": { "username": "dprince", "displayName": "Diana Prince", "admin": true, "developer": false, "viewer": false } }, "DownloadRef": { "title": "Root Type for Download", "description": "Models a download \"link\". Useful for browser use-cases.", "required": [ "downloadId" ], "type": "object", "properties": { "downloadId": { "type": "string" }, "href": { "type": "string" } }, "example": { "downloadId": "247-4987490-297845", "href": "https://54321.registry.examples.org/apis/registry/v3/downloads/247-4987490-297845" } }, "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" } } }, "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" } }, "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" } } }, "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 } }, "RuleViolationProblemDetails": { "title": "Root Type for Error", "description": "All error responses, whether `4xx` or `5xx` will include one of these as the response\nbody.", "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" }, "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" } }, "ConfigurationProperty": { "title": "Root Type for ConfigurationProperty", "description": "", "required": [ "name", "value", "type", "label", "description" ], "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "type": { "description": "", "type": "string" }, "label": { "description": "", "type": "string" }, "description": { "description": "", "type": "string" } }, "example": { "name": "registry.auth.owner-only-authorization", "value": "true", "type": "boolean", "label": "Owner Only Authorization", "description": "When enabled, the registry will allow only the artifact owner (creator) to modify an artifact." } }, "UpdateConfigurationProperty": { "title": "Root Type for UpdateConfigurationProperty", "description": "", "required": [ "value" ], "type": "object", "properties": { "value": { "type": "string" } }, "example": { "value": "true" } }, "SearchedGroup": { "description": "Models a single group from the result set returned when searching for groups.", "required": [ "owner", "createdOn", "groupId", "modifiedBy", "modifiedOn" ], "type": "object", "properties": { "description": { "description": "", "type": "string" }, "createdOn": { "format": "date-time", "description": "", "type": "string" }, "owner": { "description": "", "type": "string" }, "modifiedOn": { "format": "date-time", "description": "", "type": "string" }, "modifiedBy": { "description": "", "type": "string" }, "groupId": { "$ref": "#/components/schemas/GroupId", "description": "" }, "labels": { "$ref": "#/components/schemas/Labels", "description": "" } }, "example": { "groupId": "My-Group", "name": "Group Name", "description": "Description of the group", "owner": "user1", "createdOn": "2019-03-22T12:51:19Z", "modifiedBy": "user1", "modifiedOn": "2019-03-22T12:51:19Z" } }, "GroupMetaData": { "title": "Root Type for GroupMetaData", "description": "", "required": [ "groupId", "owner", "createdOn", "modifiedBy", "modifiedOn" ], "type": "object", "properties": { "description": { "type": "string" }, "owner": { "type": "string" }, "createdOn": { "format": "date-time", "type": "string" }, "modifiedBy": { "type": "string" }, "modifiedOn": { "format": "date-time", "type": "string" }, "labels": { "$ref": "#/components/schemas/Labels", "description": "" }, "groupId": { "$ref": "#/components/schemas/GroupId", "description": "" } }, "example": { "groupId": "group-identifier", "description": "Description of the group", "artifactsType": "AVRO", "owner": "user1", "createdOn": "2019-03-22T12:51:19Z", "modifiedBy": "user2", "modifiedOn": "2019-07-19T15:09:00Z", "properties": { "custom-1": "foo", "custom-2": "bar" } } }, "GroupSearchResults": { "description": "Describes the response received when searching for groups.", "required": [ "count", "groups" ], "type": "object", "properties": { "groups": { "description": "The groups returned in the result set.", "type": "array", "items": { "$ref": "#/components/schemas/SearchedGroup" } }, "count": { "description": "The total number of groups that matched the query that produced the result set (may be \nmore than the number of groups in the result set).", "type": "integer" } } }, "CreateGroup": { "title": "Root Type for CreateGroupMetaData", "description": "", "required": [ "groupId" ], "type": "object", "properties": { "description": { "type": "string" }, "labels": { "$ref": "#/components/schemas/Labels", "description": "" }, "groupId": { "$ref": "#/components/schemas/GroupId", "description": "" } }, "example": { "groupId": "group-identifier", "description": "The description of the artifact.", "labels": { "custom-1": "foo", "custom-2": "bar" } } }, "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" ] } } }, "ReferenceType": { "description": "", "enum": [ "OUTBOUND", "INBOUND" ], "type": "string", "example": "\"INBOUND\"", "x-codegen-package": "io.apicurio.registry.types" }, "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." } }, "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" } }, "HandleReferencesType": { "description": "How to handle references when retrieving content. References can either be\nleft unchanged (`PRESERVE`), re-written so they are valid in the context of the\nregistry (`REWRITE`), or fully dereferenced such that all externally referenced\ncontent is internalized (`DEREFERENCE`).", "enum": [ "PRESERVE", "DEREFERENCE", "REWRITE" ], "type": "string" }, "ArtifactId": { "description": "The ID of a single artifact.", "pattern": "^.{1,512}$", "type": "string", "example": "\"example-artifact\"" }, "GroupId": { "description": "An ID of a single artifact group.", "pattern": "^.{1,512}$", "type": "string", "example": "\"my-group\"" }, "Version": { "description": "A single version of an artifact. Can be provided by the client when creating a new version,\nor it can be server-generated. The value can be any string unique to the artifact, but it is\nrecommended to use a simple integer or a semver value.", "pattern": "^[a-zA-Z0-9._\\-+]{1,256}$", "type": "string", "example": "\"3.1.6\"" }, "BranchId": { "description": "The ID of a single artifact branch.", "pattern": "^[a-zA-Z0-9._\\-+]{1,256}$", "type": "string", "example": "\"latest\"" }, "BranchMetaData": { "title": "Root Type for BranchMetaData", "description": "", "required": [ "groupId", "artifactId", "branchId", "createdOn", "modifiedOn", "modifiedBy", "owner", "systemDefined" ], "type": "object", "properties": { "groupId": { "$ref": "#/components/schemas/GroupId", "description": "" }, "artifactId": { "$ref": "#/components/schemas/ArtifactId", "description": "" }, "branchId": { "$ref": "#/components/schemas/BranchId", "description": "" }, "createdOn": { "format": "date-time", "type": "string" }, "modifiedBy": { "type": "string" }, "modifiedOn": { "format": "date-time", "type": "string" }, "owner": { "description": "", "type": "string" }, "description": { "description": "", "type": "string" }, "systemDefined": { "description": "", "type": "boolean" } }, "example": { "groupId": "ExampleGroup", "artifactId": "ExampleArtifact", "branchId": "1.0.x", "description": "Just an example branch.", "systemDefined": false, "createdOn": "2018-02-10T09:30Z", "modifiedBy": "user1", "modifiedOn": "2020-02-10T09:30Z", "owner": "user2" } }, "UserInterfaceConfig": { "title": "Root Type for UserInterfaceConfig", "description": "Defines the user interface configuration data type.", "required": [ "auth" ], "type": "object", "properties": { "ui": { "$ref": "#/components/schemas/UserInterfaceConfigUi", "properties": { "contextPath": { "type": "string" }, "navPrefixPath": { "type": "string" }, "oaiDocsUrl": { "type": "string" }, "editorsUrl": { "type": "string" } } }, "auth": { "$ref": "#/components/schemas/UserInterfaceConfigAuth", "properties": { "type": { "type": "string" }, "rbacEnabled": { "type": "boolean" }, "obacEnabled": { "type": "boolean" }, "options": { "type": "object", "properties": { "url": { "type": "string" }, "redirectUri": { "type": "string" }, "clientId": { "type": "string" } } } } }, "features": { "$ref": "#/components/schemas/UserInterfaceConfigFeatures", "properties": { "readOnly": { "type": "boolean" }, "breadcrumbs": { "type": "boolean" }, "roleManagement": { "type": "boolean" }, "settings": { "type": "boolean" } } } }, "example": { "ui": { "contextPath": "/", "navPrefixPath": "/", "oaiDocsUrl": "https://registry.apicur.io/docs", "editorsUrl": "https://registry.apicur.io/editors" }, "auth": { "type": "oidc", "rbacEnabled": true, "obacEnabled": false, "options": { "url": "https://auth.apicur.io/realms/apicurio", "redirectUri": "http://registry.apicur.io", "clientId": "apicurio-registry-ui" } }, "features": { "readOnly": false, "breadcrumbs": true, "roleManagement": false, "settings": true } } }, "UserInterfaceConfigAuth": { "title": "Root Type for UserInterfaceConfigAuth", "description": "", "required": [ "obacEnabled", "rbacEnabled" ], "type": "object", "properties": { "type": { "enum": [ "none", "basic", "oidc" ], "type": "string" }, "rbacEnabled": { "type": "boolean" }, "obacEnabled": { "type": "boolean" }, "options": { "$ref": "#/components/schemas/Labels" } }, "example": { "type": "oidc", "rbacEnabled": true, "obacEnabled": false, "options": { "url": "https://auth.apicur.io/realms/apicurio", "redirectUri": "https://registry.apicur.io", "clientId": "registry-ui" } } }, "UserInterfaceConfigFeatures": { "title": "Root Type for UserInterfaceConfigFeatures", "description": "", "type": "object", "properties": { "readOnly": { "type": "boolean" }, "breadcrumbs": { "type": "boolean" }, "roleManagement": { "type": "boolean" }, "settings": { "type": "boolean" }, "deleteGroup": { "description": "", "type": "boolean" }, "deleteArtifact": { "description": "", "type": "boolean" }, "deleteVersion": { "description": "", "type": "boolean" }, "draftMutability": { "description": "", "type": "boolean" }, "agents": { "description": "", "type": "boolean" }, "searchIndex": { "description": "", "type": "boolean" } }, "example": { "readOnly": false, "breadcrumbs": true, "roleManagement": false, "settings": true } }, "UserInterfaceConfigUi": { "title": "Root Type for UserInterfaceConfigUi", "description": "", "type": "object", "properties": { "contextPath": { "type": "string" }, "navPrefixPath": { "type": "string" }, "oaiDocsUrl": { "type": "string" }, "editorsUrl": { "type": "string" } }, "example": { "contextPath": "/", "navPrefixPath": "/", "oaiDocsUrl": "https://registry.apicur.io/docs", "editorsUrl": "https://registry.apicur.io/editors" } }, "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" }, "EditableArtifactMetaData": { "title": "Root Type for EditableArtifactMetaData", "description": "", "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "labels": { "$ref": "#/components/schemas/Labels", "description": "" }, "owner": { "description": "", "type": "string" } }, "example": { "name": "Artifact Name", "description": "The description of the artifact.", "owner": "user-1", "labels": { "custom-1": "foo", "custom-2": "bar" } } }, "EditableGroupMetaData": { "title": "Root Type for EditableGroupMetaData", "description": "", "type": "object", "properties": { "description": { "type": "string" }, "labels": { "$ref": "#/components/schemas/Labels", "description": "" }, "owner": { "description": "", "type": "string" } }, "example": { "description": "The description of the group.", "owner": "user-1", "labels": { "custom-1": "foo", "custom-2": "bar" } } }, "RoleMappingSearchResults": { "description": "Describes the response received when searching for artifacts.", "required": [ "count", "roleMappings" ], "type": "object", "properties": { "roleMappings": { "description": "The role mappings returned in the result set.", "type": "array", "items": { "$ref": "#/components/schemas/RoleMapping" } }, "count": { "description": "The total number of role mappings that matched the query that produced the result set (may be \nmore than the number of role mappings in the result set).", "type": "integer" } }, "example": [ { "principalId": "user-1", "principalName": "user-1", "role": "ADMIN" }, { "principalId": "svc_account_84874587_123484", "principalName": "user-svc-account", "role": "READ_ONLY" } ] }, "EditableVersionMetaData": { "title": "Root Type for EditableArtifactMetaData", "description": "", "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "labels": { "$ref": "#/components/schemas/Labels", "description": "" } }, "example": { "name": "Artifact Name", "description": "The description of the artifact.", "labels": { "custom-1": "foo", "custom-2": "bar" } } }, "VersionState": { "description": "Describes the state of an artifact or artifact version.\n\n* ENABLED\n* DISABLED\n* DEPRECATED\n* DRAFT\n* SUNSET \u2014 Signals that a migration deadline has passed and the version will be removed. Requires transitioning through DEPRECATED first. Added in 3.3.0.\n", "enum": [ "ENABLED", "DISABLED", "DEPRECATED", "DRAFT", "SUNSET" ], "type": "string", "x-codegen-package": "io.apicurio.registry.types" }, "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": {} } } }, "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 } }, "CreateArtifactResponse": { "description": "", "required": [ "artifact" ], "type": "object", "properties": { "artifact": { "$ref": "#/components/schemas/ArtifactMetaData", "description": "" }, "version": { "$ref": "#/components/schemas/VersionMetaData", "description": "" } } }, "VersionSortBy": { "description": "", "enum": [ "groupId", "artifactId", "version", "name", "createdOn", "modifiedOn", "globalId" ], "type": "string" }, "GroupSortBy": { "description": "", "enum": [ "groupId", "createdOn", "modifiedOn" ], "type": "string" }, "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" } } }, "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\nMaximum length: 100 words\nDocument: The quick brown fox jumps over the lazy dog.", "groupId": "default", "artifactId": "summarization-v1", "version": "1.2", "validationErrors": [] } }, "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" } }, "SnapshotMetaData": { "title": "Root Type for SnapshotMetaData", "description": "", "required": [ "snapshotId" ], "type": "object", "properties": { "snapshotId": { "description": "", "type": "string" } }, "example": { "snapshotId": "snp-1137292771" } }, "CreateRule": { "title": "Root Type for Rule", "description": "", "required": [ "config" ], "type": "object", "properties": { "config": { "type": "string" }, "ruleType": { "$ref": "#/components/schemas/RuleType" } }, "example": { "ruleType": "VALIDITY", "config": "FULL" } }, "BranchSearchResults": { "description": "Describes the response received when searching for branches.", "required": [ "count", "branches" ], "type": "object", "properties": { "branches": { "description": "The branches returned in the result set.", "type": "array", "items": { "$ref": "#/components/schemas/SearchedBranch" } }, "count": { "description": "The total number of branches that matched the query that produced the result set (may be \nmore than the number of branches in the result set).", "type": "integer" } } }, "SearchedBranch": { "title": "Root Type for SearchedBranch", "description": "", "required": [ "groupId", "artifactId", "branchId", "createdOn", "owner", "modifiedBy", "modifiedOn", "systemDefined" ], "type": "object", "properties": { "groupId": { "$ref": "#/components/schemas/GroupId", "description": "" }, "artifactId": { "$ref": "#/components/schemas/ArtifactId", "description": "" }, "branchId": { "$ref": "#/components/schemas/BranchId", "description": "" }, "createdOn": { "format": "date-time", "description": "", "type": "string" }, "owner": { "description": "", "type": "string" }, "modifiedOn": { "format": "date-time", "description": "", "type": "string" }, "modifiedBy": { "description": "", "type": "string" }, "description": { "description": "", "type": "string" }, "systemDefined": { "description": "", "type": "boolean" } }, "example": { "groupId": "ExampleGroup", "artifactId": "ExampleArtifact", "branchId": "1.0.x", "description": "A really nice branch.", "systemDefined": false, "createdOn": "2018-02-10T09:30Z", "owner": "user1", "modifiedOn": "2019-03-11T09:30Z", "modifiedBy": "user2" } }, "EditableBranchMetaData": { "title": "Root Type for EditableArtifactMetaData", "description": "", "type": "object", "properties": { "description": { "type": "string" } }, "example": { "description": "The description of the group." } }, "CreateBranch": { "title": "Root Type for CreateBranch", "description": "", "required": [ "branchId" ], "type": "object", "properties": { "description": { "type": "string" }, "branchId": { "$ref": "#/components/schemas/BranchId", "description": "" }, "versions": { "description": "", "type": "array", "items": { "$ref": "#/components/schemas/Version" } } }, "example": { "branchId": "1.0.x", "description": "The description of the branch." } }, "AddVersionToBranch": { "description": "", "required": [ "version" ], "type": "object", "properties": { "version": { "description": "", "type": "string" } } }, "ReplaceBranchVersions": { "description": "", "required": [ "versions" ], "type": "object", "properties": { "versions": { "description": "", "type": "array", "items": { "$ref": "#/components/schemas/Version" } } } }, "WrappedVersionState": { "title": "Root Type for WrappedVersionState", "description": "", "required": [ "state" ], "type": "object", "properties": { "state": { "$ref": "#/components/schemas/VersionState" } }, "example": { "state": "ENABLED" } }, "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" }, "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 } }, "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" } }, "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 } }, "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 } } }, "OdcsContractResult": { "title": "OdcsContractResult", "description": "Result of submitting or updating an ODCS contract.", "type": "object", "properties": { "contractId": { "description": "The contract artifact ID.", "type": "string" }, "version": { "description": "The ODCS contract version.", "type": "string" }, "projection": { "$ref": "#/components/schemas/OdcsProjectionSummary" } } }, "OdcsProjectionSummary": { "title": "OdcsProjectionSummary", "description": "Summary of the projection performed when an ODCS contract is applied.", "type": "object", "properties": { "rulesApplied": { "description": "Number of CEL quality rules projected onto the schema artifact.", "type": "integer", "format": "int32" }, "labelsApplied": { "description": "Number of contract.* labels set on the schema artifact.", "type": "integer", "format": "int32" }, "tagsApplied": { "description": "Number of field-tag.* labels set on the schema artifact version.", "type": "integer", "format": "int32" }, "warnings": { "description": "Any warnings encountered during projection.", "type": "array", "items": { "type": "string" } } } }, "OdcsContractSummary": { "title": "OdcsContractSummary", "description": "Summary of an ODCS contract.", "type": "object", "properties": { "contractId": { "description": "The contract artifact ID.", "type": "string" }, "name": { "description": "The contract display name.", "type": "string" } } }, "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" } } }, "EditableContractMetadata": { "title": "EditableContractMetadata", "description": "Editable contract metadata fields.", "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" ] }, "compatibilityGroup": { "description": "Compatibility group for schema evolution scoping.", "type": "string" } } }, "ContractRuleSet": { "title": "ContractRuleSet", "description": "A set of contract rules, divided into domain and migration categories.", "type": "object", "properties": { "domainRules": { "description": "Rules for domain validation.", "type": "array", "items": { "$ref": "#/components/schemas/ContractRule" } }, "migrationRules": { "description": "Rules for version migration.", "type": "array", "items": { "$ref": "#/components/schemas/ContractRule" } } } }, "ContractRule": { "title": "ContractRule", "description": "A single contract rule definition.", "required": [ "name", "kind", "type", "mode" ], "type": "object", "properties": { "name": { "description": "The rule name.", "type": "string" }, "kind": { "description": "The rule kind.", "type": "string", "enum": [ "CONDITION", "TRANSFORM" ] }, "type": { "description": "Rule executor type (CEL, CEL_FIELD, ENCRYPT, etc.).", "type": "string" }, "mode": { "description": "When the rule is applied.", "type": "string", "enum": [ "WRITE", "READ", "WRITEREAD", "UPGRADE", "DOWNGRADE" ] }, "expr": { "description": "The rule expression.", "type": "string" }, "params": { "description": "Rule parameters.", "type": "object", "additionalProperties": { "type": "string" } }, "tags": { "description": "Tags for categorizing the rule.", "type": "array", "items": { "type": "string" } }, "onSuccess": { "description": "Action on rule success.", "type": "string", "enum": [ "NONE", "ERROR", "DLQ" ] }, "onFailure": { "description": "Action on rule failure.", "type": "string", "enum": [ "NONE", "ERROR", "DLQ" ] }, "disabled": { "description": "Whether the rule is disabled.", "type": "boolean" } } }, "ContractRuleSearchResult": { "title": "ContractRuleSearchResult", "description": "A contract rule with its artifact coordinates, returned by tag search.", "type": "object", "properties": { "groupId": { "description": "The group ID of the artifact containing the rule.", "type": "string" }, "artifactId": { "description": "The artifact ID containing the rule.", "type": "string" }, "globalId": { "description": "The global ID of the version (null for artifact-level rules).", "type": "integer", "format": "int64" }, "ruleCategory": { "description": "The rule category (DOMAIN or MIGRATION).", "type": "string", "enum": [ "DOMAIN", "MIGRATION" ] }, "rule": { "$ref": "#/components/schemas/ContractRule" } } }, "ContractStatusTransition": { "title": "ContractStatusTransition", "description": "Request body for transitioning the contract lifecycle status.", "required": [ "status" ], "type": "object", "properties": { "status": { "description": "The target lifecycle status. Valid transitions: DRAFT to STABLE, DRAFT to DEPRECATED, STABLE to DEPRECATED.", "type": "string", "enum": [ "DRAFT", "STABLE", "DEPRECATED" ] } } }, "UsageClassification": { "description": "Classification of schema usage based on last fetch time.", "type": "string", "enum": [ "ACTIVE", "STALE", "DEAD" ] }, "VersionUsageMetrics": { "title": "VersionUsageMetrics", "description": "Usage metrics for a specific artifact version.", "required": [ "version", "globalId", "totalFetches", "uniqueClients", "firstFetchedOn", "lastFetchedOn", "classification" ], "type": "object", "properties": { "version": { "type": "string" }, "globalId": { "type": "integer", "format": "int64" }, "totalFetches": { "type": "integer", "format": "int64" }, "uniqueClients": { "type": "integer", "format": "int32" }, "firstFetchedOn": { "type": "integer", "format": "int64" }, "lastFetchedOn": { "type": "integer", "format": "int64" }, "clients": { "type": "array", "items": { "type": "string" } }, "classification": { "$ref": "#/components/schemas/UsageClassification" } } }, "ArtifactUsageMetrics": { "title": "ArtifactUsageMetrics", "required": [ "groupId", "artifactId", "versions" ], "type": "object", "properties": { "groupId": { "type": "string" }, "artifactId": { "type": "string" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/VersionUsageMetrics" } } } }, "UsageSummary": { "title": "UsageSummary", "required": [ "active", "stale", "dead" ], "type": "object", "properties": { "active": { "type": "integer", "format": "int32" }, "stale": { "type": "integer", "format": "int32" }, "dead": { "type": "integer", "format": "int32" } } }, "ConsumerVersionEntry": { "title": "ConsumerVersionEntry", "required": [ "clientId" ], "type": "object", "properties": { "clientId": { "type": "string" }, "versions": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" } }, "versionsBehind": { "type": "integer", "format": "int32" }, "driftAlert": { "type": "boolean" } } }, "ConsumerVersionHeatmap": { "title": "ConsumerVersionHeatmap", "required": [ "groupId", "artifactId", "versions", "consumers" ], "type": "object", "properties": { "groupId": { "type": "string" }, "artifactId": { "type": "string" }, "versions": { "type": "array", "items": { "type": "string" } }, "consumers": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerVersionEntry" } } } }, "DeprecationReadiness": { "title": "DeprecationReadiness", "required": [ "groupId", "artifactId", "version", "safeToDeprecate" ], "type": "object", "properties": { "groupId": { "type": "string" }, "artifactId": { "type": "string" }, "version": { "type": "string" }, "globalId": { "type": "integer", "format": "int64" }, "activeConsumers": { "type": "array", "items": { "type": "object", "properties": { "clientId": { "type": "string" }, "lastFetched": { "type": "integer", "format": "int64" }, "fetchCount": { "type": "integer", "format": "int64" } } } }, "safeToDeprecate": { "type": "boolean" } } }, "AgentCard": { "description": "Represents an A2A Agent Card.", "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "protocolVersion": { "type": "string" }, "provider": { "$ref": "#/components/schemas/AgentProvider" }, "capabilities": { "$ref": "#/components/schemas/AgentCapabilities" }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSkill" } }, "defaultInputModes": { "type": "array", "items": { "type": "string" } }, "defaultOutputModes": { "type": "array", "items": { "type": "string" } }, "supportedInterfaces": { "type": "array", "items": { "$ref": "#/components/schemas/AgentInterface" } }, "securitySchemes": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/AgentSecurityScheme" } }, "securityRequirements": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSecurityRequirement" } }, "iconUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCardSignature" } } } }, "AgentProvider": { "description": "Provider of an A2A agent.", "type": "object", "properties": { "organization": { "type": "string" }, "url": { "type": "string" } } }, "AgentCapabilities": { "description": "Capabilities of an A2A agent.", "type": "object", "properties": { "streaming": { "type": "boolean" }, "pushNotifications": { "type": "boolean" }, "extendedAgentCard": { "type": "boolean" }, "extensions": { "type": "array", "items": { "$ref": "#/components/schemas/AgentExtension" } } } }, "AgentExtension": { "description": "Extension for an A2A agent.", "type": "object", "properties": { "uri": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" }, "params": { "type": "object", "additionalProperties": {} } } }, "AgentSkill": { "description": "A skill an A2A agent can perform.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "examples": { "type": "array", "items": { "type": "string" } }, "inputModes": { "type": "array", "items": { "type": "string" } }, "outputModes": { "type": "array", "items": { "type": "string" } }, "securityRequirements": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSecurityRequirement" } } } }, "AgentInterface": { "description": "Interface endpoint for an A2A agent.", "type": "object", "properties": { "url": { "type": "string" }, "protocolBinding": { "type": "string" }, "protocolVersion": { "type": "string" }, "tenant": { "type": "string" } } }, "AgentSecurityScheme": { "description": "Security scheme for an A2A agent.", "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" }, "location": { "type": "string" }, "name": { "type": "string" }, "scheme": { "type": "string" }, "bearerFormat": { "type": "string" }, "flows": { "type": "object", "additionalProperties": {} }, "oauth2MetadataUrl": { "type": "string" }, "openIdConnectUrl": { "type": "string" } } }, "AgentSecurityRequirement": { "description": "Security requirement for an A2A agent.", "type": "object", "properties": { "schemes": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "AgentCardSignature": { "description": "Signature on an agent card.", "type": "object", "properties": { "protected": { "type": "string" }, "signature": { "type": "string" }, "header": { "type": "object", "additionalProperties": {} } } }, "AgentSearchResult": { "description": "Agent card search result.", "type": "object", "properties": { "groupId": { "type": "string" }, "artifactId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "supportedInterfaces": { "type": "array", "items": { "$ref": "#/components/schemas/AgentInterface" } }, "skills": { "type": "array", "items": { "type": "string" } }, "capabilities": { "$ref": "#/components/schemas/AgentCapabilities" }, "createdOn": { "format": "int64", "type": "integer" }, "owner": { "type": "string" } } }, "AgentSearchResults": { "description": "Search results for agent cards.", "required": [ "count", "agents" ], "type": "object", "properties": { "count": { "type": "integer" }, "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSearchResult" } } } }, "AgentSearchRequest": { "description": "Request body for advanced agent search.", "type": "object", "properties": { "query": { "type": "string" }, "filters": { "$ref": "#/components/schemas/AgentSearchFilters" }, "limit": { "default": 20, "type": "integer" }, "offset": { "default": 0, "type": "integer" } } }, "AgentSearchFilters": { "description": "Filters for advanced agent search.", "type": "object", "properties": { "capabilities": { "type": "object", "additionalProperties": { "type": "boolean" } }, "skills": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "object", "additionalProperties": { "type": "string" } }, "inputModes": { "type": "array", "items": { "type": "string" } }, "outputModes": { "type": "array", "items": { "type": "string" } }, "protocolBindings": { "type": "array", "items": { "type": "string" } } } }, "McpToolSearchResult": { "description": "MCP tool search result.", "type": "object", "properties": { "groupId": { "type": "string" }, "artifactId": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "owner": { "type": "string" }, "createdOn": { "format": "int64", "type": "integer" }, "parameters": { "type": "array", "items": { "type": "string" } } } }, "McpToolSearchResults": { "description": "Search results for MCP tools.", "required": [ "count", "tools" ], "type": "object", "properties": { "count": { "type": "integer" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/McpToolSearchResult" } } } } }, "responses": { "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." }, "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." }, "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." }, "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." }, "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." }, "RuleViolationBadRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleViolationProblemDetails" }, "examples": { "RuleViolationBadRequestExample": { "value": { "error_code": 400, "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 the content of the request violates one or more configured rules." }, "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." }, "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:\n* Schema validation failed\n* References could not be validated\n* Required references are missing" }, "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." }, "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." } } }, "tags": [ { "name": "Artifacts", "description": "The primary way to interact with the Apicurio Registry API is to add, update, \nor delete artifacts. This section includes all of these primary operations." }, { "name": "Metadata", "description": "Sometimes the metadata for an artifact is important. For example, metadata includes \nwhen the artifact was created, last updated, and so on. This section contains \noperations to access (and in some cases change) an artifact's metadata." }, { "name": "Versions", "description": "When artifact content is updated, old versions of the artifact content are not lost. All versions can be listed and accessed if necessary. This section describes the operations used to list and access all versions of an artifact's content and metadata." }, { "name": "Artifact rules", "description": "Rules can be configured on a per-artifact basis, allowing for different approaches\nto content evolution for each artifact. These rules override any global rules\nthat have been configured. This section contains the operations used to manage a\nsingle artifact's rules." }, { "name": "Global rules", "description": "Global rules can be configured in the registry to govern how artifact content can \nevolve over time (as artifact content is **updated**). Global rules are applied \nwhenever an artifact is added to the registry, and also whenever an artifact's \ncontent is updated (only if that artifact does not have its own specific rules \nconfigured). This section describes the operations used to manage the global rules." }, { "name": "Search", "description": "The search API is used to browse or find artifacts in the registry. This section describes the operations for searching for artifacts and versions." }, { "name": "Admin", "description": "Application functionality that is only accessible to admin users. Includes logging, global rules, and export/import of registry data." }, { "name": "System", "description": "System level functionality, including versioning and status information." }, { "name": "Users", "description": "Operations related to users." }, { "name": "Groups", "description": "Registry artifacts can be collected together using groups. This section includes all of the primary operations related to groups." }, { "name": "Branches", "description": "Artifacts can optionally have branches that are just an ordered list of version identifiers." }, { "name": "Group rules", "description": "Rules can be configured on a per-group basis, allowing for different approaches\nto content evolution for artifacts in the group. These rules override any global rules\nthat have been configured. This section contains the operations used to manage the\nrules in a single group." }, { "name": "AI", "description": "Operations related to AI/ML artifact management, including prompt template rendering, model schema queries, and LLM integration features." }, { "name": "GitOps", "description": "Experimental. Management and status endpoints for the GitOps storage backend. These endpoints are only available when the registry is configured with `apicurio.storage.kind=gitops`." }, { "name": "WellKnown", "description": "Well-known discovery endpoints for A2A agents, MCP tools, and JSON schemas." } ], "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 } ] } }