openapi: 3.0.3

info:
  title: File Notes
  description: "For retrieving and managing file notes. For information of how to construct requests utilising fieldsets, sorting, paging, filters, and '*includes*', please refer to the API Developer Portal. E&OE."
  version: "1.0"

externalDocs:
  description: API Developer Portal - Constructing API Requests
  url: https://docs.actionstep.com/api-requests/

paths:
  '/filenotes':
    get:
      description: Returns a collection of file notes.
      tags:
        - File Notes
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedFileNotes'

    post:
      description: Create a new file note.
      tags:
        - File Notes
      requestBody:
        $ref: '#/components/requestBodies/CreateFileNote'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileNote'

  '/filenotes/{id}':
    get:
      description: Returns a single file note.
      tags:
        - File Notes
      parameters:
        - name: id
          in: path
          description: Unique identifier for a file note.
          required: true
          schema:
            type: integer
            format: int32
          example: 9287
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileNote'

    put:
      description: Update a file note.
      tags:
        - File Notes
      parameters:
        - name: id
          in: path
          description: Unique identifier for a file note.
          required: true
          schema:
            type: integer
            format: int32
          example: 608
      requestBody:
        $ref: '#/components/requestBodies/UpdateFileNote'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileNote'

    delete:
      description: Delete a file note.
      tags:
        - File Notes
      parameters:
        - name: id
          in: path
          description: Unique identifier for a file note.
          required: true
          schema:
            type: integer
            format: int32
          example: 608
      responses:
        '204':
          description: Success, No Content.

components:
  schemas:
    PagedFileNotes:
      type: object
      properties:
        filenotes:
          type: array
          items:
            $ref: '#/components/schemas/FileNote'
        meta:
          $ref: '#/components/schemas/PageMetaData'

    PageMetaData:
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/PagingData'

    PagingData:
      type: object
      properties:
        filenotes:
          $ref: '#/components/schemas/FileNotesPageData'

    FileNotesPageData:
      type: object
      properties:
        recordCount:
          description: The total number of file notes returned by the underlying query.
          type: integer
          example: 2487
        pageCount:
          description: The total number of pages generated by the underlying query.
          type: integer
          example: 50
        page:
          description: The page number for this page of file notes.
          type: integer
          example: 2
        pageSize:
          description: Page size.
          type: integer
          example: 50
        prevPage:
          description: A URL to the previous page of file notes.
          type: string
          example: https://ap-southeast-2.actionstep.com/api/rest/filenotes?page=1
        nextPage:
          description: A URL to the next page of file notes.
          type: string
          example: https://ap-southeast-2.actionstep.com/api/rest/filenotes?page=3

    FileNote:
      type: object
      properties:
        id:
          description: Unique identifier for the file note.
          example: 2347
          type: integer
          readOnly: true
        enteredTimestamp:
          description: The date and time the file note is entered.
          example: 2022-05-03T00:09:00+12:00
          format: timestamp
          type: string
          readOnly: true
        text:
          description: Content of the file note.
          example: Client is requesting follow up meeting this week.
          type: string
        enteredBy:
          description: The Actionstep user who entered the file note.
          example: Smith, John
          type: string
          readOnly: true
        source:
          description: Indicates the source of the file note.
          enum:
            - System
            - User
          example: User
          type: string
        noteTimestamp:
          description: The date and time for the file note.
          example: 2023-06-03T00:09:30+12:00
          format: timestamp
          type: string
        links:
          $ref: '#/components/schemas/FileNoteLinks'

    FileNoteLinks:
      type: object
      properties:
        action:
          description: Unique identifier of the matter to which the file note is associated.
          example: 34
          type: integer
        document:
          description: Unique identifier of a document associated to the file note.
          example: 8376
          type: integer
        participant:
          description: Unique identifier of the Actionstep user who created the file note.
          example: 546
          type: integer
          readOnly: true
        tags:
          description: Zero or more tags associated with the file note. Each tag is the unique identifier for the tag.
          example: [1283, 1934]
          type: array
          items:
            type: integer

    CreateFileNote:
      type: object
      required:
        - text
      properties:
        text:
          description: Content of the file note.
          example: Client is requesting follow up meeting this week.
          type: string
        source:
          description: Indicates the source of the file note.
          enum:
            - System
            - User
          example: User
          type: string
        noteTimestamp:
          description: The date and time for the file note.
          example: 2023-06-03T00:09:30+12:00
          format: timestamp
          type: string
        links:
          $ref: '#/components/schemas/CreateFileNoteLinks'

    CreateFileNoteLinks:
      type: object
      required:
        - action
      properties:
        action:
          description: Unique identifier of the matter to which the file note is associated.
          example: 34
          type: integer
        document:
          description: Unique identifier of a document associated to the file note.
          example: 8376
          type: integer
        tags:
          description: Zero or more tags to be associated with the file note. Each tag is the unique identifier for the tag.
          example: [1283, 1934]
          type: array
          items:
            type: integer

    UpdateFileNote:
      type: object
      required:
        - text
      properties:
        text:
          description: Content of the file note.
          example: Client is requesting follow up meeting this week.
          type: string
        noteTimestamp:
          description: The date and time for the file note.
          example: 2023-06-03T00:09:30+12:00
          format: timestamp
          type: string
        links:
          $ref: '#/components/schemas/UpdateFileNoteLinks'

    UpdateFileNoteLinks:
      type: object
      properties:
        action:
          description: Unique identifier of the matter to which the file note is associated.
          example: 34
          type: integer
        document:
          description: Unique identifier of a document associated to the file note.
          example: 8376
          type: integer
        tags:
          description: Zero or more tags to be associated with the file note. Each tag is the unique identifier for the tag. The supplied list of tags will replace in totality any existing tags. To remove all tags specify an empty array.
          example: [1283, 1934]
          type: array
          items:
            type: integer

  requestBodies:
    CreateFileNote:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateFileNote'

    UpdateFileNote:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateFileNote'