API Reference - Files

 

Listing Files

Returns a collection of file records, optionally filtered by the available request parameters.

GET /api/v1/files

 

Available Request Parameters:

Name	Type	Required	Description
id	integer	no	ID of the file.
name	string	no	Name of the file (as stored in Trackops).
filename	integer	no	Raw file name, with extension (as stored in Trackops).
case	integer	no	ID of the case connected to this file.
mime_type	string	no	The mime type associated with this file (e.g. application/pdf).
created_by	integer	no	ID of the user who created the file or folder.
created_from	timestamp	no	Created on or after the date, as determined by the system.
created_to	timestamp	no	Created on or before the date, as determined by the system.
updated_from	timestamp	no	Updated on or after the date, as determined by the system.
updated_to	timestamp	no	Updated on or before the date, as determined by the system.

Note: All timestamp parameters are queried and returned in UTC.

A Note about File URLs

When retrieving a file list, it will include a secure expiring URL to download each file.  It is important to note that these URLs are only valid for 15 minutes, so if you do not use the link within this time frame, you must re-query the API to get new URLs.  Because of this, you may want to consider reducing the per_page query parameter so you have ample time to handle the requested files without hitting the URL expiration.

 

Getting a File

Returns a single file record, based on the numeric ID.

GET /api/v1/files/{file_id}

 

Uploading a New File

Uploading a new file to Trackops consists of three steps:

1. Obtain a new upload URL
2. Use the URL to upload (PUT) a binary file to Trackops
3. Process the newly uploaded file

1. Obtaining an Upload URL

Generates a new pre-signed upload URL, that can be used to upload a file into the system.  The upload URL will expire 30 minutes after it has been generated.  Include the filename of the file to upload using the filename parameter.

GET /api/v1/cases/{case_id}/upload_url?filename={filename.ext}

{
  url: "upload URL will be included here"
}

2. Uploading a File to the Upload URL

Using the upload URL generated in step 1, upload (PUT) a binary file into the system.  Ensure the Content-Type header is included as application/octet-stream as shown in the example below.

PUT {upload_url}

Example Uploading URL using cURL

curl --request PUT -H "Content-Type:application/octet-stream" --data-binary "@filename.ext" "{upload_url}"

3. Processing the Uploaded File

Processes the uploaded file into the system.

POST /api/v1/cases/{case_id}/process_upload

Available Parameters:

Name	Type	Required	Description
filename	string	yes	The name of the file as stored on disk, including the file extension.
access_group_id	integer	yes	The ID of the access group associated with this file. See Access Groups.
is_valid	boolean	no	Determines if the file should be valid upon upload. In most cases, you'll set this value to be true.
notes	string	no	Text that goes along with this file upload.

{
  upload: {
    "filename": "filename.ext",
    "access_group_id": 1,
    "is_valid": true,
    "notes": "Uploaded via the API"
  }
}