SMsmokeball
Files

Upload/update version or metadata of a file

Changed on

Replaces all editable fields of a file with the supplied values. Use PATCH to change only some fields.

Because this is a full replace, omitting 'folderId' (or setting it to null) moves the file to the root folder. The destination folder is not validated for existence. 'fileName' is required (maximum 256 characters). 'userId' falls back to the authenticated user when omitted. Additional data values are merged with existing keys; null or empty additional data is a no-op. 'isFavorite' is ignored when null.

The response always includes a presigned PUT URL (valid for 1 hour) that can optionally be used to upload a new version of the file. Every call records a new upload request whether or not the URL is used.

put/matters/{matterId}/documents/files/{fileId}

Request

  • Base URL
    https://api.smokeball.com
  • URL
    https://api.smokeball.com/matters/{matterId}/documents/files/{fileId}
  • Auth
    API key in header x-api-key and API key in header Authorization

Path parameters

matterIdstring required

Unique identifier (GUID) of the matter.

fileIdstring required

Unique identifier (GUID) of the file.

Request body

fileNamestring required

Full name of the file. Required on PUT, maximum 256 characters. The name is normalised to XML-safe characters and must contain at least one valid character. The file's existing extension is kept unless the supplied name ends with that same extension; a trailing '.something' that differs from the current extension is treated as part of the name, so the extension cannot be changed by renaming.

folderIdstring nullable

Unique identifier (GUID) of the folder to move the file to. Null means the root folder. On PUT, omitting this property moves the file to the root folder. On PATCH, the file is moved only when '/folderId' is present in the request. The destination folder is not validated for existence.

userIdstring nullable

Unique identifier (GUID) of the user modifying the file. If null it will fallback to the authenticated user

fileAdditionalDataobject nullable

Dictionary of custom metadata to set on the file. Keys must not be blank. Values must be strings, integers, numbers, booleans or null; objects and arrays are rejected. Supplied keys are added or overwritten. Null or empty is a no-op, so existing values cannot be cleared through this property.

isFavoriteboolean nullable

Flag indicating whether this file is a favorite. If null it will be ignored

Example request

{
  "fileName": "court filing.pdf",
  "folderId": "b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2",
  "userId": "750eb5c5-ac0b-7d11-4997-e0ce9d8896c8",
  "fileAdditionalData": {
    "Author": "Jane Smith",
    "Pages": 12,
    "Signed": true
  },
  "isFavorite": true
}

Response

When request is accepted. Returns an 'UploadFileInfo' object.

fileIdstring nullable

Unique identifier of the file.

uploadUrlstring nullable

Temporary presigned URL to upload the file content to. Send the raw file bytes with an HTTP PUT request. The URL is valid for 1 hour from the time of the API call (see Expiry).

Important note: When uploading to this URL, set the 'Content-Type' header to an empty value.

Example cURL: curl --location --request PUT 'URL_GOES_HERE' \ --header 'Content-Type: ""' \ --data '@/C:/dir/test.pdf'

expirystring date-time

UTC date/time when the upload link is no longer accessible (1 hour after issue).

Example response

{
  "fileId": "b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2",
  "uploadUrl": "https://example-bucket.s3.amazonaws.com/apiuploads/2f1c9a3e-6b1d-4c7e-9a0f-1d2e3f4a5b6c?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=...",
  "expiry": "2022-04-23T14:30:00Z"
}

Changes

  • db1b8a86b58eRevision changes
    • breaking

      the response's body type changed from object to string for status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status