Smokeball Folders API

openapi: 3.0.1
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.\r\n\r\nThe 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:
    FileFolderLogEntry:
      type: object
      properties:
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        id:
          type: string
          description: Unique identifier of this log entry.
          nullable: true
          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).
          nullable: true
        folder:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: Link to the folder affected by this entry (only populated when Type is Folder).
          nullable: true
        oldName:
          type: string
          description: Old name prior to a rename operation (when applicable).
          nullable: true
          example: Draft Response
        newName:
          type: string
          description: New name after a rename operation (when applicable).
          nullable: true
          example: Final Response
        oldMatterId:
          type: string
          description: Previous matter identifier (for move/copy across matters).
          nullable: true
          example: f9e1a9d5-1d2b-4bd2-9a72-6a6e7b5c2f01
        newMatterId:
          type: string
          description: New matter identifier (for move/copy across matters).
          nullable: true
          example: 1c0b8a31-0a05-4601-8b87-2d7b1d0caa9a
        oldFolderId:
          type: string
          description: Previous folder identifier (for move within/between matters).
          nullable: true
          example: 6a5c3b2e-0f1e-4c7e-90e2-2ad3c3e8b0b9
        newFolderId:
          type: string
          description: New folder identifier (for move within/between matters).
          nullable: true
          example: 9b7a2c4d-2e1f-4b6a-8e01-1f2a3b4c5d6e
        copySourceFileId:
          type: string
          description: For copy operations, the source file's identifier when copying a file.
          nullable: true
          example: bb3a6c1d-1e2f-4a7b-9c01-0d9a8c7b6e5f
        copySourceFolderId:
          type: string
          description: For copy operations, the source folder's identifier when copying a folder.
          nullable: true
          example: aa2b5c1e-7f8a-4d9e-8c01-1a2b3c4d5e6f
        documentVersionId:
          type: string
          description: "Identifier of the document version involved (only for version replace/revert scenarios).\r\nCan be used to download particular file versions."
          nullable: true
          example: 2d97e267-0618-4822-a515-281cd4f31ae8-72324ca30d263b32bb38a481cc5f7a0b
        userId:
          type: string
          description: The user who is responsible for this change.
          nullable: true
      additionalProperties: false
      description: Represents a single file/folder activity (rename, move, delete, etc.).
    FolderListingPagedCollection:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        value:
          type: array
          items:
            $ref: '#/components/schemas/FolderListing'
          nullable: true
        offset:
          type: integer
          format: int32
          nullable: true
        limit:
          type: integer
          format: int32
          nullable: true
        size:
          type: integer
          format: int64
        first:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        previous:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        next:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        last:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        parentId:
          type: string
          description: Unique identifier of the parent folder
          nullable: true
          example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
        name:
          type: string
          description: Name of the folder
          nullable: true
          example: Property Documents
      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
          description: Unique identifier of the parent folder
          nullable: true
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        userId:
          type: string
          description: Unique identifier of the user modifying the folder. If null it will fallback to the authenticated user
          nullable: true
          example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
      additionalProperties: false
    FileFolderLogEntryCollection:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        value:
          type: array
          items:
            $ref: '#/components/schemas/FileFolderLogEntry'
          nullable: true
      additionalProperties: false
    Link:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
      additionalProperties: false
    FolderPathSegment:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the folder
          nullable: true
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        name:
          type: string
          description: Name of the folder
          nullable: true
          example: Property Documents
        parentId:
          type: string
          description: Unique identifier of the parent folder
          nullable: true
          example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
        depth:
          type: integer
          description: "The depth of the folder in the folder path hierarchy.\r\n\r\n0 indicates the root folder, 1 indicates a direct child of that folder, and so on."
          format: int32
          example: 2
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    FolderPathSegmentCollection:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        value:
          type: array
          items:
            $ref: '#/components/schemas/FolderPathSegment'
          nullable: true
      additionalProperties: false
    Folder:
      type: object
      properties:
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        id:
          type: string
          description: Unique identifier of the folder
          nullable: true
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        parentId:
          type: string
          description: Unique identifier of the parent folder
          nullable: true
          example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
        name:
          type: string
          description: Name of the folder
          nullable: true
          example: Property Documents
      additionalProperties: false
    FolderListing:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        folders:
          type: array
          items:
            $ref: '#/components/schemas/Folder'
          description: List of folders
          nullable: true
          readOnly: true
        files:
          type: array
          items:
            $ref: '#/components/schemas/File'
          description: List of files
          nullable: true
          readOnly: true
      additionalProperties: false
    File:
      type: object
      properties:
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        id:
          type: string
          description: Unique identifier of the file.
          nullable: true
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        versionId:
          type: string
          description: Unique identifier of the file's current version.
          nullable: true
        folder:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: Hypermedia link of the folder to which the file belongs.
          nullable: true
        matter:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: Hypermedia link of the matter to which the file belongs.
          nullable: true
        name:
          type: string
          description: Name of the file, excluding file extension.
          nullable: true
          example: court filing
        fileExtension:
          type: string
          description: Extension of the file.
          nullable: true
          example: .pdf
        ownerId:
          type: string
          description: Unique identifier of the user who created/uploaded this file.
          nullable: true
          example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
        to:
          type: string
          description: The 'To' or recipients' email address (only applicable for email files).
          nullable: true
          example: recipient@email.com
        from:
          type: string
          description: The 'From' or sender's email address (only applicable for email files).
          nullable: true
          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.
          nullable: true
        additionalData:
          type: object
          additionalProperties:
            nullable: true
          description: Collection of file meta data as KeyValuePair(string, object).
          nullable: true
        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
  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