Smokeball Files API

openapi: 3.2.0
info:
  title: Smokeball Activity Codes Files 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: Files
paths:
  /matters/{matterId}/documents/files:
    get:
      tags:
      - Files
      summary: Get files on a matter
      description: "Returns a list of files associated with a matter. \nDefaults to ascending order of date created, i.e. oldest first, unless sort option is supplied.\nCustom sorting and searching options does not apply to cursor-based pagination."
      operationId: GetFiles
      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
      - name: Cursor
        in: query
        schema:
          type: string
      - name: Sort
        in: query
        description: ' Available fields: dateCreated'
        schema:
          type: string
      - name: Search
        in: query
        description: ' Available fields: query, fileExtension'
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: When request is successful. Returns a paged collection of 'File' objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilePagedCollection'
        '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:
      - Files
      summary: Add file to a matter
      description: Uploads a new file for the specified matter.
      operationId: AddFile
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AddFileDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AddFileDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AddFileDto'
        required: true
      responses:
        '202':
          description: When request is accepted. Returns an 'UploadFileInfo' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadFileInfo'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /matters/{matterId}/documents/files/{fileId}:
    get:
      tags:
      - Files
      summary: Get a file
      description: Retrieves a specified file.
      operationId: GetFileById
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: When request is successful. Returns a 'File' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        '403':
          description: When the requested file does not belong to the account making the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When file with the specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      tags:
      - Files
      summary: Upload/update version or metadata of a file
      description: Updates the metadata for a file or uploads a new version of the file
      operationId: UpdateFile
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      - name: fileId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/EditFileDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/EditFileDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/EditFileDto'
        required: true
      responses:
        '202':
          description: When request is accepted. Returns an 'UploadFileInfo' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadFileInfo'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When file or matter with the specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    patch:
      tags:
      - Files
      summary: Patch a file
      description: Updates the metadata for a file or uploads a new version of the file
      operationId: PatchFile
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      - name: fileId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/EditFileDto'
          application/json:
            schema:
              $ref: '#/components/schemas/EditFileDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/EditFileDto'
      responses:
        '202':
          description: When request is accepted. Returns an 'UploadFileInfo' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadFileInfo'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When file or matter with the specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
      - Files
      summary: Delete a file
      description: Deletes a specified matter file.
      operationId: DeleteFile
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: fileId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: When request is accepted. Returns a 'Link' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When the requested file does not belong to the account making the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /matters/{matterId}/documents/files/{fileId}/download:
    get:
      tags:
      - Files
      summary: Get download url for a file
      description: Retrieves download details for a specified matter file.
      operationId: DownloadFile
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      - name: fileId
        in: path
        required: true
        schema:
          type: string
      - name: versionId
        in: query
        schema:
          type: string
      responses:
        '200':
          description: When request is successful. Returns a 'DownloadFileInfo' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadFileInfo'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When the requested file does not belong to the account making the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When file or matter with the specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /matters/{matterId}/documents/files/{fileId}/upload:
    get:
      tags:
      - Files
      summary: Get upload url for a file
      description: Retrieves upload details for a specified matter file.
      operationId: UploadFile
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      - name: fileId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: When request is successful. Returns an 'UploadFileInfo' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadFileInfo'
        '403':
          description: When the requested file does not belong to the account making the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When file or matter with the specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /matters/{matterId}/documents/files/{fileId}/history:
    get:
      tags:
      - Files
      summary: Get file history on a matter
      description: Returns a list of history entries for the specified file
      operationId: GetFileHistory
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      - name: fileId
        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'
  /matters/{matterId}/documents/files/bulk:
    post:
      tags:
      - Files
      summary: Add files to a matter
      description: Uploads a batch of files for the specified matter. Used for data migrations.
      operationId: BulkAddFiles
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AddFileDto'
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AddFileDto'
          application/*+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AddFileDto'
        required: true
      responses:
        '202':
          description: When request is accepted. Returns an array of 'UploadFileInfo' objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UploadFileInfo'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /matters/{matterId}/documents/files/{fileId}/preview:
    get:
      tags:
      - Files
      summary: Get preview info for a file
      description: Returns info to preview a file.
      operationId: GetPreview
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      - name: fileId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: When request is successful. Returns a 'PreviewFileInfo' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewFileInfo'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When the file is not associated with the authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When the file name does not exist or isn't uploaded yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    post:
      tags:
      - Files
      summary: Create a preview request
      description: Creates a preview for the specified file.
      operationId: CreatePreview
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      - name: fileId
        in: path
        required: true
        schema:
          type: string
      responses:
        '202':
          description: When request is accepted. Returns a 'PreviewFileInfo' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewFileInfo'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When the file is not associated with the authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When the file name does not exist or isn't uploaded yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /matters/{matterId}/documents/files/{fileId}/preview/{documentVersionId}:
    get:
      tags:
      - Files
      summary: Get preview info for a file by document version
      description: Returns info to preview a file by document version.
      operationId: GetPreviewById
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
      - name: fileId
        in: path
        required: true
        schema:
          type: string
      - name: documentVersionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: When request is successful. Returns a 'PreviewFileInfo' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewFileInfo'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When the file is not associated with the authenticated client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When the file name does not exist or isn't uploaded yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    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.).
    EditFileDto:
      required:
      - fileName
      type: object
      properties:
        fileName:
          maxLength: 256
          minLength: 0
          type: string
          description: Full name of the file including the file extension
          example: court filing.pdf
        folderId:
          type:
          - string
          - 'null'
          description: Unique identifier of the folder to add the file to. If null it will be placed in the root folder
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        userId:
          type:
          - string
          - 'null'
          description: Unique identifier of the user modifying the file. If null it will fallback to the authenticated user
          example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
        fileAdditionalData:
          type:
          - object
          - 'null'
          additionalProperties: {}
          description: Collection of KeyValuePair(string, string) to update File meta data.
        isFavorite:
          type:
          - boolean
          - 'null'
          description: Flag indicating whether this file is a favorite. If null it will be ignored
      additionalProperties: false
    AddFileDto:
      required:
      - fileName
      type: object
      properties:
        fileName:
          maxLength: 256
          minLength: 0
          type: string
          description: Full name of the file including the file extension
          example: court filing.pdf
        folderId:
          type:
          - string
          - 'null'
          description: Unique identifier of the folder to add the file to. If null it will be placed in the root folder
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        userId:
          type:
          - string
          - 'null'
          description: Unique identifier of the file owner. If null it will fallback to the authenticated user
          example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
        folderPath:
          type:
          - string
          - 'null'
          description: Path of the folder to add the file to. If null then the FolderId will be used
          example: Court Filings/2023/January
        fileAdditionalData:
          type:
          - object
          - 'null'
          additionalProperties: {}
          description: Collection of KeyValuePair(string, string) to update File meta data.
        dateCreated:
          type:
          - string
          - 'null'
          description: The original datetime that the file was created. If null the current datetime will be used
          format: date-time
          example: '2023-04-23T14:00:00Z'
        dateModified:
          type:
          - string
          - 'null'
          description: The initial datetime that the file was last modified. If null the current datetime will be used
          format: date-time
          example: '2023-04-24T14:00:00Z'
      additionalProperties: false
    FilePagedCollection:
      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/File'
        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'
      additionalProperties: false
    DownloadFileInfo:
      type: object
      properties:
        fileId:
          type:
          - string
          - 'null'
          description: Unique identifier of the requested file
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        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
        downloadUrl:
          type:
          - string
          - 'null'
          description: Temporary Link to download file
          example: ''
        expiry:
          type: string
          description: Expiry date/time when the download link is no longer accessible
          format: date-time
          example: '2022-04-23T14:30:00Z'
        sizeBytes:
          type: integer
          description: Size of the requested file (in bytes)
          format: int64
          example: 19104768
      additionalProperties: false
    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
    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
    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: {}
    PreviewFileInfo:
      type: object
      properties:
        fileId:
          type:
          - string
          - 'null'
          description: Unique identifier of the requested file
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        documentVersionId:
          type:
          - string
          - 'null'
        downloadUrl:
          type:
          - string
          - 'null'
          description: Temporary Link to download file
          example: ''
        expiry:
          type:
          - string
          - 'null'
          description: Expiry date/time when the download link is no longer accessible
          format: date-time
      

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smokeball/refs/heads/main/openapi/smokeball-files-api-openapi.yml