openapi: "3.0.0"

info:
  description: lakeFS HTTP API
  title: lakeFS API
  license:
    name: "Apache 2.0"
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0

servers:
  - url: "/api/v1"
    description: lakeFS server endpoint
security:
  - jwt_token: []
  - basic_auth: []
  - cookie_auth: []
  - oidc_auth: []
  - saml_auth: []
components:
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
    jwt_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
    cookie_auth:
      type: apiKey
      in: cookie
      name: internal_auth_session
    oidc_auth:
      type: apiKey
      in: cookie
      name: oidc_auth_session
    saml_auth:
      type: apiKey
      in: cookie
      name: saml_auth_session

  parameters:
    PaginationPrefix:
      in: query
      name: prefix
      allowEmptyValue: true
      description: return items prefixed with this value
      schema:
        type: string

    PaginationAfter:
      in: query
      name: after
      description: return items after this value
      allowEmptyValue: true
      schema:
        type: string

    PaginationAmount:
      in: query
      name: amount
      description: how many items to return
      schema:
        type: integer
        minimum: -1
        maximum: 1000
        default: 100

    PaginationDelimiter:
      in: query
      name: delimiter
      allowEmptyValue: true
      description: delimiter used to group common prefixes by
      schema:
        type: string

    SearchString:
      in: query
      name: search
      allowEmptyValue: true
      description: string for searching relevant entries
      schema:
        type: string

    IfNoneMatch:
      in: header
      name: If-None-Match
      description: Set to "*" to atomically allow the upload only if the key has no object yet. Other values are not supported.
      example: "*"
      required: false
      schema:
        type: string

    IfMatch:
      in: header
      name: If-Match
      description: Set to the object's ETag to atomically allow operations only if the object's current ETag matches the provided value.
      example: "2e9ec317e197e02e4264d128c2e7e681"
      required: false
      schema:
        type: string

    NoTombstone:
      in: query
      name: no_tombstone
      required: false
      schema:
        type: boolean
        default: false
      description: delete entry without tombstone when possible *EXPERIMENTAL*

  responses:
    NotFoundOrNoACL:
      description: Group not found, or group found but has no ACL
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorNoACL"

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    ServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Conflict:
      description: Resource Conflicts With Target
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    PreconditionFailed:
      description: Precondition Failed
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    ValidationError:
      description: Validation Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotImplemented:
      description: Not Implemented
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  schemas:
    Pagination:
      type: object
      required:
        - has_more
        - max_per_page
        - results
        - next_offset
      properties:
        has_more:
          type: boolean
          description: Next page is available
        next_offset:
          type: string
          description: Token used to retrieve the next page
        results:
          type: integer
          minimum: 0
          description: Number of values found in the results
        max_per_page:
          type: integer
          minimum: 0
          description: Maximal number of entries per page

    Repository:
      type: object
      required:
        - creation_date
        - id
        - default_branch
        - storage_namespace
      properties:
        id:
          type: string
        creation_date:
          type: integer
          format: int64
          description: Unix Epoch in seconds
        default_branch:
          type: string
        storage_id:
          type: string
          description: Unique identifier of the underlying data store. *EXPERIMENTAL*
        storage_namespace:
          type: string
          description: Filesystem URI to store the underlying data in (e.g. "s3://my-bucket/some/path/")
        read_only:
          type: boolean
          description: Whether the repository is a read-only repository- not relevant for bare repositories

    RepositoryMetadata:
      type: object
      additionalProperties:
        type: string

    RepositoryMetadataSet:
      type: object
      required:
        - metadata
      properties:
        metadata:
          type: object
          additionalProperties:
            type: string

    RepositoryMetadataKeys:
      type: object
      required:
        - keys
      properties:
        keys:
          type: array
          items:
            type: string
            description: metadata key

    RepositoryList:
      type: object
      required:
        - pagination
        - results
      properties:
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: array
          items:
            $ref: "#/components/schemas/Repository"

    FindMergeBaseResult:
      type: object
      required:
        - source_commit_id
        - destination_commit_id
        - base_commit_id
      properties:
        source_commit_id:
          type: string
          description: "The commit ID of the merge source"
        destination_commit_id:
          type: string
          description: "The commit ID of the merge destination"
        base_commit_id:
          type: string
          description: "The commit ID of the merge base"

    MergeResult:
      type: object
      required:
        - reference
      properties:
        reference:
          type: string

    RepositoryCreation:
      type: object
      required:
        - name
        - storage_namespace
      properties:
        name:
          type: string
          pattern: "^[a-z0-9][a-z0-9-]{2,62}$"
        storage_id:
          type: string
          description: Unique identifier of the underlying data store. *EXPERIMENTAL*
        storage_namespace:
          type: string
          description: 'Filesystem URI to store the underlying data in (e.g. "s3://my-bucket/some/path/")'
          example: "s3://example-bucket/"
          pattern: "^(s3|gs|https?|mem|local|transient)://.*$"
        default_branch:
          type: string
          example: "main"
        sample_data:
          type: boolean
          default: false
          example: true
        read_only:
          type: boolean
          default: false
          example: true

    PathList:
      type: object
      required:
        - paths
      properties:
        paths:
          type: array
          items:
            type: string
            description: Object path

    DiffObjectStat:
      type: object
      required:
        - checksum
        - mtime
        - content_type
      properties:
        checksum:
          type: string
        mtime:
          type: integer
          format: int64
          description: Unix Epoch in seconds
        content_type:
          type: string
          description: Object media type
        metadata:
          $ref: "#/components/schemas/ObjectUserMetadata"

    ObjectStats:
      type: object
      required:
        - checksum
        - physical_address
        - path
        - path_type
        - mtime
      properties:
        path:
          type: string
        path_type:
          type: string
          enum: [common_prefix, object]
        physical_address:
          type: string
          description: |
            The location of the object on the underlying object store.
            Formatted as a native URI with the object store type as scheme ("s3://...", "gs://...", etc.)
            Or, in the case of presign=true, will be an HTTP URL to be consumed via regular HTTP GET
        physical_address_expiry:
          type: integer
          format: int64
          description: |
            If present and nonzero, physical_address is a pre-signed URL and
            will expire at this Unix Epoch time.  This will be shorter than
            the pre-signed URL lifetime if an authentication token is about
            to expire.

            This field is *optional*.
        checksum:
          type: string
        size_bytes:
          type: integer
          format: int64
          description: |
            The number of bytes in the object.  lakeFS always populates this
            field when returning ObjectStats.  This field is optional _for
            the client_ to supply, for instance on upload.
        mtime:
          type: integer
          format: int64
          description: Unix Epoch in seconds
        metadata:
          $ref: "#/components/schemas/ObjectUserMetadata"
        content_type:
          type: string
          description: Object media type

    ObjectStatsList:
      type: object
      required:
        - pagination
        - results
      properties:
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: array
          items:
            $ref: "#/components/schemas/ObjectStats"

    UpdateObjectUserMetadata:
      type: object
      required:
        - set
      properties:
        set:
          description: Set this object user metadata
          $ref: "#/components/schemas/ObjectUserMetadata"

    ObjectCopyCreation:
      type: object
      required:
        - src_path
      properties:
        src_path:
          type: string
          description: path of the copied object relative to the ref
        src_ref:
          type: string
          description: a reference, if empty uses the provided branch as ref
        force:
          type: boolean
          default: false
        shallow:
          description: |
            Create a shallow copy of the object (without copying the actual data). At the moment shallow copy only works for same repository and branch. 
            Please note that shallow copied objects might be in contention with garbage collection and branch retention policies - use with caution.
          type: boolean
          default: false

    ObjectStageCreation:
      type: object
      required:
        - physical_address
        - checksum
        - size_bytes
      properties:
        physical_address:
          type: string
        checksum:
          type: string
        size_bytes:
          type: integer
          format: int64
        mtime:
          type: integer
          format: int64
          description: Unix Epoch in seconds
        metadata:
          $ref: "#/components/schemas/ObjectUserMetadata"
        content_type:
          type: string
          description: Object media type
        force:
          type: boolean
          default: false

    ObjectUserMetadata:
      type: object
      additionalProperties:
        type: string

    UnderlyingObjectProperties:
      type: object
      properties:
        storage_class:
          type: string
          nullable: true
    Ref:
      type: object
      required:
        - id
        - commit_id
      properties:
        id:
          type: string
        commit_id:
          type: string

    RefList:
      type: object
      required:
        - pagination
        - results
      properties:
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: array
          items:
            $ref: "#/components/schemas/Ref"

    Diff:
      type: object
      required:
        - type
        - path
        - path_type
      properties:
        type:
          type: string
          enum: [added, removed, changed, conflict, prefix_changed]
        path:
          type: string
        path_type:
          type: string
          enum: [common_prefix, object]
        size_bytes:
          type: integer
          description: represents the size of the added/changed/deleted entry
          format: int64
        right:
          $ref: "#/components/schemas/DiffObjectStat"
          description: ObjectStats of the right side of the diff.

    DiffList:
      type: object
      required:
        - pagination
        - results
      properties:
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: array
          items:
            $ref: "#/components/schemas/Diff"

    ResetCreation:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum: [object, common_prefix, reset]
          description: What to reset according to path.
        path:
          type: string
        force:
          type: boolean
          default: false

    CommitOverrides:
      type: object
      properties:
        message:
          type: string
          description: replace the commit message
        metadata:
          type: object
          description: replace the metadata of the commit
          additionalProperties:
            type: string

    RevertCreation:
      type: object
      required:
        - parent_number
        - ref
      properties:
        ref:
          type: string
          description: the commit to revert, given by a ref
        commit_overrides:
          $ref: "#/components/schemas/CommitOverrides"
        parent_number:
          type: integer
          description: when reverting a merge commit, the parent number (starting from 1) relative to which to perform the revert.
        force:
          type: boolean
          default: false
        allow_empty:
          type: boolean
          default: false
          description: allow empty commit (revert without changes)

    CherryPickCreation:
      type: object
      required:
        - ref
      properties:
        ref:
          type: string
          description: the commit to cherry-pick, given by a ref
        parent_number:
          type: integer
          description: |
            When cherry-picking a merge commit, the parent number (starting from 1) with which to perform the diff.
            The default branch is parent 1.
        commit_overrides:
          $ref: "#/components/schemas/CommitOverrides"
        force:
          type: boolean
          default: false

    Commit:
      type: object
      required:
        - id
        - parents
        - committer
        - message
        - creation_date
        - meta_range_id
      properties:
        id:
          type: string
        parents:
          type: array
          items:
            type: string
        committer:
          type: string
        message:
          type: string
        creation_date:
          type: integer
          format: int64
          description: Unix Epoch in seconds
        meta_range_id:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        generation:
          type: integer
          format: int64
        version:
          type: integer
          minimum: 0
          maximum: 1

    CommitList:
      type: object
      required:
        - pagination
        - results
      properties:
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: array
          items:
            $ref: "#/components/schemas/Commit"

    CommitCreation:
      type: object
      required:
        - message
      properties:
        message:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        date:
          description: set date to override creation date in the commit (Unix Epoch in seconds)
          type: integer
          format: int64
        allow_empty:
          description: sets whether a commit can contain no changes
          type: boolean
          default: false
        force:
          type: boolean
          default: false

    CommitRecordCreation:
      type: object
      required:
        - commit_id
        - version
        - committer
        - message
        - metarange_id
        - creation_date
        - parents
        - generation
      properties:
        commit_id:
          type: string
          description: id of the commit record
        version:
          type: integer
          minimum: 0
          maximum: 1
          description: version of the commit record
        committer:
          type: string
          description: committer of the commit record
        message:
          type: string
          description: message of the commit record
        metarange_id:
          type: string
          description: metarange_id of the commit record
        creation_date:
          type: integer
          format: int64
          description: Unix Epoch in seconds
        parents:
          type: array
          items:
            type: string
          description: parents of the commit record
        metadata:
          type: object
          additionalProperties:
            type: string
          description: metadata of the commit record
        generation:
          type: integer
          format: int64
          description: generation of the commit record
        force:
          type: boolean
          default: false

    Merge:
      type: object
      properties:
        message:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        strategy:
          description: In case of a merge conflict, this option will force the merge process to automatically favor changes from the dest branch ('dest-wins') or from the source branch('source-wins'). In case no selection is made, the merge process will fail in case of a conflict
          type: string
        force:
          type: boolean
          default: false
          description: Allow merge into a read-only branch or into a branch with the same content
        allow_empty:
          type: boolean
          default: false
          description: Allow merge when the branches have the same content
        squash_merge:
          type: boolean
          default: false
          description: |
            If set, set only the destination branch as a parent, which "squashes" the merge to
            appear as a single commit on the destination branch.  The source commit is no longer
            a part of the merge commit; consider adding it to the 'metadata' or 'message'
            fields.  This behaves like a GitHub or GitLab "squash merge", or in Git terms 'git
            merge --squash; git commit ...'.
    BranchCreation:
      type: object
      required:
        - name
        - source
      properties:
        name:
          type: string
        source:
          type: string
        force:
          type: boolean
          default: false
        hidden:
          type: boolean
          description: When set, branch will not show up when listing branches by default. *EXPERIMENTAL*
          default: false

    TagCreation:
      type: object
      description: Make tag ID point at this REF.
      required:
        - id
        - ref
      properties:
        id:
          type: string
          description: ID of tag to create
        ref:
          type: string
          description: the commit to tag
        force:
          type: boolean
          default: false

    TaskInfo:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: ID of the task

    RepositoryDumpStatus:
      type: object
      required:
        - id
        - done
        - update_time
      properties:
        id:
          type: string
          description: ID of the task
        done:
          type: boolean
        update_time:
          type: string
          format: date-time
        error:
          type: string
        refs:
          $ref: "#/components/schemas/RefsDump"

    RepositoryRestoreStatus:
      type: object
      required:
        - id
        - done
        - update_time
      properties:
        id:
          type: string
          description: ID of the task
        done:
          type: boolean
        update_time:
          type: string
          format: date-time
        error:
          type: string

    RefsDump:
      type: object
      required:
        - branches_meta_range_id
        - tags_meta_range_id
        - commits_meta_range_id
      properties:
        commits_meta_range_id:
          type: string
        tags_meta_range_id:
          type: string
        branches_meta_range_id:
          type: string

    RefsRestore:
      type: object
      required:
        - branches_meta_range_id
        - tags_meta_range_id
        - commits_meta_range_id
      properties:
        commits_meta_range_id:
          type: string
        tags_meta_range_id:
          type: string
        branches_meta_range_id:
          type: string
        force:
          type: boolean
          default: false

    StorageURI:
      description: URI to a path in a storage provider (e.g. "s3://bucket1/path/to/object")
      required:
        - location
      type: object
      properties:
        location:
          type: string

    Error:
      type: object
      required:
        - message
      properties:
        message:
          description: short message explaining the error
          type: string

    ObjectError:
      type: object
      required:
        - status_code
        - message
      properties:
        status_code:
          type: integer
          description: HTTP status code associated for operation on path
        message:
          type: string
          description: short message explaining status_code
        path:
          type: string
          description: affected path

    ObjectErrorList:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: "#/components/schemas/ObjectError"

    ErrorNoACL:
      type: object
      required:
        - message
      properties:
        message:
          description: short message explaining the error
          type: string
        no_acl:
          description: "true if the group exists but has no ACL"
          type: boolean

    User:
      type: object
      required:
        - id
        - creation_date
      properties:
        id:
          type: string
          description: A unique identifier for the user. Cannot be edited.
        creation_date:
          type: integer
          format: int64
          description: Unix Epoch in seconds
        friendly_name:
          type: string
          description: |
            A shorter name for the user than the id. Unlike id it does not identify the user (it
            might not be unique). Used in some places in the UI.
        email:
          type: string
          description: |
            The email address of the user. If API authentication is enabled, this field is mandatory and will be invited to login.
            If API authentication is disabled, this field will be ignored. All current APIAuthenticators require the email to be 
            lowercase and unique, although custom authenticators may not enforce this.

    CurrentUser:
      type: object
      required:
        - user
      properties:
        user:
          $ref: "#/components/schemas/User"

    UserCreation:
      type: object
      properties:
        id:
          type: string
          description: a unique identifier for the user.
        invite_user:
          type: boolean
      required:
        - id

    LoginConfig:
      type: object
      properties:
        RBAC:
          description: |
            RBAC will remain enabled on GUI if "external".  That only works
            with an external auth service.
          type: string
          enum: [none, simplified, internal, external]
        username_ui_placeholder:
          description: |
            Placeholder text to display in the username field of the login form.
          type: string
        password_ui_placeholder:
          description: |
            Placeholder text to display in the password field of the login form.
          type: string
        login_url:
          description: Primary URL to use for login.
          type: string
        login_url_method:
          type: string
          description: |
            Defines login behavior when login_url is set.
            - none: For OSS users.
            - redirect: Auto-redirect to login_url.
            - select: Show a page to choose between logging in via login_url or with lakeFS credentials.
            Ignored if login_url is not configured.
          enum:
            - none
            - redirect
            - select
        login_failed_message:
          description: |
            Message to display to users who fail to login; a full sentence that is rendered
            in HTML and may contain a link to a secondary login method
          type: string
        fallback_login_url:
          description: Secondary URL to offer users to use for login.
          type: string
        fallback_login_label:
          description: Label to place on fallback_login_url.
          type: string
        login_cookie_names:
          description: Cookie names used to store JWT
          type: array
          items:
            type: string
        logout_url:
          description: URL to use for logging out.
          type: string
      required:
        - login_url
        - login_cookie_names
        - logout_url

    SetupState:
      type: object
      properties:
        state:
          type: string
          enum: [initialized, not_initialized]
        comm_prefs_missing:
          type: boolean
          description: true if the comm prefs are missing.
        login_config:
          $ref: "#/components/schemas/LoginConfig"
    AccessKeyCredentials:
      type: object
      properties:
        # Example values as seen on
        # https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html
        access_key_id:
          description: access key ID to set for user for use in integration testing.
          example: AKIAIOSFODNN7EXAMPLE
          type: string
          minLength: 1
        secret_access_key:
          description: secret access key to set for user for use in integration testing.
          example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
          type: string
          minLength: 1
      required:
        - access_key_id
        - secret_access_key

    Setup:
      type: object
      properties:
        username:
          description: an identifier for the user (e.g. jane.doe)
          type: string
        key:
          $ref: "#/components/schemas/AccessKeyCredentials"
        firstName:
          description: the provided first name
          type: string
        lastName:
          description: the provided last name
          type: string
        email:
          description: the provided email
          type: string
        companyName:
          description: the provided company name
          type: string
        featureUpdates:
          description: user preference to receive feature updates
          type: boolean
        securityUpdates:
          description: user preference to receive security updates
          type: boolean
      required:
        - username

    CommPrefsInput:
      type: object
      properties:
        firstName:
          description: the provided first name
          type: string
        lastName:
          description: the provided last name
          type: string
        email:
          description: the provided email
          type: string
        companyName:
          description: the provided company name
          type: string
        featureUpdates:
          description: user preference to receive feature updates
          type: boolean
        securityUpdates:
          description: user preference to receive security updates
          type: boolean
      required:
        - featureUpdates
        - securityUpdates

    Credentials:
      type: object
      required:
        - creation_date
        - access_key_id
      properties:
        access_key_id:
          type: string
        creation_date:
          type: integer
          format: int64
          description: Unix Epoch in seconds

    CredentialsList:
      type: object
      required:
        - pagination
        - results
      properties:
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: array
          items:
            $ref: "#/components/schemas/Credentials"

    CredentialsWithSecret:
      type: object
      required:
        - access_key_id
        - creation_date
        - secret_access_key
      properties:
        access_key_id:
          type: string
        secret_access_key:
          type: string
        creation_date:
          type: integer
          format: int64
          description: Unix Epoch in seconds

    Group:
      type: object
      required:
        - creation_date
        - id
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        creation_date:
          type: integer
          format: int64
          description: Unix Epoch in seconds

    GroupList:
      type: object
      required:
        - results
        - pagination
      properties:
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: array
          items:
            $ref: "#/components/schemas/Group"

    AuthCapabilities:
      type: object
      properties:
        invite_user:
          type: boolean
        forgot_password:
          type: boolean

    UserList:
      type: object
      required:
        - pagination
        - results
      properties:
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: array
          items:
            $ref: "#/components/schemas/User"

    LoginInformation:
      type: object
      required:
        - access_key_id
        - secret_access_key
      properties:
        access_key_id:
          type: string
        secret_access_key:
          type: string

    ExternalLoginInformation:
      type: object
      required:
        - identityRequest
      properties:
        token_expiration_duration:
          type: integer
        identityRequest:
          type: object

    StsAuthRequest:
      type: object
      required:
        - code
        - state
        - redirect_uri
      properties:
        code:
          type: string
        state:
          type: string
        redirect_uri:
          type: string
        ttl_seconds:
          type: integer
          format: int64
          description: |
            The time-to-live for the generated token in seconds.  The default
            value is 3600 seconds (1 hour) maximum time allowed is 12 hours.
    AuthenticationToken:
      type: object
      required:
        - token
      properties:
        token:
          description: a JWT token that could be used to authenticate requests
          type: string
        token_expiration:
          type: integer
          format: int64
          description: Unix Epoch in seconds

    GroupCreation:
      type: object
      required:
        - id
      properties:
        id:
          type: string
        description:
          type: string

    PolicyCondition:
      type: object
      description: Condition operator (e.g., IpAddress)
      additionalProperties:
        type: array
        items:
          type: string
      example:
        IpAddress:
          - 192.168.0.1/32
          - 192.168.0.2/32

    Statement:
      type: object
      required:
        - effect
        - resource
        - action
      properties:
        effect:
          type: string
          enum: [allow, deny]
        resource:
          type: string
        action:
          type: array
          items:
            type: string
          minItems: 1
        condition:
          type: object
          description: Optional conditions for when this statement applies.
          additionalProperties:
            $ref: "#/components/schemas/PolicyCondition"

    Policy:
      type: object
      required:
        - id
        - statement
      properties:
        id:
          type: string
        creation_date:
          type: integer
          format: int64
          description: Unix Epoch in seconds
        statement:
          type: array
          items:
            $ref: "#/components/schemas/Statement"
          minItems: 1

    PolicyList:
      type: object
      required:
        - pagination
        - results
      properties:
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: array
          items:
            $ref: "#/components/schemas/Policy"

    ACL:
      type: object
      required:
        - permission
      properties:
        permission:
          type: string
          description: |
            Permission level to give this ACL.  "Read", "Write", "Super" and
            "Admin" are all supported.

    StorageConfig:
      type: object
      required:
        - blockstore_type
        - blockstore_namespace_example
        - blockstore_namespace_ValidityRegex
        - pre_sign_support
        - pre_sign_support_ui
        - import_support
        - import_validity_regex
      properties:
        blockstore_type:
          type: string
        blockstore_namespace_example:
          type: string
        blockstore_namespace_ValidityRegex:
          type: string
        default_namespace_prefix:
          type: string
        pre_sign_support:
          type: boolean
        pre_sign_support_ui:
          type: boolean
        import_support:
          type: boolean
        import_validity_regex:
          type: string
        pre_sign_multipart_upload:
          type: boolean
        blockstore_id:
          type: string
        blockstore_description:
          type: string

    StorageConfigList:
      type: array
      items:
        $ref: "#/components/schemas/StorageConfig"

    Config:
      type: object
      properties:
        version_config:
          $ref: "#/components/schemas/VersionConfig"
        storage_config:
          $ref: "#/components/schemas/StorageConfig"
        storage_config_list:
          $ref: "#/components/schemas/StorageConfigList"
        ui_config:
          $ref: "#/components/schemas/UIConfig"
        capabilities_config:
          $ref: "#/components/schemas/CapabilitiesConfig"
    VersionConfig:
      type: object
      properties:
        version:
          type: string
        version_context:
          type: string
        latest_version:
          type: string
        upgrade_recommended:
          type: boolean
        upgrade_url:
          type: string
    UIConfig:
      type: object
      properties:
        custom_viewers:
          type: array
          items:
            $ref: "#/components/schemas/CustomViewer"
    CustomViewer:
      type: object
      required:
        - name
        - url
      properties:
        name:
          type: string
        url:
          type: string
        extensions:
          type: array
          items:
            type: string
        content_types:
          type: array
          items:
            type: string
    CapabilitiesConfig:
      type: object
      properties: {}
    GarbageCollectionConfig:
      type: object
      properties:
        grace_period:
          description: Duration in seconds. Objects created in the recent grace_period will not be collected.
          type: integer

    ActionRun:
      type: object
      required:
        - run_id
        - branch
        - start_time
        - commit_id
        - event_type
        - status
      properties:
        run_id:
          type: string
        branch:
          type: string
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
        event_type:
          type: string
        status:
          type: string
          enum: [failed, completed]
        commit_id:
          type: string

    ActionRunList:
      type: object
      required:
        - pagination
        - results
      properties:
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: array
          items:
            $ref: "#/components/schemas/ActionRun"

    HookRun:
      type: object
      required:
        - hook_run_id
        - action
        - hook_id
        - start_time
        - status
      properties:
        hook_run_id:
          type: string
        action:
          type: string
        hook_id:
          type: string
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
        status:
          type: string
          enum: [failed, completed]

    HookRunList:
      type: object
      required:
        - pagination
        - results
      properties:
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: array
          items:
            $ref: "#/components/schemas/HookRun"

    StagingLocation:
      type: object
      description: location for placing an object when staging it
      properties:
        physical_address:
          type: string
        presigned_url:
          type: string
          nullable: true
          description: if presign=true is passed in the request, this field will contain a pre-signed URL to use when uploading
        presigned_url_expiry:
          type: integer
          format: int64
          description: |
            If present and nonzero, physical_address is a pre-signed URL and
            will expire at this Unix Epoch time.  This will be shorter than
            the pre-signed URL lifetime if an authentication token is about
            to expire.

            This field is *optional*.

    StagingMetadata:
      type: object
      description: information about uploaded object
      properties:
        staging:
          $ref: "#/components/schemas/StagingLocation"
        checksum:
          type: string
          description: unique identifier of object content on backing store (typically ETag)
        size_bytes:
          type: integer
          format: int64
        user_metadata:
          type: object
          additionalProperties:
            type: string
        content_type:
          type: string
          description: Object media type
        mtime:
          type: integer
          format: int64
          description: Unix Epoch in seconds.  May be ignored by server.
        force:
          type: boolean
          default: false
      required:
        - staging
        - checksum
        - size_bytes

    GarbageCollectionPrepareResponse:
      type: object
      properties:
        run_id:
          type: string
          description: a unique identifier generated for this GC job
          example: 64eaa103-d726-4a33-bcb8-7c0b4abfe09e
        gc_commits_location:
          type: string
          description: location of the resulting commits csv table (partitioned by run_id)
          example: s3://my-storage-namespace/_lakefs/retention/commits
        gc_addresses_location:
          type: string
          description: location to use for expired addresses parquet table (partitioned by run_id)
          example: s3://my-storage-namespace/_lakefs/retention/addresses
        gc_commits_presigned_url:
          type: string
          description: a presigned url to download the commits csv
      required:
        - run_id
        - gc_commits_location
        - gc_addresses_location

    PrepareGarbageCollectionCommitsStatus:
      type: object
      properties:
        task_id:
          type: string
          description: the id of the task preparing the GC commits
        completed:
          type: boolean
          description: true if the task has completed (either successfully or with an error)
        update_time:
          type: string
          format: date-time
          description: last time the task status was updated
        result:
          $ref: "#/components/schemas/GarbageCollectionPrepareResponse"
        error:
          $ref: "#/components/schemas/Error"
      required:
        - task_id
        - completed
        - update_time

    PrepareGCUncommittedRequest:
      type: object
      properties:
        continuation_token:
          type: string

    PrepareGCUncommittedResponse:
      type: object
      properties:
        run_id:
          type: string
        gc_uncommitted_location:
          type: string
          description: location of uncommitted information data
        continuation_token:
          type: string
      required:
        - run_id
        - gc_uncommitted_location

    GarbageCollectionRule:
      type: object
      properties:
        branch_id:
          type: string
        retention_days:
          type: integer
      required:
        - branch_id
        - retention_days

    GarbageCollectionRules:
      type: object
      properties:
        default_retention_days:
          type: integer
        branches:
          type: array
          items:
            $ref: "#/components/schemas/GarbageCollectionRule"
      required:
        - default_retention_days
        - branches

    BranchProtectionRule:
      type: object
      properties:
        pattern:
          type: string
          description: fnmatch pattern for the branch name, supporting * and ? wildcards
          example: "stable_*"
          minLength: 1
      required:
        - pattern

    ImportLocation:
      type: object
      required:
        - type
        - path
        - destination
      properties:
        type:
          type: string
          enum: [common_prefix, object]
          description: Path type, can either be 'common_prefix' or 'object'
        path:
          type: string
          description: A source location to a 'common_prefix' or to a single object. Must match the lakeFS installation blockstore type.
          example: s3://my-bucket/production/collections/
        destination:
          type: string
          description: |
            Destination for the imported objects on the branch. Must be a relative path to the branch.
            If the type is an 'object', the destination is the exact object name under the branch.
            If the type is a 'common_prefix', the destination is the prefix under the branch.
          example: collections/

    ImportCreation:
      type: object
      required:
        - paths
        - commit
      properties:
        paths:
          type: array
          items:
            $ref: "#/components/schemas/ImportLocation"
        commit:
          $ref: "#/components/schemas/CommitCreation"
        force:
          type: boolean
          default: false
      example:
        commit:
          message: Importing collections from S3
        paths:
          - path: s3://my-bucket/production/collections/
            destination: collections/
            type: common_prefix
          - path: s3://my-bucket/production/collections/file1
            destination: collections/file1
            type: object

    RangeMetadata:
      type: object
      required:
        - id
        - min_key
        - max_key
        - count
        - estimated_size
      properties:
        id:
          type: string
          description: ID of the range.
          example: 480e19972a6fbe98ab8e81ae5efdfd1a29037587e91244e87abd4adefffdb01c
        min_key:
          type: string
          description: First key in the range.
          example: production/collections/some/file_1.parquet
        max_key:
          type: string
          description: Last key in the range.
          example: production/collections/some/file_8229.parquet
        count:
          type: integer
          description: Number of records in the range.
        estimated_size:
          type: integer
          description: Estimated size of the range in bytes

    ImportStatus:
      type: object
      properties:
        completed:
          type: boolean
        update_time:
          type: string
          format: date-time
        ingested_objects:
          description: Number of objects processed so far
          type: integer
          format: int64
        metarange_id:
          type: string
        commit:
          $ref: "#/components/schemas/Commit"
        error:
          $ref: "#/components/schemas/Error"
      required:
        - update_time
        - completed

    ImportCreationResponse:
      type: object
      properties:
        id:
          description: The id of the import process
          type: string
      required:
        - id

    TaskCreation:
      type: object
      properties:
        id:
          description: The id of the new task
          type: string
      required:
        - id

    MetaRangeCreation:
      type: object
      properties:
        ranges:
          type: array
          items:
            $ref: "#/components/schemas/RangeMetadata"
          minItems: 1
      required:
        - ranges

    MetaRangeCreationResponse:
      type: object
      properties:
        id:
          description: The id of the created metarange
          type: string

    UpdateToken:
      type: object
      properties:
        staging_token:
          type: string
      required:
        - staging_token

    StatsEvent:
      type: object
      properties:
        class:
          description: stats event class (e.g. "s3_gateway", "openapi_request", "experimental-feature", "ui-event")
          type: string
        name:
          description: stats event name (e.g. "put_object", "create_repository", "<experimental-feature-name>")
          type: string
        count:
          description: number of events of the class and name
          type: integer
      required:
        - class
        - name
        - count

    StatsEventsList:
      type: object
      required:
        - events
      properties:
        events:
          type: array
          items:
            $ref: "#/components/schemas/StatsEvent"

    PresignMultipartUpload:
      type: object
      properties:
        upload_id:
          type: string
        physical_address:
          type: string
        presigned_urls:
          type: array
          items:
            type: string
      required:
        - upload_id
        - physical_address

    UploadPart:
      type: object
      properties:
        part_number:
          type: integer
        etag:
          type: string
      required:
        - part_number
        - etag

    UploadPartFrom:
      type: object
      properties:
        physical_address:
          description: |
            The physical address (of the entire intended object) returned from
            createPresignMultipartUpload.
          type: string
      required:
        - physical_address

    CopyPartSource:
      type: object
      properties:
        repository:
          type: string
        ref:
          type: string
        path:
          type: string
        range:
          description: "Range of bytes to copy"
          type: string
          pattern: '^bytes=((\d*-\d*,? ?)+)$'
      required:
        - repository
        - ref
        - path

    UploadPartCopyFrom:
      allOf: # Extend UploadPartFrom
        - $ref: "#/components/schemas/UploadPartFrom"
        - type: object
          properties:
            copy_source:
              description: "Source of copy"
              $ref: "#/components/schemas/CopyPartSource"
          required:
            - copy_source

    UploadTo:
      type: object
      properties:
        presigned_url:
          type: string
      required:
        - presigned_url

    CompletePresignMultipartUpload:
      type: object
      properties:
        physical_address:
          type: string
        parts:
          type: array
          description: "List of uploaded parts, should be ordered by ascending part number"
          items:
            $ref: "#/components/schemas/UploadPart"
        user_metadata:
          type: object
          additionalProperties:
            type: string
        content_type:
          type: string
          description: Object media type
      required:
        - physical_address
        - parts

    AbortPresignMultipartUpload:
      type: object
      properties:
        physical_address:
          type: string
      required:
        - physical_address

    UsageReport:
      type: object
      properties:
        year:
          type: integer
        month:
          type: integer
        count:
          type: integer
          format: int64
      required:
        - year
        - month
        - count

    InstallationUsageReport:
      type: object
      properties:
        installation_id:
          type: string
        reports:
          type: array
          items:
            $ref: "#/components/schemas/UsageReport"
      required:
        - installation_id
        - reports

    ExternalPrincipalList:
      type: object
      required:
        - pagination
        - results
      properties:
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: array
          items:
            $ref: "#/components/schemas/ExternalPrincipal"
    ExternalPrincipalSettings:
      type: object
      additionalProperties:
        type: string
      description: Additional settings to be consumed by the remote authenticator
    ExternalPrincipalCreation:
      type: object
      properties:
        settings:
          type: object
          items:
            $ref: "#/components/schemas/ExternalPrincipalSettings"
    ExternalPrincipal:
      type: object
      required:
        - user_id
        - id
      properties:
        id:
          type: string
          description: A unique identifier for the external principal i.e aws:sts::123:assumed-role/role-name
        user_id:
          type: string
          description: |
            lakeFS user ID to associate with an external principal.
        settings:
          type: object
          items:
            $ref: "#/components/schemas/ExternalPrincipalSettings"

    PullRequestBasic:
      type: object
      properties:
        status:
          type: string
          enum: [open, closed, merged]
        title:
          type: string
        description:
          type: string

    PullRequest:
      allOf:
        - $ref: "#/components/schemas/PullRequestBasic"
        - required:
            - status
            - title
            - description
        - type: object
          required:
            - id
            - creation_date
            - author
            - source_branch
            - destination_branch
          properties:
            id:
              type: string
            creation_date:
              type: string
              format: date-time
            author:
              type: string
            source_branch:
              type: string
            destination_branch:
              type: string
            merged_commit_id:
              type: string
              description: the commit id of merged PRs
            closed_date:
              type: string
              format: date-time

    PullRequestsList:
      type: object
      required:
        - pagination
        - results
      properties:
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: array
          items:
            $ref: "#/components/schemas/PullRequest"

    PullRequestCreation:
      type: object
      required:
        - title
        - source_branch
        - destination_branch
      properties:
        title:
          type: string
        description:
          type: string
        source_branch:
          type: string
        destination_branch:
          type: string

    PullRequestCreationResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: ID of the pull request

