Apicurio GitOps API

openapi: 3.1.0
info:
  title: Apicurio Registry Admin GitOps API
  version: 3.1.x
  description: Apicurio Registry is a high-performance, runtime registry for schemas and API designs. It stores and manages OpenAPI, AsyncAPI, Avro, JSON Schema, Protobuf, and other artifact types, providing a REST API for schema management with compatibility checking and content versioning.
  contact:
    name: Apicurio
    url: https://www.apicur.io/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:8080/apis/registry/v3
  description: Local Apicurio Registry
tags:
- name: GitOps
paths:
  /admin/gitops/status:
    summary: Get the current GitOps synchronization status.
    get:
      tags:
      - GitOps
      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.


        This endpoint is only available when GitOps storage is enabled (`apicurio.storage.kind=gitops`). Returns HTTP 409 (Conflict) if a different storage backend is active.


        This operation can fail for the following reasons:


        * GitOps storage is not enabled (HTTP error `409`)

        * A server error occurred (HTTP error `500`)

        '
  /admin/gitops/sync:
    summary: Trigger an immediate GitOps synchronization.
    post:
      tags:
      - GitOps
      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.


        The synchronization happens asynchronously — this endpoint returns immediately and the actual sync occurs on the next scheduler cycle.


        This endpoint is only available when GitOps storage is enabled (`apicurio.storage.kind=gitops`). Returns HTTP 409 (Conflict) if a different storage backend is active.


        This operation can fail for the following reasons:


        * GitOps storage is not enabled (HTTP error `409`)

        * A server error occurred (HTTP error `500`)

        '
components:
  schemas:
    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
    ProblemDetails:
      title: Root Type for Error
      description: 'All error responses, whether `4xx` or `5xx` will include one of these as the response

        body.'
      required:
      - title
      - status
      type: object
      properties:
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        type:
          description: A URI reference [RFC3986] that identifies the problem type.
          type: string
        title:
          description: A short, human-readable summary of the problem type.
          type: string
        status:
          format: int32
          description: The HTTP status code.
          type: integer
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          type: string
        name:
          description: The name of the error (typically a server exception class name).
          type: string
      example:
        status: 500
        name: NullPointerException
        title: An error occurred somewhere.
    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
  responses:
    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.
    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.
    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.
    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.
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://example.com/realms/apicurio/protocol/openid-connect/token
          scopes:
            read: Read access
            write: Write access
            admin: Admin access
x-codegen:
  suppress-date-time-formatting: true
  bean-annotations:
  - io.quarkus.runtime.annotations.RegisterForReflection
  - annotation: lombok.experimental.SuperBuilder
    excludeEnums: true
  - annotation: lombok.AllArgsConstructor
    excludeEnums: true
  - annotation: lombok.NoArgsConstructor
    excludeEnums: true
  - annotation: lombok.EqualsAndHashCode
    excludeEnums: true
  - annotation: lombok.ToString(callSuper = true)
    excludeEnums: true