swagger.yml

swagger: "2.0"

consumes:
- application/json
info:
  description: lakeFS HTTP API
  title: lakeFS API
  version: 0.1.0
produces:
- application/json
schemes:
- http
- https
basePath: /api/v1


securityDefinitions:
  basic_auth:
    type: basic
  jwt_token:
    type: apiKey
    in: header
    name: X-JWT-Authorization


security:
  - basic_auth: []
  - jwt_token: []

responses:
  Unauthorized:
    description: Unauthorized
    schema:
      $ref: "#/definitions/error"

definitions:

  pagination:
    type: object
    required:
      - has_more
    properties:
      has_more:
        type: boolean
      next_offset:
        type: string
      results:
        type: integer
        minimum: 0
      max_per_page:
        type: integer
        minimum: 0

  repository:
    type: object
    properties:
      id:
        type: string
      creation_date:
        type: integer
        format: int64
      default_branch:
        example: "master"
        type: string
      storage_namespace:
        type: string
        description: "Filesystem URI to store the underlying data in (e.g. 's3://my-bucket/some/path/')"

  merge_result:
    type: object
    properties:
      summary:
        type: object
        properties:
          added:
            type: integer
          removed:
            type: integer
          changed:
            type: integer
          conflict:
            type: integer
      reference:
        type: string

  repository_creation:
    type: object
    required:
      - id
      - storage_namespace
    properties:
      id:
        type: string
      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|mem|local|transient)://.*$'
      default_branch:
        example: "master"
        type: string

  object_stats:
    type: object
    properties:
      path:
        type: string
      checksum:
        type: string
      mtime:
        type: integer
        format: int64
      size_bytes:
        type: integer
        format: int64
      path_type:
        type: string
        enum: [common_prefix, object]

  underlying_object_properties:
    type: object
    properties:
      storage_class:
        x-nullable: true
        type: string

  diff:
    type: object
    properties:
      type:
        type: string
        enum: [added, removed, changed, conflict]
      path:
        type: string
      path_type:
        type: string
        enum: [common_prefix, object]

  revert_creation:
    type: object
    required:
      - type
    properties:
      type:
        type: string
        enum: [object, common_prefix, commit, reset]
      commit:
        type: string
      path:
        type: string

  commit:
    type: object
    properties:
      id:
        type: string
      parents:
        type: array
        items:
          type: string
      committer:
        type: string
      message:
        type: string
      creation_date:
        type: integer
        format: int64
      metadata:
        type: object
        additionalProperties:
          type: string

  commit_creation:
    type: object
    required:
      - message
    properties:
      message:
        type: string
      metadata:
        type: object
        additionalProperties:
          type: string

  merge:
    type: object
    properties:
      message:
        type: string
      metadata:
        type: object
        additionalProperties:
          type: string

  branch_creation:
    type: object
    required:
      - name
      - source
    properties:
      name:
        type: string
      source:
        type: string

  error:
    type: object
    properties:
      message:
        description: short message explaining the error
        type: string

  user:
    type: object
    properties:
      id:
        type: string
      creation_date:
        type: integer
        format: int64

  user_creation:
    type: object
    properties:
      id:
        type: string
    required:
      - id

  setup:
    type: object
    properties:
      username:
        description: an identifier for the user (e.g. jane.doe)
        type: string
    required:
      - username

  credentials:
    type: object
    properties:
      access_key_id:
        type: string
      creation_date:
        type: integer
        format: int64

  credentials_with_secret:
    type: object
    properties:
      access_key_id:
        type: string
      access_secret_key:
        type: string
      creation_date:
        type: integer
        format: int64

  group:
    type: object
    properties:
      id:
        type: string
      creation_date:
        type: integer
        format: int64

  group_creation:
    type: object
    properties:
      id:
        type: string
    required:
      - id

  statement:
    type: object
    properties:
      effect:
        type: string
        enum: [allow, deny]
      resource:
        type: string
      action:
        type: array
        items:
          type: string
        minItems: 1
    required:
      - effect
      - resource
      - action

  policy:
    type: object
    properties:
      id:
        type: string
      creation_date:
        type: integer
        format: int64
      statement:
        type: array
        items:
          $ref: "#/definitions/statement"
        minItems: 1
    required:
      - id
      - statement

  retention_policy:
    type: object
    required:
      - rules
    properties:
      rules:
        type: array
        items:
          $ref: "#/definitions/retention_policy_rule"
      description:
        type: string

  retention_policy_with_creation_date:
    allOf:
      - $ref: "#/definitions/retention_policy"
      - type: object
        properties:
          creation_date:
            type: string
            format: date-time
        required:
          - creation_date

  retention_policy_rule:
    type: object
    required:
      - status
      - filter
    properties:
      status:
        type: string
        enum: [enabled, disabled]
      filter:
        type: object
        properties:
          prefix:
            type: string
      expiration:
        type: object
        minProperties: 1
        properties:
          all:
            $ref: "#/definitions/time_period"
          uncommitted:
            $ref: "#/definitions/time_period"
          noncurrent:
            $ref: "#/definitions/time_period"

  time_period:
    type: object
    description: |
        a number of days, which can be broken up into a sum of weeks
        and days
    properties:
      weeks:
        type: integer
        format: int32
      days:
        type: integer
        format: int32
    minProperties: 1

  config:
      type: object
      properties:
        blockstore.type:
          type: string

