Smokeball Files API

openapi: 3.0.1
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. \r\nDefaults to ascending order of date created, i.e. oldest first, unless sort option is supplied.\r\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
          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.).
    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
          description: Unique identifier of the folder to add the file to. If null it will be placed in the root folder
          nullable: true
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        userId:
          type: string
          description: Unique identifier of the file owner. If null it will fallback to the authenticated user
          nullable: true
          example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
        folderPath:
          type: string
          description: Path of the folder to add the file to. If null then the FolderId will be used
          nullable: true
          example: Court Filings/2023/January
        fileAdditionalData:
          type: object
          additionalProperties:
            nullable: true
          description: Collection of KeyValuePair(string, string) to update File meta data.
          nullable: true
        dateCreated:
          type: string
          description: The original datetime that the file was created. If null the current datetime will be used
          format: date-time
          nullable: true
          example: '2023-04-23T14:00:00Z'
        dateModified:
          type: string
          description: The initial datetime that the file was last modified. If null the current datetime will be used
          format: date-time
          nullable: true
          example: '2023-04-24T14:00:00Z'
      additionalProperties: false
    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
          description: Unique identifier of the folder to add the file to. If null it will be placed in the root folder
          nullable: true
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        userId:
          type: string
          description: Unique identifier of the user modifying the file. If null it will fallback to the authenticated user
          nullable: true
          example: 750eb5c5-ac0b-7d11-4997-e0ce9d8896c8
        fileAdditionalData:
          type: object
          additionalProperties:
            nullable: true
          description: Collection of KeyValuePair(string, string) to update File meta data.
          nullable: true
        isFavorite:
          type: boolean
          description: Flag indicating whether this file is a favorite. If null it will be ignored
          nullable: true
      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
    PreviewFileInfo:
      type: object
      properties:
        fileId:
          type: string
          description: Unique identifier of the requested file
          nullable: true
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        documentVersionId:
          type: string
          nullable: true
        downloadUrl:
          type: string
          description: Temporary Link to download file
          nullable: true
          example: ''
        expiry:
          type: string
          description: Expiry date/time when the download link is no longer accessible
          format: date-time
          nullable: true
          example: '2022-04-23T14:30:00Z'
      additionalProperties: false
    UploadFileInfo:
      type: object
      properties:
        fileId:
          type: string
          description: Unique identifier of the file.
          nullable: true
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        uploadUrl:
          type: string
          description: "Temporary Link to upload file.\r\n\r\nImportant note: When uploading to this URL, set the 'Content-Type' header to an empty value.\r\n\r\nExample cURL: curl --location --request PUT 'URL_GOES_HERE' \\ --header 'Content-Type: \"\"' \\ --data '@/C:/dir/test.pdf'"
          nullable: true
          example: ''
        expiry:
          type: string
          description: Expiry date/time when the upload link is no longer accessible.
          format: date-time
          example: '2022-04-23T14:30:00Z'
      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: {}
    FilePagedCollection:
      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/File'
          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
      additionalProperties: false
    DownloadFileInfo:
      type: object
      properties:
        fileId:
          type: string
          description: Unique identifier of the requested file
          nullable: true
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        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
        downloadUrl:
          type: string
          description: Temporary Link to download file
          nullable: true
          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
          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:
         

# --- 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