openapi: 3.0.1
info:
  title: Elevate Document API
  description: >
    ### Document management


    Provides read & write access to Elevate documents


    #### Definitions

    * Document - a file or folder. A file being a single unit of storage that
    has a name and can be uploaded or uploaded. A folder holds one or more
    files, and a folder can be empty until it is filled. A folder can also
    contain other folders, and there can be many levels of folders within
    folders
  version: '1.0'
servers:
  - url: https://rest.elevatebilling.com/v1
tags:
  - name: documents
    description: >-
      Document being a file or folder. A file being a single unit of storage
      that has a name and can be uploaded or downloaded. A folder holds one or
      more files, and a folder can be empty until it is filled. A folder can
      also contain other folders, and there can be many levels of folders within
      folders
paths:
  /documents:
    get:
      tags:
        - documents
      summary: Get a page of documents in a specific folder
      operationId: getDocuments
      x-si-permissions:
        - VIEW_DOCUMENT
      security:
        - bearerAuth: []
      x-si-filterable: true
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
        - name: level
          in: query
          description: Filter by document level, e.g. CUSTOMER
          schema:
            $ref: '#/components/schemas/DocumentLevel'
          required: true
        - name: levelId
          in: query
          description: Filter by level id, e.g. customer id 1234
          schema:
            $ref: '#/components/schemas/IdFilterParam'
          required: true
        - name: parentDocumentId
          in: query
          description: >-
            Filter by folder id, e.g. folder ABC with id 456, omitting this
            implies the root folder
          schema:
            $ref: '#/components/schemas/IdFilterParam'
          required: false
        - name: tags
          in: query
          description: Filter by tag name
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: name
          in: query
          description: Filter by document name
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: recursive
          in: query
          description: Search all sub-folders below the folder level specified
          schema:
            $ref: '#/components/schemas/BooleanFilterParam'
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Document'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
    head:
      tags:
        - documents
      summary: Check if documents exists
      operationId: checkDocuments
      x-si-response-headers: true
      x-si-permissions:
        - VIEW_DOCUMENT
      security:
        - bearerAuth: []
      parameters:
        - name: level
          in: query
          description: Filter by document level, e.g. CUSTOMER
          schema:
            $ref: '#/components/schemas/DocumentLevel'
          required: true
        - name: levelId
          in: query
          description: Filter by level id, e.g. customer id 1234
          schema:
            $ref: '#/components/schemas/IdFilterParam'
          required: true
        - name: parentDocumentId
          in: query
          description: >-
            Filter by folder id, e.g. folder ABC with id 456, omitting this
            implies the root folder
          schema:
            $ref: '#/components/schemas/IdFilterParam'
          required: false
        - name: tags
          in: query
          description: Filter by tag name
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: name
          in: query
          description: Filter by document name
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: recursive
          in: query
          description: Search all sub-folders below the folder specified
          schema:
            $ref: '#/components/schemas/BooleanFilterParam'
          required: false
      responses:
        '200':
          description: Exists
          headers:
            X-Total-Count:
              schema:
                type: integer
                description: Total number of documents
          content: {}
        '400':
          description: Invalid Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
    post:
      tags:
        - documents
      summary: Upload a new file or create a new folder
      operationId: createDocument
      x-si-permissions:
        - CREATE_DOCUMENT
      x-si-apply-impact-of-change: false
      security:
        - bearerAuth: []
      requestBody:
        description: New file or folder
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                fileContent:
                  type: multipartFile
                  description: File content in application/excel format
                  format: binary
                upload:
                  $ref: '#/components/schemas/Document'
        required: true
      responses:
        '201':
          description: OK - document uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
  /documents/{id}:
    get:
      tags:
        - documents
      summary: Find a document using the document identifier
      operationId: getDocument
      x-si-permissions:
        - VIEW_DOCUMENT
      x-si-filterable: false
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: Document identifier
          required: true
          schema:
            $ref: '#/components/schemas/IdParam'
      responses:
        '200':
          description: Found document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
    patch:
      tags:
        - documents
      summary: Update a file or folder's attributes
      operationId: updateDocument
      x-si-json-patch: true
      x-si-allow-patch:
        - /name
        - /tags/.*
      x-si-permissions:
        - UPDATE_DOCUMENT
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: Document identifier
          required: true
          schema:
            $ref: '#/components/schemas/IdParam'
      requestBody:
        description: A set of JSONPatch operations to be performed
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/PatchRequest'
            examples:
              Rename:
                value:
                  - op: replace
                    path: /name
                    value: MyFile.txt
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '400':
          description: Invalid Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
  /document-contents/{id}:
    get:
      tags:
        - documents
      summary: Download the contents of the file or folder
      description: >-
        Download the contents of the file or folder. If a folder it will zip the
        files and folders within
      operationId: downloadDocument
      x-si-permissions:
        - VIEW_DOCUMENT
      x-si-filterable: false
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: Document identifier
          required: true
          schema:
            $ref: '#/components/schemas/IdParam'
      responses:
        '200':
          description: A file contents or zip file of folder
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    Document:
      required:
        - level
        - levelId type
        - name
      type: object
      properties:
        id:
          description: Document identifier
          type: integer
          readOnly: true
          format: int64
          example: 1
        parentDocumentId:
          description: Parent document identifier
          type: integer
          format: int64
          example: 1
        levelId:
          description: Level identifier, e.g. customer id
          type: integer
          format: int64
          example: 1
        level:
          $ref: '#/components/schemas/DocumentLevel'
        type:
          $ref: '#/components/schemas/DocumentType'
        name:
          type: string
          description: File of folder name
          minLength: 1
          maxLength: 100
          pattern: '[a-zA-Z0-9_.\-\s]*'
          example: /helloworld.doc
        owner:
          type: string
          description: >-
            Owner of document, the person who uploaded the file or created the
            folder
          readOnly: true
          minLength: 1
          maxLength: 150
          pattern: '[\w\p{L}\s%£@&#='':;`’,|!_—–\(\)\\/\-\+\.\?\*\$]*'
          example: Tommy Tynan
        ownerUserId:
          description: User id for the owner of the document
          readOnly: true
          type: integer
          format: int64
          example: 1
        sizeInKb:
          description: Size of document in Kilo Byte (KB)
          readOnly: true
          type: integer
          format: int64
          example: 1
        path:
          type: string
          readOnly: true
          description: Parent folder name, might be missing for root
          minLength: 1
          maxLength: 1000
          pattern: '[\w\p{L}\s%£@&#='':;`’,|!_—–\(\)\\/\-\+\.\?\*\$]*'
          example: /folder1/folder2/
        uploadDateTime:
          readOnly: true
          description: File or folder upload date and time
          type: string
          format: date-time
        tags:
          description: >-
            Zero or more tags associated with the file or folder. Might be
            'Star' or 'Private' or even 'Deleted'
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    Tag:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Tag name
          minLength: 1
          maxLength: 100
          pattern: '[\w\p{L}\s%£@&#='':;`’,|!_—–\(\)\\/\-\+\.\?\*\$]*'
    DocumentLevel:
      description: Level of document
      type: string
      enum:
        - CUSTOMER
    DocumentType:
      description: Type of document
      type: string
      enum:
        - FILE
        - FOLDER
    PageParam:
      description: Page of results to show
      minimum: 1
      type: integer
      format: int32
      example: 1
    ResultsPerPageParam:
      description: Results to return per page
      maximum: 1000
      minimum: 1
      type: integer
      format: int32
      example: 100
    SortParam:
      description: >-
        Comma-delimited list of the fields to sort by - defaults to ascending
        order, suffix :desc to change
      example: id,name | name:desc
      type: string
    FieldsParam:
      description: >-
        Comma-delimited list of the field(s) to return if only a subset is
        required
      example: id,name
      type: string
    IdFilterParam:
      description: Filter by this numeric id value
      example: '0'
      type: string
    StringFilterParam:
      description: >-
        Filter by this string value where value can optionally be prefixed
        (in:|like:)
      example: xyz | in:x,y | like:xyz
      type: string
    BooleanFilterParam:
      description: Filter by this boolean value (true or false)
      example: true | false
      type: string
    IdParam:
      description: Identifier
      minimum: 1
      type: integer
      format: int64
      example: 1
    PatchDocument:
      description: A JSONPatch document as defined by RFC 6902
      required:
        - op
        - path
      type: object
      properties:
        op:
          type: string
          description: The JSON Patch operation to be performed
          x-si-exclude: true
          enum:
            - add
            - remove
            - replace
            - move
            - copy
            - test
        path:
          type: string
          description: A JSON-Pointer
        value:
          type: object
          properties: {}
          description: The value to be used within the operations
        from:
          type: string
          description: A string containing a JSON Pointer value
    PatchRequest:
      type: array
      description: >-
        JSON Patch is a format for describing changes to a JSON document as
        specified in RFC 6902. Refer to [jsonpatch.com](http://jsonpatch.com/)
        for more information
      items:
        $ref: '#/components/schemas/PatchDocument'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    page:
      name: page
      in: query
      description: Page of results to show
      schema:
        $ref: '#/components/schemas/PageParam'
      required: true
    pageSize:
      name: pageSize
      description: Results to return per page
      in: query
      schema:
        $ref: '#/components/schemas/ResultsPerPageParam'
      required: true
    sort:
      name: sort
      in: query
      description: >-
        Comma-delimited list of the fields to sort by - defaults to ascending
        order, suffix :desc to change
      schema:
        $ref: '#/components/schemas/SortParam'
      required: false
    fields:
      name: fields
      in: query
      description: >-
        Comma-delimited list of the field(s) to return if only a subset is
        required
      schema:
        $ref: '#/components/schemas/FieldsParam'
      required: false