paths:

  /setup_lakefs:
    post:
      tags:
        - setup
      operationId: setupLakeFS
      summary: setup lakeFS and create the first user
      security: []
      parameters:
        - in: body
          name: user
          schema:
            $ref: "#/definitions/setup"
      responses:
        200:
          description: user created successfully
          schema:
            $ref: "#/definitions/credentials_with_secret"
        400:
          description: bad request
          schema:
            $ref: "#/definitions/error"
        409:
          description: setup was already called
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /user:
    get:
      tags:
        - auth
      operationId: getCurrentUser
      summary: get current user
      responses:
        200:
          description: user
          schema:
            type: object
            properties:
              user:
                $ref: "#/definitions/user"

  /auth/users:
    get:
      tags:
        - auth
      operationId: listUsers
      summary: list users
      parameters:
        - in: query
          name: after
          type: string
          default: ""
        - in: query
          name: amount
          type: integer
          default: 100
      responses:
        200:
          description: user list
          schema:
            type: object
            properties:
              pagination:
                $ref: "#/definitions/pagination"
              results:
                type: array
                items:
                  $ref: "#/definitions/user"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    post:
      tags:
        - auth
      operationId: createUser
      summary: create user
      parameters:
        - in: body
          name: user
          schema:
            $ref: "#/definitions/user_creation"
      responses:
        201:
          description: user
          schema:
            $ref: "#/definitions/user"
        400:
          description: validation error
          schema:
            $ref: "#/definitions/error"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /auth/users/{userId}:
    parameters:
      - in: path
        name: userId
        required: true
        type: string
    get:
      tags:
        - auth
      operationId: getUser
      summary: get user
      responses:
        200:
          description: user
          schema:
            $ref: "#/definitions/user"
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: user not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    delete:
      tags:
        - auth
      operationId: deleteUser
      summary: delete user
      responses:
        204:
          description: user deleted successfully
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: user not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /auth/groups:
    get:
      tags:
        - auth
      operationId: listGroups
      summary: list groups
      parameters:
        - in: query
          name: after
          type: string
          default: ""
        - in: query
          name: amount
          type: integer
          default: 100
      responses:
        200:
          description: group list
          schema:
            type: object
            properties:
              pagination:
                $ref: "#/definitions/pagination"
              results:
                type: array
                items:
                  $ref: "#/definitions/group"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    post:
      tags:
        - auth
      operationId: createGroup
      summary: create group
      parameters:
        - in: body
          name: group
          schema:
            $ref: "#/definitions/group_creation"
      responses:
        201:
          description: group
          schema:
            $ref: "#/definitions/group"
        400:
          description: validation error
          schema:
            $ref: "#/definitions/error"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /auth/groups/{groupId}:
    parameters:
      - in: path
        name: groupId
        required: true
        type: string
    get:
      tags:
        - auth
      operationId: getGroup
      summary: get group
      responses:
        200:
          description: group
          schema:
            $ref: "#/definitions/group"
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: group not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    delete:
      tags:
        - auth
      operationId: deleteGroup
      summary: delete group
      responses:
        204:
          description: group deleted successfully
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: group not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /auth/policies:
    get:
      tags:
        - auth
      operationId: listPolicies
      summary: list policies
      parameters:
        - in: query
          name: after
          type: string
          default: ""
        - in: query
          name: amount
          type: integer
          default: 100
      responses:
        200:
          description: policy list
          schema:
            type: object
            properties:
              pagination:
                $ref: "#/definitions/pagination"
              results:
                type: array
                items:
                  $ref: "#/definitions/policy"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    post:
      tags:
        - auth
      operationId: createPolicy
      summary: create policy
      parameters:
        - in: body
          name: policy
          schema:
            $ref: "#/definitions/policy"
      responses:
        201:
          description: policy
          schema:
            $ref: "#/definitions/policy"
        400:
          description: validation error
          schema:
            $ref: "#/definitions/error"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /auth/policies/{policyId}:
    parameters:
      - in: path
        name: policyId
        required: true
        type: string
    get:
      tags:
        - auth
      operationId: getPolicy
      summary: get policy
      responses:
        200:
          description: policy
          schema:
            $ref: "#/definitions/policy"
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: policy not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    put:
      tags:
        - auth
      operationId: updatePolicy
      summary: update policy
      parameters:
        - in: body
          name: policy
          schema:
            $ref: "#/definitions/policy"
      responses:
        200:
          description: policy
          schema:
            $ref: "#/definitions/policy"
        400:
          description: validation error
          schema:
            $ref: "#/definitions/error"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    delete:
      tags:
        - auth
      operationId: deletePolicy
      summary: delete policy
      responses:
        204:
          description: policy deleted successfully
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: policy not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /auth/groups/{groupId}/members:
    parameters:
      - in: path
        name: groupId
        required: true
        type: string
    get:
      tags:
        - auth
      operationId: listGroupMembers
      summary: list group members
      parameters:
        - in: query
          name: after
          type: string
          default: ""
        - in: query
          name: amount
          type: integer
          default: 100
      responses:
        200:
          description: user list
          schema:
            type: object
            properties:
              pagination:
                $ref: "#/definitions/pagination"
              results:
                type: array
                items:
                  $ref: "#/definitions/user"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /auth/groups/{groupId}/members/{userId}:
    parameters:
      - in: path
        name: groupId
        required: true
        type: string
      - in: path
        name: userId
        required: true
        type: string
    put:
      tags:
        - auth
      operationId: addGroupMembership
      summary: add group membership
      responses:
        201:
          description: membership added successfully
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    delete:
      tags:
        - auth
      operationId: deleteGroupMembership
      summary: delete group membership
      responses:
        204:
          description: membership deleted successfully
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: membership not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /auth/users/{userId}/credentials:
    parameters:
      - in: path
        name: userId
        required: true
        type: string
    get:
      tags:
        - auth
      parameters:
        - in: query
          name: after
          type: string
          default: ""
        - in: query
          name: amount
          type: integer
          default: 100
      operationId: listUserCredentials
      summary: list user credentials
      responses:
        200:
          description: credential list
          schema:
            type: object
            properties:
              pagination:
                $ref: "#/definitions/pagination"
              results:
                type: array
                items:
                  $ref: "#/definitions/credentials"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    post:
      tags:
        - auth
      operationId: createCredentials
      summary: create credentials
      responses:
        201:
          description: credentials
          schema:
            $ref: "#/definitions/credentials_with_secret"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /auth/users/{userId}/credentials/{accessKeyId}:
    parameters:
      - in: path
        name: userId
        required: true
        type: string
      - in: path
        name: accessKeyId
        required: true
        type: string
    delete:
      tags:
        - auth
      operationId: deleteCredentials
      summary: delete credentials
      responses:
        204:
          description: credentials deleted successfully
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: credentials not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    get:
      tags:
        - auth
      operationId: getCredentials
      summary: get credentials
      responses:
        200:
          description: credentials
          schema:
            $ref: "#/definitions/credentials"
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: credentials not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /auth/users/{userId}/groups:
    parameters:
      - in: path
        name: userId
        required: true
        type: string
    get:
      tags:
        - auth
      parameters:
        - in: query
          name: after
          type: string
          default: ""
        - in: query
          name: amount
          type: integer
          default: 100
      operationId: listUserGroups
      summary: list user groups
      responses:
        200:
          description: group list
          schema:
            type: object
            properties:
              pagination:
                $ref: "#/definitions/pagination"
              results:
                type: array
                items:
                  $ref: "#/definitions/group"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /auth/users/{userId}/policies:
    parameters:
      - in: path
        name: userId
        required: true
        type: string
    get:
      tags:
        - auth
      parameters:
        - in: query
          name: after
          type: string
          default: ""
        - in: query
          name: amount
          type: integer
          default: 100
        - in: query
          name: effective
          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
          schema:
            type: object
            properties:
              pagination:
                $ref: "#/definitions/pagination"
              results:
                type: array
                items:
                  $ref: "#/definitions/policy"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /auth/users/{userId}/policies/{policyId}:
    parameters:
      - in: path
        name: userId
        required: true
        type: string
      - in: path
        name: policyId
        required: true
        type: string
    put:
      tags:
        - auth
      operationId: attachPolicyToUser
      summary: attach policy to user
      responses:
        201:
          description: policy attached successfully
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    delete:
      tags:
        - auth
      operationId: detachPolicyFromUser
      summary: detach policy from user
      responses:
        204:
          description: policy detached successfully
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: policy attachment not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /auth/groups/{groupId}/policies:
    parameters:
      - in: path
        name: groupId
        required: true
        type: string
    get:
      tags:
        - auth
      parameters:
        - in: query
          name: after
          type: string
          default: ""
        - in: query
          name: amount
          type: integer
          default: 100
      operationId: listGroupPolicies
      summary: list group policies
      responses:
        200:
          description: policy list
          schema:
            type: object
            properties:
              pagination:
                $ref: "#/definitions/pagination"
              results:
                type: array
                items:
                  $ref: "#/definitions/policy"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /auth/groups/{groupId}/policies/{policyId}:
    parameters:
      - in: path
        name: groupId
        required: true
        type: string
      - in: path
        name: policyId
        required: true
        type: string
    put:
      tags:
        - auth
      operationId: attachPolicyToGroup
      summary: attach policy to group
      responses:
        201:
          description: policy attached successfully
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    delete:
      tags:
        - auth
      operationId: detachPolicyFromGroup
      summary: detach policy from group
      responses:
        204:
          description: policy detached successfully
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: policy attachment not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /repositories:
    get:
      tags:
        - repositories
      parameters:
        - in: query
          name: after
          type: string
          default: ""
        - in: query
          name: amount
          type: integer
          default: 100
      operationId: listRepositories
      summary: list repositories
      responses:
        200:
          description: repository list
          schema:
            type: object
            properties:
              pagination:
                $ref: "#/definitions/pagination"
              results:
                type: array
                items:
                  $ref: "#/definitions/repository"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    post:
      tags:
        - repositories
      operationId: createRepository
      summary: create repository
      parameters:
        - in: body
          name: repository
          schema:
            $ref: "#/definitions/repository_creation"
      responses:
        201:
          description: repository
          schema:
            $ref: "#/definitions/repository"
        400:
          description: validation error
          schema:
            $ref: "#/definitions/error"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /repositories/{repository}:
    parameters:
      - in: path
        name: repository
        required: true
        type: string
    get:
      tags:
        - repositories
      operationId: getRepository
      summary: get repository
      responses:
        200:
          description: repository
          schema:
            $ref: "#/definitions/repository"
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: repository not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    delete:
      tags:
        - repositories
      operationId: deleteRepository
      summary: delete repository
      responses:
        204:
          description: repository deleted successfully
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: repository not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /repositories/{repository}/inventory/s3/import:
    parameters:
      - in: path
        name: repository
        required: true
        type: string
      - in: query
        name: manifestUrl
        required: true
        type: string
      - in: query
        name: dryRun
        type: boolean
        default: false
    post:
      tags:
        - repositories
      operationId: importFromS3Inventory
      summary: import metadata for an existing bucket in S3
      responses:
        201:
          description: import results
          schema:
            type: object
            properties:
              is_dry_run:
                type: boolean
              added_or_changed:
                type: integer
                format: int64
              deleted:
                type: integer
                format: int64
              previous_manifest:
                type: string
              previous_import_date:
                type: integer
                format: int64
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: "repository not found"
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
  /repositories/{repository}/branches:
    parameters:
      - in: path
        name: repository
        required: true
        type: string
    get:
      tags:
        - branches
      operationId: listBranches
      summary: list branches
      parameters:
        - in: query
          name: after
          type: string
          default: ""
        - in: query
          name: amount
          type: integer
          default: 100
      responses:
        200:
          description: branch list
          schema:
            type: object
            properties:
              pagination:
                $ref: "#/definitions/pagination"
              results:
                type: array
                items:
                  type: string
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    post:
      tags:
        - branches
      operationId: createBranch
      summary: create branch
      parameters:
        - in: body
          name: branch
          schema:
            $ref: "#/definitions/branch_creation"
      responses:
        201:
          description: reference
          schema:
            type: string
        400:
          description: validation error
          schema:
            $ref: "#/definitions/error"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /repositories/{repository}/branches/{branch}/commits:
    parameters:
      - in: path
        name: repository
        required: true
        type: string
      - in: path
        name: branch
        required: true
        type: string
    get:
      tags:
        - commits
      operationId: getBranchCommitLog
      summary: get commit log for branch
      parameters:
        - in: query
          name: after
          type: string
        - in: query
          name: amount
          type: integer
      responses:
        200:
          description: commit log
          schema:
            type: object
            properties:
              pagination:
                $ref: "#/definitions/pagination"
              results:
                type: array
                items:
                  $ref: "#/definitions/commit"
        401:
          description: Unauthorized
          schema:
            $ref: "#/responses/Unauthorized"
        404:
          description: branch not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    post:
      tags:
        - commits
      operationId: commit
      summary: create commit
      parameters:
        - in: body
          name: commit
          schema:
            $ref: "#/definitions/commit_creation"
      responses:
        201:
          description: commit
          schema:
            $ref: "#/definitions/commit"
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: branch not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /repositories/{repository}/branches/{branch}:
    parameters:
      - in: path
        name: repository
        required: true
        type: string
      - in: path
        name: branch
        required: true
        type: string
    get:
      tags:
        - branches
      operationId: getBranch
      summary: get branch
      responses:
        200:
          description: branch
          schema:
            type: string
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: branch not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    delete:
      tags:
        - branches
      operationId: deleteBranch
      summary: delete branch
      responses:
        204:
          description: branch deleted successfully
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: branch not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    put:
      tags:
        - branches
      operationId: revertBranch
      summary: revert branch
      parameters:
        - in: body
          name: revert
          description: "revert parameters"
          schema:
            $ref: "#/definitions/revert_creation"
      responses:
        204:
          description: reverted
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: resource not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /repositories/{repository}/refs/{sourceRef}/merge/{destinationRef}:
    parameters:
      - in: path
        name: repository
        required: true
        type: string
      - in: path
        name: sourceRef
        required: true
        type: string
        description: source branch name
      - in: path
        name: destinationRef
        required: true
        type: string
        description: destination branch name

    post:
      tags:
        - refs
      operationId: mergeIntoBranch
      summary: merge references
      parameters:
        - in: body
          name: merge
          schema:
            $ref: "#/definitions/merge"
      responses:
        200:
          description: merge completed
          schema:
            $ref: "#/definitions/merge_result"
        401:
          description: Unauthorized
          schema:
            $ref: "#/responses/Unauthorized"
        404:
          description: reference not found
          schema:
            $ref: "#/definitions/error"
        409:
          description: conflict
          schema:
            $ref: "#/definitions/merge_result"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /repositories/{repository}/branches/{branch}/diff:
    parameters:
      - in: path
        name: repository
        required: true
        type: string
      - in: path
        name: branch
        required: true
        type: string
      - in: query
        name: after
        type: string
      - in: query
        name: amount
        type: integer
    get:
      tags:
        - branches
      operationId: diffBranch
      summary: diff branch
      responses:
        200:
          description: diff of branch uncommitted changes
          schema:
            type: object
            properties:
              pagination:
                $ref: "#/definitions/pagination"
              results:
                type: array
                items:
                  $ref: "#/definitions/diff"
        401:
          description: Unauthorized
          schema:
            $ref: "#/responses/Unauthorized"
        404:
          description: branch not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"


  /repositories/{repository}/refs/{leftRef}/diff/{rightRef}:
    parameters:
      - in: path
        name: repository
        required: true
        type: string
      - in: path
        name: leftRef
        required: true
        type: string
        description: a reference (could be either a branch or a commit ID)
      - in: path
        name: rightRef
        required: true
        type: string
        description: a reference (could be either a branch or a commit ID) to compare against
      - in: query
        name: after
        type: string
      - in: query
        name: amount
        type: integer
    get:
      tags:
        - refs
      operationId: diffRefs
      summary: diff references
      responses:
        200:
          description: diff between refs
          schema:
            type: object
            properties:
              pagination:
                $ref: "#/definitions/pagination"
              results:
                type: array
                items:
                  $ref: "#/definitions/diff"
        401:
          description: Unauthorized
          schema:
            $ref: "#/responses/Unauthorized"
        404:
          description: reference not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /repositories/{repository}/commits/{commitId}:
    parameters:
      - in: path
        name: repository
        required: true
        type: string
      - in: path
        name: commitId
        required: true
        type: string
    get:
      tags:
        - commits
      operationId: getCommit
      summary: get commit
      responses:
        200:
          description: commit
          schema:
            $ref: "#/definitions/commit"
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: commit not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /repositories/{repository}/refs/{ref}/objects:
    parameters:
      - in: path
        name: repository
        required: true
        type: string
      - in: path
        name: ref
        required: true
        type: string
        description: a reference (could be either a branch or a commit ID)
      - in: query
        name: path
        required: true
        type: string
    get:
      tags:
        - objects
      operationId: getObject
      summary: get object content
      produces:
        - application/octet-stream
      responses:
        200:
          description: object content
          schema:
            type: file
          headers:
            Content-Length:
              type: integer
              format: int64
            Last-Modified:
              type: string
            ETag:
              type: string
            Content-Disposition:
              type: string
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: resource not found
          schema:
            $ref: "#/definitions/error"
        410:
          description: object expired
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /repositories/{repository}/branches/{branch}/objects:
    parameters:
      - in: path
        name: repository
        required: true
        type: string
      - in: path
        name: branch
        required: true
        type: string
      - in: query
        name: path
        required: true
        type: string
    post:
      tags:
        - objects
      operationId: uploadObject
      summary: upload object content
      parameters:
        - in: formData
          name: content
          type: file
          description: Object content to upload
        - in: query
          name: storageClass
          required: false
          type: string
      consumes:
        - multipart/form-data
      responses:
        201:
          description: object metadata
          schema:
            $ref: "#/definitions/object_stats"
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: repository or branch not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    delete:
      tags:
        - objects
      operationId: deleteObject
      summary: delete object
      responses:
        204:
          description: object deleted successfully
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: path or branch not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /repositories/{repository}/refs/{ref}/objects/stat:
    parameters:
      - in: path
        name: repository
        required: true
        type: string
      - in: path
        name: ref
        required: true
        type: string
        description: a reference (could be either a branch or a commit ID)
      - in: query
        name: path
        required: true
        type: string
    get:
      tags:
        - objects
      operationId: statObject
      summary: get object metadata
      responses:
        200:
          description: object metadata
          schema:
            $ref: "#/definitions/object_stats"
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: path or branch not found
          schema:
            $ref: "#/definitions/error"
        410:
          description: object gone (but partial metadata may be available)
          schema:
            $ref: "#/definitions/object_stats"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /repositories/{repository}/refs/{ref}/objects/underlyingProperties/:
    parameters:
      - in: path
        name: repository
        required: true
        type: string
      - in: path
        name: ref
        required: true
        type: string
        description: a reference (could be either a branch or a commit ID)
      - in: query
        name: path
        required: true
        type: string
    get:
      tags:
        - objects
      operationId: getUnderlyingProperties
      summary: get object properties on underlying storage
      responses:
        200:
          description: object metadata on underlying storage
          schema:
            $ref: "#/definitions/underlying_object_properties"
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: path or branch not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /repositories/{repository}/refs/{ref}/objects/ls:
    parameters:
      - in: path
        name: repository
        required: true
        type: string
      - in: path
        name: ref
        required: true
        type: string
        description: a reference (could be either a branch or a commit ID)
      - in: query
        name: prefix
        required: false
        type: string
      - in: query
        name: after
        type: string
      - in: query
        name: amount
        type: integer
    get:
      tags:
        - objects
      operationId: listObjects
      summary: list objects under a given prefix
      responses:
        200:
          description: entry list
          schema:
            type: object
            properties:
              pagination:
                $ref: "#/definitions/pagination"
              results:
                type: array
                items:
                  $ref: "#/definitions/object_stats"
        404:
          description: prefix or branch not found
          schema:
            $ref: "#/definitions/error"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

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

      responses:
        201:
          description: location created
          schema:
            description: "path to created location"
            type: string
        401:
          $ref: "#/responses/Unauthorized"
        404:
          description: repository or branch not found
          schema:
            $ref: "#/definitions/error"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"


  /repositories/{repository}/retention:
    parameters:
      - in: path
        name: repository
        required: true
        type: string
    put:
      tags:
        - retention
      operationId: updateRetentionPolicy
      description: set retention policy for repository
      parameters:
        - in: body
          name: policy
          required: true
          schema:
            $ref: "#/definitions/retention_policy"
      responses:
        201:
          description: policy attached successfully
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"
    get:
      operationId: getRetentionPolicy
      tags:
        - retention
      description: get retention policy for repository
      responses:
        200:
          description: retention policy
          schema:
            $ref: "#/definitions/retention_policy_with_creation_date"
        401:
          $ref: "#/responses/Unauthorized"
        default:
          description: generic error response
          schema:
            $ref: "#/definitions/error"

  /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 the lakefs config
      responses:
        200:
          description: the lakefs config
          schema:
            $ref: "#/definitions/config"
        401:
          $ref: "#/responses/Unauthorized"