paths:
  /setup_comm_prefs:
    post:
      tags:
        - internal
      operationId: setupCommPrefs
      summary: setup communications preferences
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommPrefsInput"
      responses:
        200:
          description: communication preferences saved successfully
        400:
          $ref: "#/components/responses/BadRequest"
        409:
          description: setup was already completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        412:
          description: wrong setup state for this operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /setup_lakefs:
    get:
      tags:
        - internal
      operationId: getSetupState
      summary: check if the lakeFS installation is already set up
      security: []
      responses:
        200:
          description: lakeFS setup state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SetupState"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    post:
      tags:
        - internal
      operationId: setup
      summary: setup lakeFS and create a first user
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Setup"
      responses:
        200:
          description: user created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CredentialsWithSecret"
        400:
          $ref: "#/components/responses/BadRequest"
        409:
          description: setup was already called
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /user:
    get:
      tags:
        - auth
      operationId: getCurrentUser
      summary: get current user
      responses:
        200:
          description: user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CurrentUser"

  /auth/login:
    post:
      tags:
        - auth
      operationId: login
      summary: perform a login
      security: [] # No authentication
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginInformation"
      responses:
        200:
          description: successful login
          headers:
            Set-Cookie:
              schema:
                type: string
                example: "access_token=abcde12356; Path=/; HttpOnly"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationToken"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/external/principal/login:
    post:
      tags:
        - external
        - experimental
        - auth
      operationId: externalPrincipalLogin
      summary: perform a login using an external authenticator
      security: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExternalLoginInformation"
      responses:
        200:
          description: successful external login
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationToken"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /sts/login:
    post:
      tags:
        - experimental
      operationId: stsLogin # change to stsLogin
      summary: perform a login with STS
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StsAuthRequest"
      responses:
        200:
          description: successful STS login
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationToken"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/capabilities:
    get:
      tags:
        - internal
      operationId: getAuthCapabilities
      summary: list authentication capabilities supported
      security: []
      responses:
        200:
          description: auth capabilities
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthCapabilities"

        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/users:
    get:
      tags:
        - auth
      operationId: listUsers
      summary: list users
      parameters:
        - $ref: "#/components/parameters/PaginationPrefix"
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
      responses:
        200:
          description: user list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    post:
      tags:
        - auth
      operationId: createUser
      summary: create user
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserCreation"
      responses:
        201:
          description: user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        400:
          description: validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          $ref: "#/components/responses/Unauthorized"
        409:
          $ref: "#/components/responses/Conflict"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/users/{userId}:
    parameters:
      - in: path
        name: userId
        required: true
        schema:
          type: string
    get:
      tags:
        - auth
      operationId: getUser
      summary: get user
      responses:
        200:
          description: user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    delete:
      tags:
        - auth
      operationId: deleteUser
      summary: delete user
      responses:
        204:
          description: user deleted successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/groups:
    get:
      tags:
        - auth
      operationId: listGroups
      summary: list groups
      parameters:
        - $ref: "#/components/parameters/PaginationPrefix"
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
      responses:
        200:
          description: group list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GroupList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    post:
      tags:
        - auth
      operationId: createGroup
      summary: create group
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GroupCreation"
      responses:
        201:
          description: group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/groups/{groupId}:
    parameters:
      - in: path
        name: groupId
        required: true
        schema:
          type: string
    get:
      tags:
        - auth
      operationId: getGroup
      summary: get group
      responses:
        200:
          description: group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    delete:
      tags:
        - auth
      operationId: deleteGroup
      summary: delete group
      responses:
        204:
          description: group deleted successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/policies:
    get:
      tags:
        - auth
      operationId: listPolicies
      summary: list policies
      parameters:
        - $ref: "#/components/parameters/PaginationPrefix"
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
      responses:
        200:
          description: policy list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PolicyList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    post:
      tags:
        - auth
      operationId: createPolicy
      summary: create policy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Policy"
      responses:
        201:
          description: policy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Policy"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        409:
          $ref: "#/components/responses/Conflict"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/policies/{policyId}:
    parameters:
      - in: path
        name: policyId
        required: true
        schema:
          type: string
    get:
      tags:
        - auth
      operationId: getPolicy
      summary: get policy
      responses:
        200:
          description: policy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Policy"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    put:
      tags:
        - auth
      operationId: updatePolicy
      summary: update policy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Policy"
      responses:
        200:
          description: policy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Policy"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    delete:
      tags:
        - auth
      operationId: deletePolicy
      summary: delete policy
      responses:
        204:
          description: policy deleted successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/groups/{groupId}/members:
    parameters:
      - in: path
        name: groupId
        required: true
        schema:
          type: string
    get:
      tags:
        - auth
      operationId: listGroupMembers
      summary: list group members
      parameters:
        - $ref: "#/components/parameters/PaginationPrefix"
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
      responses:
        200:
          description: group member list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/groups/{groupId}/members/{userId}:
    parameters:
      - in: path
        name: groupId
        required: true
        schema:
          type: string
      - in: path
        name: userId
        required: true
        schema:
          type: string
    put:
      tags:
        - auth
      operationId: addGroupMembership
      summary: add group membership
      responses:
        201:
          description: membership added successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

    delete:
      tags:
        - auth
      operationId: deleteGroupMembership
      summary: delete group membership
      responses:
        204:
          description: membership deleted successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/users/{userId}/credentials:
    parameters:
      - in: path
        name: userId
        required: true
        schema:
          type: string
    get:
      tags:
        - auth
      parameters:
        - $ref: "#/components/parameters/PaginationPrefix"
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
      operationId: listUserCredentials
      summary: list user credentials
      responses:
        200:
          description: credential list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CredentialsList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

    post:
      tags:
        - auth
      operationId: createCredentials
      summary: create credentials
      responses:
        201:
          description: credentials
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CredentialsWithSecret"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/users/{userId}/credentials/{accessKeyId}:
    parameters:
      - in: path
        name: userId
        required: true
        schema:
          type: string
      - in: path
        name: accessKeyId
        required: true
        schema:
          type: string
    delete:
      tags:
        - auth
      operationId: deleteCredentials
      summary: delete credentials
      responses:
        204:
          description: credentials deleted successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

    get:
      tags:
        - auth
      operationId: getCredentials
      summary: get credentials
      responses:
        200:
          description: credentials
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Credentials"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/users/{userId}/groups:
    parameters:
      - in: path
        name: userId
        required: true
        schema:
          type: string
    get:
      tags:
        - auth
      parameters:
        - $ref: "#/components/parameters/PaginationPrefix"
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
      operationId: listUserGroups
      summary: list user groups
      responses:
        200:
          description: group list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GroupList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/users/{userId}/policies:
    parameters:
      - in: path
        name: userId
        required: true
        schema:
          type: string
    get:
      tags:
        - auth
      parameters:
        - $ref: "#/components/parameters/PaginationPrefix"
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
        - in: query
          name: effective
          schema:
            type: boolean
            default: false
          description: will return all distinct policies attached to the user or any of its groups
      operationId: listUserPolicies
      summary: list user policies
      responses:
        200:
          description: policy list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PolicyList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/users/{userId}/policies/{policyId}:
    parameters:
      - in: path
        name: userId
        required: true
        schema:
          type: string
      - in: path
        name: policyId
        required: true
        schema:
          type: string
    put:
      tags:
        - auth
      operationId: attachPolicyToUser
      summary: attach policy to user
      responses:
        201:
          description: policy attached successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    delete:
      tags:
        - auth
      operationId: detachPolicyFromUser
      summary: detach policy from user
      responses:
        204:
          description: policy detached successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/users/{userId}/external/principals:
    parameters:
      - in: path
        name: userId
        required: true
        schema:
          type: string
      - in: query
        name: principalId
        required: true
        schema:
          type: string
    post:
      tags:
        - auth
        - external
        - experimental
      operationId: createUserExternalPrincipal
      summary: attach external principal to user
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExternalPrincipalCreation"
      responses:
        201:
          description: external principal attached successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        409:
          $ref: "#/components/responses/Conflict"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    delete:
      tags:
        - auth
        - external
        - experimental
      operationId: deleteUserExternalPrincipal
      summary: delete external principal from user
      responses:
        204:
          description: external principal detached successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/users/{userId}/external/principals/ls:
    parameters:
      - in: path
        name: userId
        required: true
        schema:
          type: string
    get:
      tags:
        - auth
        - external
        - experimental
      parameters:
        - $ref: "#/components/parameters/PaginationPrefix"
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
      operationId: listUserExternalPrincipals
      summary: list user external policies attached to a user
      responses:
        200:
          description: external principals list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExternalPrincipalList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/external/principals:
    parameters:
      - in: query
        name: principalId
        required: true
        schema:
          type: string
    get:
      tags:
        - auth
        - external
        - experimental
      operationId: getExternalPrincipal
      summary: describe external principal by id
      responses:
        200:
          description: external principal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExternalPrincipal"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/groups/{groupId}/policies:
    parameters:
      - in: path
        name: groupId
        required: true
        schema:
          type: string
    get:
      tags:
        - auth
      parameters:
        - $ref: "#/components/parameters/PaginationPrefix"
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
      operationId: listGroupPolicies
      summary: list group policies
      responses:
        200:
          description: policy list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PolicyList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/groups/{groupId}/policies/{policyId}:
    parameters:
      - in: path
        name: groupId
        required: true
        schema:
          type: string
      - in: path
        name: policyId
        required: true
        schema:
          type: string
    put:
      tags:
        - auth
      operationId: attachPolicyToGroup
      summary: attach policy to group
      responses:
        201:
          description: policy attached successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

    delete:
      tags:
        - auth
      operationId: detachPolicyFromGroup
      summary: detach policy from group
      responses:
        204:
          description: policy detached successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /auth/groups/{groupId}/acl:
    parameters:
      - in: path
        name: groupId
        required: true
        schema:
          type: string

    post:
      tags:
        - auth
      operationId: setGroupACL
      summary: set ACL of group
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ACL"
      responses:
        201:
          description: ACL successfully changed
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

    get:
      tags:
        - auth
      operationId: getGroupACL
      summary: get ACL of group
      responses:
        200:
          description: ACL of group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ACL"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFoundOrNoACL"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories:
    get:
      tags:
        - repositories
      parameters:
        - $ref: "#/components/parameters/PaginationPrefix"
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
        - $ref: "#/components/parameters/SearchString"
      operationId: listRepositories
      summary: list repositories
      responses:
        200:
          description: repository list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RepositoryList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    post:
      tags:
        - repositories
      operationId: createRepository
      summary: create repository
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RepositoryCreation"
      parameters:
        - in: query
          name: bare
          schema:
            type: boolean
            default: false
          description: If true, create a bare repository with no initial commit and branch
      responses:
        201:
          description: repository
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Repository"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        409:
          $ref: "#/components/responses/Conflict"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    get:
      tags:
        - repositories
      operationId: getRepository
      summary: get repository
      responses:
        200:
          description: repository
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Repository"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    delete:
      tags:
        - repositories
      operationId: deleteRepository
      summary: delete repository
      parameters:
        - in: query
          name: force
          schema:
            type: boolean
            default: false
          description: Bypass read-only protection and delete the repository
      responses:
        204:
          description: repository deleted successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/metadata:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    get:
      tags:
        - repositories
      operationId: getRepositoryMetadata
      summary: get repository metadata
      responses:
        200:
          description: repository metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RepositoryMetadata"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    post:
      tags:
        - internal
      operationId: setRepositoryMetadata
      summary: set repository metadata
      description: |
        Set repository metadata. This will only add or update the provided keys, and will not remove any existing keys.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RepositoryMetadataSet"
      responses:
        204:
          description: repository metadata set successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    delete:
      tags:
        - internal
      operationId: deleteRepositoryMetadata
      summary: delete repository metadata
      description: |
        Delete specified keys from the repository's metadata.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RepositoryMetadataKeys"
      responses:
        204:
          description: repository metadata keys deleted successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/settings/gc_rules:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    get:
      tags:
        - repositories
      operationId: getGCRules
      summary: get repository GC rules
      responses:
        200:
          description: repository GC rules
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GarbageCollectionRules"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    put:
      tags:
        - repositories
      operationId: setGCRules
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GarbageCollectionRules"
      responses:
        204:
          description: set garbage collection rules successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    delete:
      tags:
        - repositories
      operationId: deleteGCRules
      responses:
        204:
          description: deleted garbage collection rules successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/settings/branch_protection:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    get:
      tags:
        - repositories
      operationId: getBranchProtectionRules
      summary: get branch protection rules
      responses:
        200:
          description: branch protection rules
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/BranchProtectionRule"
          headers:
            ETag:
              schema:
                type: string
                description: ETag of the branch protection rules
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

    put:
      parameters:
        - in: header
          name: If-Match
          schema:
            type: string
          description: if provided, the branch protection rules will be updated only if the current ETag match the provided value
          allowEmptyValue: true
      tags:
        - repositories
      operationId: setBranchProtectionRules
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/BranchProtectionRule"
      responses:
        204:
          description: branch protection rule created successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        412:
          $ref: "#/components/responses/PreconditionFailed"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/refs/dump:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    put:
      tags:
        - internal
      operationId: dumpRefs
      summary: |
        Dump repository refs (tags, commits, branches) to object store
        Deprecated: a new API will introduce long running operations
      responses:
        201:
          description: refs dump
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RefsDump"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/refs/restore:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    put:
      tags:
        - internal
      operationId: restoreRefs
      summary: |
        Restore repository refs (tags, commits, branches) from object store.
        Deprecated: a new API will introduce long running operations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RefsRestore"
      responses:
        200:
          description: refs successfully loaded
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/dump:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    post:
      tags:
        - repositories
      operationId: dumpSubmit
      summary: Backup the repository metadata (tags, commits, branches) and save the backup to the object store.
      responses:
        202:
          description: dump task information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaskInfo"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        default:
          $ref: "#/components/responses/ServerError"
    get:
      tags:
        - repositories
      operationId: dumpStatus
      summary: Status of a repository dump task
      parameters:
        - in: query
          name: task_id
          required: true
          schema:
            type: string
      responses:
        200:
          description: dump task status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RepositoryDumpStatus"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/restore:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    post:
      tags:
        - repositories
      operationId: restoreSubmit
      summary: Restore repository from a dump in the object store
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RefsRestore"
      responses:
        202:
          description: restore task created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaskInfo"
        400:
          $ref: "#/components/responses/ValidationError"
        403:
          $ref: "#/components/responses/Forbidden"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        default:
          $ref: "#/components/responses/ServerError"
    get:
      tags:
        - repositories
      operationId: restoreStatus
      summary: Status of a restore request
      parameters:
        - in: query
          name: task_id
          required: true
          schema:
            type: string
      responses:
        200:
          description: restore task status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RepositoryRestoreStatus"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/tags:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    get:
      tags:
        - tags
      operationId: listTags
      summary: list tags
      parameters:
        - $ref: "#/components/parameters/PaginationPrefix"
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
      responses:
        200:
          description: tag list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RefList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

    post:
      tags:
        - tags
      operationId: createTag
      summary: create tag
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TagCreation"
      responses:
        201:
          description: tag
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Ref"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        409:
          $ref: "#/components/responses/Conflict"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/tags/{tag}:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: tag
        required: true
        schema:
          type: string
    get:
      tags:
        - tags
      operationId: getTag
      summary: get tag
      responses:
        200:
          description: tag
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Ref"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    delete:
      tags:
        - tags
      operationId: deleteTag
      summary: delete tag
      parameters:
        - in: query
          name: force
          required: false
          schema:
            type: boolean
      responses:
        204:
          description: tag deleted successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    get:
      tags:
        - branches
      operationId: listBranches
      summary: list branches
      parameters:
        - $ref: "#/components/parameters/PaginationPrefix"
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
        - in: query
          name: show_hidden
          schema:
            type: boolean
            default: false
            description: When set - list all branches including hidden branches. *EXPERIMENTAL*
      responses:
        200:
          description: branch list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RefList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    post:
      tags:
        - branches
      operationId: createBranch
      summary: create branch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BranchCreation"
      responses:
        201:
          description: reference
          content:
            text/html:
              schema:
                type: string
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        409:
          $ref: "#/components/responses/Conflict"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/refs/{ref}/commits:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: ref
        required: true
        schema:
          type: string
    get:
      tags:
        - refs
      operationId: logCommits
      summary: get commit log from ref. If both objects and prefixes are empty, return all commits.
      parameters:
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
        - in: query
          name: objects
          description: list of paths, each element is a path of a specific object
          schema:
            type: array
            items:
              type: string
        - in: query
          name: prefixes
          description: list of paths, each element is a path of a prefix
          schema:
            type: array
            items:
              type: string
        - in: query
          name: limit
          description: limit the number of items in return to 'amount'. Without further indication on actual number of items.
          schema:
            type: boolean
        - in: query
          name: first_parent
          description: if set to true, follow only the first parent upon reaching a merge commit
          schema:
            type: boolean
        - in: query
          name: since
          description: Show commits more recent than a specific date-time. In case used with stop_at parameter, will stop at the first commit that meets any of the conditions.
          allowEmptyValue: true
          schema:
            type: string
            format: date-time
        - in: query
          name: stop_at
          allowEmptyValue: true
          description: A reference to stop at. In case used with since parameter, will stop at the first commit that meets any of the conditions.
          schema:
            type: string
      responses:
        200:
          description: commit log
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommitList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}/commits:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
    post:
      parameters:
        - in: query
          name: source_metarange
          required: false
          description: The source metarange to commit. Branch must not have uncommitted changes.
          schema:
            type: string
      tags:
        - commits
      operationId: commit
      summary: create commit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommitCreation"
      responses:
        201:
          description: commit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Commit"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        409:
          $ref: "#/components/responses/Conflict"
        412:
          $ref: "#/components/responses/PreconditionFailed"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/commits:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    post:
      tags:
        - internal
      operationId: CreateCommitRecord
      summary: create commit record
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommitRecordCreation"
      responses:
        204:
          description: commit record created
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
    get:
      tags:
        - branches
      operationId: getBranch
      summary: get branch
      responses:
        200:
          description: branch
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Ref"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    delete:
      tags:
        - branches
      operationId: deleteBranch
      summary: delete branch
      parameters:
        - in: query
          name: force
          required: false
          schema:
            type: boolean
            default: false
      responses:
        204:
          description: branch deleted successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    put:
      tags:
        - branches
      operationId: resetBranch
      summary: reset branch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResetCreation"
      responses:
        204:
          description: reset successful
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}/hard_reset:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
    put:
      tags:
        - experimental
      operationId: hardResetBranch
      summary: hard reset branch
      description: Relocate branch to refer to ref.  Branch must not contain
        uncommitted data.
      parameters:
        - in: query
          name: ref
          required: true
          schema:
            type: string
          description: After reset, branch will point at this reference.
        - in: query
          name: force
          required: false
          schema:
            type: boolean
            default: false
      responses:
        204:
          description: reset successful
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}/revert:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
    post:
      tags:
        - branches
      operationId: revertBranch
      summary: revert
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RevertCreation"
      responses:
        204:
          description: revert successful
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        409:
          description: Conflict Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}/cherry-pick:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
    post:
      tags:
        - branches
      operationId: cherryPick
      summary: Replay the changes from the given commit on the branch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CherryPickCreation"
      responses:
        201:
          description: the cherry-pick commit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Commit"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        409:
          description: Conflict Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/refs/{sourceRef}/merge/{destinationBranch}:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: sourceRef
        required: true
        schema:
          type: string
        description: source ref
      - in: path
        name: destinationBranch
        required: true
        schema:
          type: string
        description: destination branch name
    post:
      tags:
        - refs
      operationId: mergeIntoBranch
      summary: merge references
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Merge"
      responses:
        200:
          description: merge completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MergeResult"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        409:
          description: |
            Conflict
            Deprecated: content schema will return Error format and not an empty MergeResult
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MergeResult"
        412:
          description: precondition failed (e.g. a pre-merge hook returned a failure)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    get:
      tags:
        - refs
      operationId: findMergeBase
      summary: find the merge base for 2 references
      responses:
        200:
          description: Found the merge base
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FindMergeBaseResult"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}/diff:
    parameters:
      - $ref: "#/components/parameters/PaginationAfter"
      - $ref: "#/components/parameters/PaginationAmount"
      - $ref: "#/components/parameters/PaginationPrefix"
      - $ref: "#/components/parameters/PaginationDelimiter"
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string

    get:
      tags:
        - branches
      operationId: diffBranch
      summary: diff branch
      responses:
        200:
          description: diff of branch uncommitted changes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DiffList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/refs/{leftRef}/diff/{rightRef}:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: leftRef
        required: true
        schema:
          type: string
        description: a reference (could be either a branch or a commit ID)
      - in: path
        name: rightRef
        required: true
        schema:
          type: string
        description: a reference (could be either a branch or a commit ID) to compare against
      - $ref: "#/components/parameters/PaginationAfter"
      - $ref: "#/components/parameters/PaginationAmount"
      - $ref: "#/components/parameters/PaginationPrefix"
      - $ref: "#/components/parameters/PaginationDelimiter"
      - in: query
        name: type
        schema:
          type: string
          enum: [two_dot, three_dot]
          default: three_dot
      - in: query
        name: include_right_stats
        description: If set to true, the diff will include right-side object stats. *EXPERIMENTAL*
        required: false
        schema:
          type: boolean
          default: false

    get:
      tags:
        - refs
      operationId: diffRefs
      summary: diff references
      responses:
        200:
          description: diff between refs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DiffList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/commits/{commitId}:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: commitId
        required: true
        schema:
          type: string
    get:
      tags:
        - commits
      operationId: getCommit
      summary: get commit
      responses:
        200:
          description: commit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Commit"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/refs/{ref}/objects:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: ref
        required: true
        schema:
          type: string
        description: a reference (could be either a branch or a commit ID)
      - in: query
        name: path
        description: relative to the ref
        required: true
        schema:
          type: string
    get:
      tags:
        - objects
      operationId: getObject
      summary: get object content
      parameters:
        - in: header
          name: Range
          description: Byte range to retrieve
          example: "bytes=0-1023"
          required: false
          schema:
            type: string
            pattern: '^bytes=((\d*-\d*,? ?)+)$'
        - in: header
          name: If-None-Match
          description: Returns response only if the object does not have a matching ETag
          example: "33a64df551425fcc55e4d42a148795d9f25f89d4"
          required: false
          schema:
            type: string
        - in: query
          name: presign
          required: false
          schema:
            type: boolean
      responses:
        200:
          description: object content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          headers:
            Content-Length:
              schema:
                type: integer
                format: int64
            Last-Modified:
              schema:
                type: string
            ETag:
              schema:
                type: string
        206:
          description: partial object content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          headers:
            Content-Length:
              schema:
                type: integer
                format: int64
            Content-Range:
              schema:
                type: string
                pattern: '^bytes=((\d*-\d*,? ?)+)$'
            Last-Modified:
              schema:
                type: string
            ETag:
              schema:
                type: string
        302:
          description: Redirect to a pre-signed URL for the object
          headers:
            Location:
              schema:
                type: string
        304:
          description: Content not modified
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        410:
          description: object expired
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        416:
          description: Requested Range Not Satisfiable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    head:
      tags:
        - objects
      operationId: headObject
      summary: check if object exists
      parameters:
        - in: header
          name: Range
          description: Byte range to retrieve
          example: "bytes=0-1023"
          required: false
          schema:
            type: string
            pattern: '^bytes=((\d*-\d*,? ?)+)$'
      responses:
        200:
          description: object exists
          headers:
            Content-Length:
              schema:
                type: integer
                format: int64
            Last-Modified:
              schema:
                type: string
            ETag:
              schema:
                type: string
        206:
          description: partial object content info
          headers:
            Content-Length:
              schema:
                type: integer
                format: int64
            Content-Range:
              schema:
                type: string
                pattern: '^bytes=((\d*-\d*,? ?)+)$'
            Last-Modified:
              schema:
                type: string
            ETag:
              schema:
                type: string
        400:
          description: Bad Request
        401:
          description: Unauthorized
        404:
          description: object not found
        410:
          description: object expired
        416:
          description: Requested Range Not Satisfiable
        429:
          description: too many requests
        default:
          description: internal server error

  /repositories/{repository}/branches/{branch}/staging/pmpu:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
      - in: query
        name: path
        description: relative to the branch
        required: true
        schema:
          type: string
      - in: query
        name: parts
        description: number of presigned URL parts required to upload
        schema:
          type: integer
    post:
      tags:
        - experimental
      operationId: createPresignMultipartUpload
      summary: Initiate a multipart upload
      description: |
        Initiates a multipart upload and returns an upload ID with presigned URLs for each part (optional).
        Part numbers starts with 1. Each part except the last one has minimum size depends on the underlying blockstore implementation.
        For example working with S3 blockstore, minimum size is 5MB (excluding the last part).
      responses:
        201:
          description: Presign multipart upload initiated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PresignMultipartUpload"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}/staging/pmpu/{uploadId}:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
      - in: path
        name: uploadId
        required: true
        schema:
          type: string
      - in: query
        name: path
        description: relative to the branch
        required: true
        schema:
          type: string
    put:
      tags:
        - experimental
      operationId: completePresignMultipartUpload
      summary: Complete a presign multipart upload request
      description: Completes a presign multipart upload by assembling the uploaded parts.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CompletePresignMultipartUpload"
      responses:
        200:
          description: Presign multipart upload completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ObjectStats"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        409:
          description: conflict with a commit, try here
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StagingLocation"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

    delete:
      tags:
        - experimental
      operationId: abortPresignMultipartUpload
      summary: Abort a presign multipart upload
      description: Aborts a presign multipart upload.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AbortPresignMultipartUpload"
      responses:
        204:
          description: Presign multipart upload aborted
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}/staging/pmpu/{uploadId}/parts/{partNumber}:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
      - in: path
        name: uploadId
        required: true
        schema:
          type: string
      - in: query
        name: path
        required: true
        schema:
          type: string
      - in: path
        name: partNumber
        required: true
        schema:
          type: integer
          maximum: 10000
          minimum: 1
    put:
      tags:
        - experimental
      operationId: uploadPart
      description: Return a presigned URL to upload into a presigned multipart upload.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UploadPartFrom"
      responses:
        200:
          description: presigned URL to use for upload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadTo"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}/staging/pmpu/{uploadId}/parts/{partNumber}/copy:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
      - in: path
        name: uploadId
        required: true
        schema:
          type: string
      - in: query
        name: path
        required: true
        schema:
          type: string
      - in: path
        name: partNumber
        required: true
        schema:
          type: integer
          maximum: 10000
          minimum: 1
    put:
      tags:
        - experimental
      operationId: uploadPartCopy
      description: Upload a part by copying part of another object.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UploadPartCopyFrom"
      responses:
        204:
          description: part copied
          headers:
            ETag:
              schema:
                type: string
                description: ETag of the uploaded part, pass in completion
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}/staging/backing:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
      - in: query
        name: path
        description: relative to the branch
        required: true
        schema:
          type: string
    get:
      tags:
        - staging
      operationId: getPhysicalAddress
      summary: generate an address to which the client can upload an object
      parameters:
        - in: query
          name: presign
          required: false
          schema:
            type: boolean
      responses:
        200:
          description: physical address for staging area
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StagingLocation"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

    put:
      tags:
        - staging
      operationId: linkPhysicalAddress
      summary: associate staging on this physical address with a path
      description: |
        Link the physical address with the path in lakeFS, creating an uncommitted change.
        The given address can be one generated by getPhysicalAddress, or an address outside the repository's storage namespace.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StagingMetadata"

      parameters:
        - $ref: "#/components/parameters/IfNoneMatch"
        - $ref: "#/components/parameters/IfMatch"

      responses:
        200:
          # This actually violates HTTP, which requires returning 201 if a new object was
          # created or 200 if an existing object was modified,
          # https://tools.ietf.org/html/rfc7231#section-4.3.4
          description: object metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ObjectStats"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/ServerError"
        409:
          description: conflict with a commit, try here
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StagingLocation"
        412:
          $ref: "#/components/responses/PreconditionFailed"
        429:
          description: too many requests
        501:
          $ref: "#/components/responses/NotImplemented"
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}/import:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
    get:
      tags:
        - import
      operationId: importStatus
      summary: get import status
      parameters:
        - in: query
          name: id
          description: Unique identifier of the import process
          schema:
            type: string
          required: true
      responses:
        200:
          description: import status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImportStatus"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    post:
      tags:
        - import
      operationId: importStart
      summary: import data from object store
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImportCreation"
      responses:
        202:
          description: Import started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImportCreationResponse"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    delete:
      tags:
        - import
      operationId: importCancel
      summary: cancel ongoing import
      parameters:
        - in: query
          name: id
          description: Unique identifier of the import process
          schema:
            type: string
          required: true
      responses:
        204:
          description: import canceled successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        409:
          $ref: "#/components/responses/Conflict"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}/objects/stage_allowed:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
      - in: query
        name: path
        description: relative to the branch
        required: true
        schema:
          type: string
    get:
      tags:
        - internal
      operationId: uploadObjectPreflight
      responses:
        204:
          description: User has permissions to upload this object. This does not guarantee that the upload will be successful or even possible. It indicates only the permission at the time of calling this endpoint
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}/objects:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
      - in: query
        name: path
        description: relative to the branch
        required: true
        schema:
          type: string
    put:
      deprecated: true
      tags:
        - internal
      operationId: stageObject
      summary: stage an object's metadata for the given branch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ObjectStageCreation"
      responses:
        201:
          description: object metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ObjectStats"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

    post:
      tags:
        - objects
      operationId: uploadObject
      x-validation-exclude-body: true
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                content:
                  description: Only a single file per upload which must be named "content".
                  type: string
                  format: binary
          application/octet-stream:
            schema:
              type: string
              format: binary

      parameters:
        - $ref: "#/components/parameters/IfNoneMatch"
        - $ref: "#/components/parameters/IfMatch"
        - in: query
          name: storageClass
          description: Deprecated, this capability will not be supported in future releases.
          required: false
          deprecated: true
          schema:
            type: string
        - in: query
          name: force
          required: false
          schema:
            type: boolean
            default: false
      responses:
        201:
          description: object metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ObjectStats"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        412:
          $ref: "#/components/responses/PreconditionFailed"
        429:
          description: too many requests
        501:
          $ref: "#/components/responses/NotImplemented"
        default:
          $ref: "#/components/responses/ServerError"
    delete:
      tags:
        - objects
      operationId: deleteObject
      summary: delete object. Missing objects will not return a NotFound error.
      parameters:
        - in: query
          name: force
          required: false
          schema:
            type: boolean
            default: false
        - $ref: "#/components/parameters/NoTombstone"
      responses:
        204:
          description: object deleted successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}/objects/delete:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
      - in: query
        name: force
        required: false
        schema:
          type: boolean
          default: false
      - $ref: "#/components/parameters/NoTombstone"
    post:
      tags:
        - objects
      operationId: deleteObjects
      summary: delete objects. Missing objects will not return a NotFound error.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PathList"
      responses:
        200:
          description: Delete objects response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ObjectErrorList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}/objects/copy:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
        description: destination branch for the copy
      - in: query
        name: dest_path
        description: destination path relative to the branch
        required: true
        schema:
          type: string

    post:
      tags:
        - objects
      operationId: copyObject
      summary: create a copy of an object
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ObjectCopyCreation"
      responses:
        201:
          description: Copy object response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ObjectStats"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/refs/{ref}/objects/stat:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: ref
        required: true
        schema:
          type: string
        description: a reference (could be either a branch or a commit ID)
      - in: query
        name: path
        description: relative to the branch
        required: true
        schema:
          type: string
      - in: query
        name: user_metadata
        required: false
        schema:
          type: boolean
          default: true
      - in: query
        name: presign
        required: false
        schema:
          type: boolean
    get:
      tags:
        - objects
      operationId: statObject
      summary: get object metadata
      responses:
        200:
          description: object metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ObjectStats"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        400:
          $ref: "#/components/responses/BadRequest"
        410:
          description: object gone (but partial metadata may be available)
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branches/{branch}/objects/stat/user_metadata:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
        description: branch to update
      - in: query
        name: path
        description: path to object relative to the branch
        required: true
        schema:
          type: string
    put:
      tags:
        - objects
        - experimental
      operationId: updateObjectUserMetadata
      summary: rewrite (all) object metadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateObjectUserMetadata"
      responses:
        201:
          description: User metadata updated
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        400:
          $ref: "#/components/responses/BadRequest"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/refs/{ref}/objects/underlyingProperties:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: ref
        required: true
        schema:
          type: string
        description: a reference (could be either a branch or a commit ID)
      - in: query
        name: path
        description: relative to the branch
        required: true
        schema:
          type: string
    get:
      tags:
        - objects
      operationId: getUnderlyingProperties
      summary: get object properties on underlying storage
      responses:
        200:
          description: object metadata on underlying storage
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnderlyingObjectProperties"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/refs/{ref}/objects/ls:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: ref
        required: true
        schema:
          type: string
        description: a reference (could be either a branch or a commit ID)
      - in: query
        name: user_metadata
        required: false
        schema:
          type: boolean
          default: true
      - in: query
        name: presign
        required: false
        schema:
          type: boolean
      - $ref: "#/components/parameters/PaginationAfter"
      - $ref: "#/components/parameters/PaginationAmount"
      - $ref: "#/components/parameters/PaginationDelimiter"
      - $ref: "#/components/parameters/PaginationPrefix"

    get:
      tags:
        - objects
      operationId: listObjects
      summary: list objects under a given prefix
      responses:
        200:
          description: object listing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ObjectStatsList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/refs/{branch}/symlink:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: branch
        required: true
        schema:
          type: string
      - in: query
        name: location
        schema:
          type: string
        description: path to the table data
    post:
      tags:
        - internal
      operationId: createSymlinkFile
      summary: creates symlink files corresponding to the given directory

      responses:
        201:
          description: location created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StorageURI"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/actions/runs:
    get:
      tags:
        - actions
      operationId: listRepositoryRuns
      summary: list runs
      parameters:
        - in: path
          name: repository
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
        - in: query
          name: branch
          allowEmptyValue: true
          schema:
            type: string
        - in: query
          name: commit
          allowEmptyValue: true
          schema:
            type: string
      responses:
        200:
          description: list action runs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionRunList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/actions/runs/{run_id}:
    get:
      tags:
        - actions
      operationId: getRun
      summary: get a run
      parameters:
        - in: path
          name: repository
          required: true
          schema:
            type: string
        - in: path
          name: run_id
          required: true
          schema:
            type: string
      responses:
        200:
          description: action run result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionRun"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/actions/runs/{run_id}/hooks:
    get:
      tags:
        - actions
      operationId: listRunHooks
      summary: list run hooks
      parameters:
        - in: path
          name: repository
          required: true
          schema:
            type: string
        - in: path
          name: run_id
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
      responses:
        200:
          description: list specific run hooks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HookRunList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/actions/runs/{run_id}/hooks/{hook_run_id}/output:
    get:
      tags:
        - actions
      operationId: getRunHookOutput
      summary: get run hook output
      parameters:
        - in: path
          name: repository
          required: true
          schema:
            type: string
        - in: path
          name: run_id
          required: true
          schema:
            type: string
        - in: path
          name: hook_run_id
          required: true
          schema:
            type: string
      responses:
        200:
          description: run hook output
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/metadata/object/{type}/{object_id}:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: object_id
        required: true
        schema:
          type: string
      - in: path
        name: type
        required: true
        schema:
          type: string
          enum:
            - range
            - meta_range
    get:
      tags:
        - internal
      operationId: getMetadataObject
      summary: return a lakeFS metadata object by ID
      parameters:
        - in: query
          name: presign
          required: false
          schema:
            type: boolean
      responses:
        200:
          description: object content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          headers:
            Content-Length:
              schema:
                type: integer
                format: int64
        302:
          description: Redirect to a pre-signed URL for the object
          headers:
            Location:
              schema:
                type: string
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/metadata/meta_range/{meta_range}:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: meta_range
        required: true
        schema:
          type: string
    get:
      tags:
        - metadata
      operationId: getMetaRange
      summary: return URI to a meta-range file
      responses:
        200:
          description: meta-range URI
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StorageURI"
          headers:
            Location:
              schema:
                type: string
              description: redirect to S3
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/metadata/range/{range}:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: range
        required: true
        schema:
          type: string
    get:
      tags:
        - metadata
      operationId: getRange
      summary: return URI to a range file
      responses:
        200:
          description: range URI
          headers:
            Location:
              schema:
                type: string
              description: redirect to S3
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StorageURI"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/gc/rules/set_allowed:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    get:
      tags:
        - internal
      operationId: setGarbageCollectionRulesPreflight
      responses:
        204:
          description: User has permissions to set garbage collection rules on this repository
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/gc/rules:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    get:
      deprecated: true
      tags:
        - internal
      operationId: internalGetGarbageCollectionRules
      description: "Deprecated; use getGCRules."
      responses:
        200:
          description: gc rule list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GarbageCollectionRules"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

    post:
      deprecated: true
      tags:
        - internal
      operationId: internalSetGarbageCollectionRules
      description: "Deprecated; use setGCRules."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GarbageCollectionRules"
      responses:
        204:
          description: set garbage collection rules successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    delete:
      deprecated: true
      tags:
        - internal
      operationId: internalDeleteGarbageCollectionRules
      description: "Deprecated; use deleteGCRules."
      responses:
        204:
          description: deleted garbage collection rules successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/gc/prepare_commits:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    post:
      tags:
        - internal
      operationId: prepareGarbageCollectionCommits
      summary: save lists of active commits for garbage collection
      responses:
        201:
          description: paths to commit dataset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GarbageCollectionPrepareResponse"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/gc/prepare_commits/async:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    post:
      tags:
        - internal
      operationId: prepareGarbageCollectionCommitsAsync
      summary: prepare gc commits
      responses:
        202:
          description: GC prepare task started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaskCreation"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/gc/prepare_commits/status:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    get:
      tags:
        - internal
      operationId: prepareGarbageCollectionCommitsStatus
      summary: get status of prepare gc commits operation
      parameters:
        - in: query
          name: id
          description: Unique identifier of the prepare GC commits task
          schema:
            type: string
          required: true
      responses:
        200:
          description: prepare GC commits task status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrepareGarbageCollectionCommitsStatus"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/gc/prepare_uncommited:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PrepareGCUncommittedRequest"
      tags:
        - internal
      operationId: prepareGarbageCollectionUncommitted
      summary: save repository uncommitted metadata for garbage collection
      responses:
        201:
          description: paths to commit dataset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrepareGCUncommittedResponse"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branch_protection/set_allowed:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    get:
      tags:
        - internal
      operationId: createBranchProtectionRulePreflight
      responses:
        204:
          description: User has permissions to create a branch protection rule in this repository
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        409:
          $ref: "#/components/responses/Conflict"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/branch_protection:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    get:
      deprecated: true
      tags:
        - internal
      operationId: internalGetBranchProtectionRules
      summary: get branch protection rules
      responses:
        200:
          description: branch protection rules
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/BranchProtectionRule"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

    post:
      deprecated: true
      tags:
        - internal
      operationId: internalCreateBranchProtectionRule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BranchProtectionRule"
      responses:
        204:
          description: branch protection rule created successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    delete:
      deprecated: true
      tags:
        - internal
      operationId: internalDeleteBranchProtectionRule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pattern:
                  type: string
              required:
                - pattern
      responses:
        204:
          description: branch protection rule deleted successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/pulls:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
    get:
      tags:
        - pulls
        - experimental
      operationId: listPullRequests
      summary: list pull requests
      parameters:
        - $ref: "#/components/parameters/PaginationPrefix"
        - $ref: "#/components/parameters/PaginationAfter"
        - $ref: "#/components/parameters/PaginationAmount"
        - in: query
          name: status
          schema:
            type: string
            enum: [open, closed, all]
            default: all
            description: filter pull requests by status
      responses:
        200:
          description: list of pull requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PullRequestsList"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    post:
      tags:
        - pulls
        - experimental
      operationId: createPullRequest
      summary: create pull request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PullRequestCreation"
      responses:
        201:
          description: pull request created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PullRequestCreationResponse"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        409:
          $ref: "#/components/responses/Conflict"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/pulls/{pull_request}:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: pull_request
        required: true
        description: pull request id
        schema:
          type: string
    get:
      tags:
        - pulls
        - experimental
      operationId: getPullRequest
      summary: get pull request
      responses:
        200:
          description: pull request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PullRequest"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"
    patch:
      tags:
        - pulls
        - experimental
      operationId: updatePullRequest
      summary: update pull request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PullRequestBasic"
      responses:
        200:
          description: pull request updated successfully
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /repositories/{repository}/pulls/{pull_request}/merge:
    parameters:
      - in: path
        name: repository
        required: true
        schema:
          type: string
      - in: path
        name: pull_request
        required: true
        description: pull request id
        schema:
          type: string
    put:
      tags:
        - pulls
        - experimental
      operationId: mergePullRequest
      summary: merge pull request
      responses:
        200:
          description: merge completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MergeResult"
        400:
          $ref: "#/components/responses/ValidationError"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        404:
          $ref: "#/components/responses/NotFound"
        409:
          description: |
            Conflict
            Deprecated: content schema will return Error format and not an empty MergeResult
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MergeResult"
        412:
          description: precondition failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /healthcheck:
    get:
      operationId: healthCheck
      security: []
      tags:
        - healthCheck
      description: check that the API server is up and running
      responses:
        204:
          description: NoContent

  /config:
    get:
      tags:
        - config
      operationId: getConfig
      description: retrieve lakeFS configuration
      responses:
        200:
          description: lakeFS configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Config"
        401:
          $ref: "#/components/responses/Unauthorized"
  /config/version:
    get:
      tags:
        - internal
      operationId: getLakeFSVersion
      description: get version of lakeFS server
      deprecated: true
      responses:
        200:
          description: lakeFS version
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VersionConfig"
        401:
          $ref: "#/components/responses/Unauthorized"
  /config/storage:
    get:
      tags:
        - internal
      operationId: getStorageConfig
      description: retrieve lakeFS storage configuration
      deprecated: true
      responses:
        200:
          description: lakeFS storage configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StorageConfig"
        401:
          $ref: "#/components/responses/Unauthorized"
  /config/garbage-collection:
    get:
      tags:
        - internal
      operationId: getGarbageCollectionConfig
      description: get information of gc settings
      responses:
        200:
          description: lakeFS garbage collection config
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GarbageCollectionConfig"
        401:
          $ref: "#/components/responses/Unauthorized"

  /statistics:
    post:
      tags:
        - internal
      operationId: postStatsEvents
      summary: post stats events, this endpoint is meant for internal use only
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StatsEventsList"
      responses:
        204:
          description: reported successfully
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          $ref: "#/components/responses/Unauthorized"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /usage-report/summary:
    get:
      tags:
        - internal
      operationId: getUsageReportSummary
      summary: get usage report summary
      responses:
        200:
          description: Usage report
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InstallationUsageReport"
            application/text:
              schema:
                type: string
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: "#/components/responses/NotFound"
        429:
          description: too many requests
        default:
          $ref: "#/components/responses/ServerError"

  /oidc/callback:
    get:
      tags:
        - auth
      operationId: oauthCallback
      security: []
      responses:
        302:
          description: successfully got token
        401:
          description: failed to exchange authorization code for token
        default:
          $ref: "#/components/responses/ServerError"