Smokeball Folders API

openapi: 3.2.0
info:
  title: Smokeball Activity Codes Folders API
  version: '1.0'
  description: REST API for integrating with Smokeball legal practice management software. Supports matters, contacts, documents, time entries, billing, trust accounting, staff, webhooks, and law firm workflows across US, AU, and UK regions. Uses OAuth 2.0 (client credentials) authentication.
  contact:
    name: Smokeball Developer Support
    url: https://docs.smokeball.com/docs/api-docs/1e13a13124aee-introduction
  x-api-id: smokeball
  x-audience: external-public
servers:
- url: https://api.smokeball.com
- url: https://api.smokeball.com.au
- url: https://api.smokeball.co.uk
- url: https://stagingapi.smokeball.com
- url: https://stagingapi.smokeball.com.au
- url: https://stagingapi.smokeball.co.uk
security:
- api-key: []
  token: []
tags:
- name: Folders
paths:
  /matters/{matterId}/documents/folders:
    get:
      tags:
      - Folders
      summary: Get folders/files under root folder
      description: Returns a list of sub folders and files under the root folder of a matter.
      operationId: GetFolders
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      - name: Offset
        in: query
        schema:
          maximum: 2147483647
          minimum: 0
          type: integer
          format: int32
      - name: Limit
        in: query
        schema:
          maximum: 500
          minimum: 1
          type: integer
          format: int32
      responses:
        '200':
          description: When request is successful. Returns a paged collection of 'FolderListing' objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderListingPagedCollection'
        '403':
          description: When the requested matter does not belong to the account making the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    post:
      tags:
      - Folders
      summary: Create a folder
      description: Creates a new folder under the specified matter.
      operationId: CreateRootFolder
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/FolderDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/FolderDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/FolderDto'
      responses:
        '202':
          description: When request is accepted. Returns a hypermedia 'Link' object of the folder to be created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When folder name is not provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /matters/{matterId}/documents/folders/{folderId}:
    get:
      tags:
      - Folders
      summary: Get folders/files under a folder
      description: Returns a list of sub folders and files under a specified folder of a matter.
      operationId: GetFolderById
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      - name: folderId
        in: path
        required: true
        schema:
          type: string
      - name: Offset
        in: query
        schema:
          maximum: 2147483647
          minimum: 0
          type: integer
          format: int32
      - name: Limit
        in: query
        schema:
          maximum: 500
          minimum: 1
          type: integer
          format: int32
      responses:
        '200':
          description: When request is successful. Returns a paged collection of 'FolderListing' objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderListingPagedCollection'
        '403':
          description: When the requested matter does not belong to the account making the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When folder with the specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      tags:
      - Folders
      summary: Update a folder
      description: Updates a folder belonging to the specified matter.
      operationId: UpdateFolder
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      - name: folderId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/FolderDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/FolderDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/FolderDto'
      responses:
        '202':
          description: When request is accepted. Returns a hypermedia 'Link' object of the folder to be updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When folder name is not provided or folder does not belong to the specified matter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When folder with the specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    patch:
      tags:
      - Folders
      summary: Patch a folder
      description: Updates a folder belonging to the specified matter.
      operationId: PatchFolder
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      - name: folderId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/FolderDto'
          application/json:
            schema:
              $ref: '#/components/schemas/FolderDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/FolderDto'
      responses:
        '202':
          description: When request is accepted. Returns a hypermedia 'Link' object of the folder to be updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When folder name is not provided or folder does not belong to the specified matter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When folder with the specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
      - Folders
      summary: Delete a folder
      description: Deletes a folder belonging to the specified matter.
      operationId: DeleteFolder
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: folderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: When request is accepted. Returns a hypermedia 'Link' object of the folder to be deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When the folder does not belong to the specified matter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /matters/{matterId}/documents/folders/{folderId}/path:
    get:
      tags:
      - Folders
      summary: Get folder path hierarchy
      description: 'Returns the full folder hierarchy (path) as a collection ordered from the root folder down to the supplied folder.


        The root folder is not included in the response.'
      operationId: GetFolderPath
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      - name: folderId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: When request is successful. Returns the folder path hierarchy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderPathSegmentCollection'
        '403':
          description: When the requested matter does not belong to the account making the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When folder with the specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /matters/{matterId}/documents/folders/{folderId}/history:
    get:
      tags:
      - Folders
      summary: Get folder history on a matter
      description: Returns a list of history entries for the specified folder.
      operationId: GetFolderHistory
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      - name: folderId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: When request is successful. Returns a collection of 'FileFolderLogEntry' objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileFolderLogEntryCollection'
        '403':
          description: When the requested matter does not belong to the account making the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    FolderListing:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        href:
          type:
          - string
          - 'null'
        relation:
          type:
          - string
          - 'null'
        method:
          type:
          - string
          - 'null'
          default: GET
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
        folders:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Folder'
          description: List of folders
          readOnly: true
        files:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/File'
          description: List of files
          readOnly: true
      additionalProperties: false
    FileFolderLogEntry:
      type: object
      properties:
        href:
          type:
          - string
          - 'null'
        relation:
          type:
          - string
          - 'null'
        method:
          type:
          - string
          - 'null'
          default: GET
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
        id:
          type:
          - string
          - 'null'
          description: Unique identifier of this log entry.
          example: 3f2b1f2a-1d5f-48a4-8f3c-7a7a3c2b5e1a
        type:
          type: string
          description: The type of entity this log entry refers to.
          example: File
        changeType:
          type: string
          description: The type of change that occurred.
          example: Move
        timestamp:
          type: string
          description: When the client recorded the action (UTC).
          format: date-time
          example: '2025-08-27T04:12:45Z'
        file:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: Link to the file affected by this entry (only populated when Type is File).
        folder:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: Link to the folder affected by this entry (only populated when Type is Folder).
        oldName:
          type:
          - string
          - 'null'
          description: Old name prior to a rename operation (when applicable).
          example: Draft Response
        newName:
          type:
          - string
          - 'null'
          description: New name after a rename operation (when applicable).
          example: Final Response
        oldMatterId:
          type:
          - string
          - 'null'
          description: Previous matter identifier (for move/copy across matters).
          example: f9e1a9d5-1d2b-4bd2-9a72-6a6e7b5c2f01
        newMatterId:
          type:
          - string
          - 'null'
          description: New matter identifier (for move/copy across matters).
          example: 1c0b8a31-0a05-4601-8b87-2d7b1d0caa9a
        oldFolderId:
          type:
          - string
          - 'null'
          description: Previous folder identifier (for move within/between matters).
          example: 6a5c3b2e-0f1e-4c7e-90e2-2ad3c3e8b0b9
        newFolderId:
          type:
          - string
          - 'null'
          description: New folder identifier (for move within/between matters).
          example: 9b7a2c4d-2e1f-4b6a-8e01-1f2a3b4c5d6e
        copySourceFileId:
          type:
          - string
          - 'null'
          description: For copy operations, the source file's identifier when copying a file.
          example: bb3a6c1d-1e2f-4a7b-9c01-0d9a8c7b6e5f
        copySourceFolderId:
          type:
          - string
          - 'null'
          description: For copy operations, the source folder's identifier when copying a folder.
          example: aa2b5c1e-7f8a-4d9e-8c01-1a2b3c4d5e6f
        documentVersionId:
          type:
          - string
          - 'null'
          description: 'Identifier of the document version involved (only for version replace/revert scenarios).

            Can be used to download particular file versions.'
          example: 2d97e267-0618-4822-a515-281cd4f31ae8-72324ca30d263b32bb38a481cc5f7a0b
        userId:
          type:
          - string
          - 'null'
          description: The user who is responsible for this change.
      additionalProperties: false
      description: Represents a single file/folder activity (rename, move, delete, etc.).
    File:
      type: object
      properties:
        href:
          type:
          - string
          - 'null'
        relation:
          type:
          - string
          - 'null'
        method:
          type:
          - string
          - 'null'
          default: GET
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
        id:
          type:
          - string
          - 'null'
          description: Unique identifier of the file.
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        versionId:
          type:
          - string
          - 'null'
          description: Unique identifier of the file's current version.
        folder:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: Hypermedia link of the folder to which the file belongs.
        matter:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: Hypermedia link of the matter to which the file belongs.
        name:
          type:
          - string
          - 'null'
          description: Name of the file, excluding file extension.
          example: court filing
        fileExtension:
          type:
          - string
          - 'null'
          description: Extension of the file.
          example: .pdf
        ownerId:
          type:
          - string
          - 'null'
          description: Unique identifier of the user who created/uploaded this file.
          example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
        to:
          type:
          - string
          - 'null'
          description: The 'To' or recipients' email address (only applicable for email files).
          example: recipient@email.com
        from:
          type:
          - string
          - 'null'
          description: The 'From' or sender's email address (only applicable for email files).
          example: sender@email.com
        dateCreated:
          type: string
          description: The original datetime that the file was created.
          format: date-time
          example: '2022-04-23T14:00:00Z'
        dateModified:
          type: string
          description: The datetime that the file was last modified.
          format: date-time
          example: '2022-04-25T17:00:00Z'
        sizeBytes:
          type: integer
          description: Size of the file (in bytes).
          format: int64
          example: 19104768
        downloadInfo:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: Hypermedia link to the download details of the file.
        additionalData:
          type:
          - object
          - 'null'
          additionalProperties: {}
          description: Collection of file meta data as KeyValuePair(string, object).
        isFavorite:
          type: boolean
          description: Flag indicating whether this file is a favorite
          example: false
        isUploaded:
          type: boolean
          description: Flag indicating whether the file contents are uploaded to the server.
          example: false
        isCancelled:
          type: boolean
          description: Flag indicating whether the file upload has been cancelled.
          example: false
        isDuplicate:
          type: boolean
          description: Flag indicating whether the file data is duplicated. Applies to emails only for now.
        isDeleted:
          type: boolean
          description: Flag indicating whether the file has been deleted.
          example: false
      additionalProperties: false
    FolderDto:
      required:
      - name
      type: object
      properties:
        name:
          maxLength: 256
          minLength: 1
          type: string
          description: Name of the folder
          example: Property Documents
        parentFolderId:
          type:
          - string
          - 'null'
          description: Unique identifier of the parent folder
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        userId:
          type:
          - string
          - 'null'
          description: Unique identifier of the user modifying the folder. If null it will fallback to the authenticated user
          example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
      additionalProperties: false
    FileFolderLogEntryCollection:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        href:
          type:
          - string
          - 'null'
        relation:
          type:
          - string
          - 'null'
        method:
          type:
          - string
          - 'null'
          default: GET
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
        value:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/FileFolderLogEntry'
      additionalProperties: false
    Link:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        href:
          type:
          - string
          - 'null'
        relation:
          type:
          - string
          - 'null'
        method:
          type:
          - string
          - 'null'
          default: GET
      additionalProperties: false
    FolderListingPagedCollection:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        href:
          type:
          - string
          - 'null'
        relation:
          type:
          - string
          - 'null'
        method:
          type:
          - string
          - 'null'
          default: GET
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
        value:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/FolderListing'
        offset:
          type:
          - integer
          - 'null'
          format: int32
        limit:
          type:
          - integer
          - 'null'
          format: int32
        size:
          type: integer
          format: int64
        first:
          allOf:
          - $ref: '#/components/schemas/Link'
        previous:
          allOf:
          - $ref: '#/components/schemas/Link'
        next:
          allOf:
          - $ref: '#/components/schemas/Link'
        last:
          allOf:
          - $ref: '#/components/schemas/Link'
        parentId:
          type:
          - string
          - 'null'
          description: Unique identifier of the parent folder
          example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
        name:
          type:
          - string
          - 'null'
          description: Name of the folder
          example: Property Documents
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
      additionalProperties: {}
    Folder:
      type: object
      properties:
        href:
          type:
          - string
          - 'null'
        relation:
          type:
          - string
          - 'null'
        method:
          type:
          - string
          - 'null'
          default: GET
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
        id:
          type:
          - string
          - 'null'
          description: Unique identifier of the folder
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        parentId:
          type:
          - string
          - 'null'
          description: Unique identifier of the parent folder
          example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
        name:
          type:
          - string
          - 'null'
          description: Name of the folder
          example: Property Documents
      additionalProperties: false
    FolderPathSegment:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique identifier of the folder
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        name:
          type:
          - string
          - 'null'
          description: Name of the folder
          example: Property Documents
        parentId:
          type:
          - string
          - 'null'
          description: Unique identifier of the parent folder
          example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
        depth:
          type: integer
          description: 'The depth of the folder in the folder path hierarchy.


            0 indicates the root folder, 1 indicates a direct child of that folder, and so on.'
          format: int32
          example: 2
      additionalProperties: false
    FolderPathSegmentCollection:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
        href:
          type:
          - string
          - 'null'
        relation:
          type:
          - string
          - 'null'
        method:
          type:
          - string
          - 'null'
          default: GET
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
        value:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/FolderPathSegment'
      additionalProperties: false
  securitySchemes:
    api-key:
      type: apiKey
      name: x-api-key
      in: header
    token:
      type: apiKey
      name: Authorization
      in: header
      x-amazon-apigateway-authtype: cognito_user_pools