Files

File management collection for uploading, storing, and manipulating files within the TrackVision system.

The file Object

File collection stores metadata and access information for all uploaded files within the system.

Field Name	Type	Description
id	uuid	Primary key of the file.
storage	string	Storage adapter used for the file.
filename_disk	string	Name of the file as saved on the storage adapter.
filename_download	string	Preferred filename when file is downloaded.
title	string	Title for the file.
type	string	Mimetype of the file.
folder	object	Virtual folder the file is in. Links to Folders.
created_on	datetime	Timestamp when the file was created.
uploaded_by	object	User who uploaded the file. Links to Users.
uploaded_on	datetime	Timestamp when the file was last uploaded/replaced.
modified_by	object	User who last updated the file. Links to Users.
filesize	integer	Size of the file in bytes.
width	integer	Width in pixels if the file is an image/video. Auto-extracted for images.
height	integer	Height in pixels if the file is an image/video. Auto-extracted for images.
focal_point_x	integer	X coordinate for image cropping center point.
focal_point_y	integer	Y coordinate for image cropping center point.
duration	integer	Duration in milliseconds if the file contains audio/video. Not auto-extracted.
description	string	Description of the file.
location	string	Location information for the file.
tags	array of objects	Tags associated with the file.
metadata	object	Additional metadata scraped from the file (Exif, IPTC, ICC for images).

---

List Files

List all files that exist in TrackVision.

Request

REST

GET /files

GraphQL

POST /graphql/system

type Query {
	files: [trackvision_files]
}

Query Parameters

Supports all global query parameters.

Response

An array of up to limit file objects. If no items are available, data will be an empty array.

Example

REST

GET /files

GraphQL

query {
	files {
		id
		filename_disk
	}
}

Retrieve a File

Retrieve a single file by primary key.

Request

REST

GET /files/:id

GraphQL

POST /graphql/system

type Query {
	files_by_id(id: ID!): trackvision_files
}

Query Parameters

Supports all global query parameters.

Response

Returns a file object if a valid primary key was provided.

Example

REST

GET /files/0fca80c4-d61c-4404-9fd7-6ba86b64154d

GraphQL

POST /graphql/system

query {
	files_by_id(id: "0fca80c4-d61c-4404-9fd7-6ba86b64154d") {
		id
		filename_disk
	}
}

Upload a File

Upload a new file.

Request

REST

POST /files

Body must be formatted as a multipart/form-data with a final property called file.

GraphQL

Not supported by GraphQL

The file contents has to be provided in a property called file. All other properties of the file object can be provided as well, except filename_disk and filename_download.

Order Matters

Make sure to define the non-file properties for each file first. This ensures that the file metadata is associated with the correct file.

Query Parameters

Supports all global query parameters.

Response

Returns the file object for the uploaded file, or an array of file objects if multiple files were uploaded at once.

Example

REST

POST /files

Content-Type: multipart/form-data; boundary=boundary

--boundary
Content-Disposition: form-data; name="title"

example
--boundary
Content-Disposition: form-data; name="file"; filename="example.txt"

< ./example.txt

--boundary

GraphQL

Not supported by GraphQL

Import a File

Import a file from the web

Request

REST

POST /files/import

{
	"url": file_url,
	"data": file_object
}

GraphQL

POST /graphql/system

type Mutation {
	import_file(url: String!, data: create_trackvision_files_input!): trackvision_files
}

Query Parameters

Supports all global query parameters.

Request Body

url Required
The URL to download the file from.

data
Any of the file object's properties.

Response

Returns the file object for the imported file.

Example

REST

POST /files/import

{
	"url": "https://source.unsplash.com/random",
	"data": {
		"title": "Example"
	}
}

GraphQL

POST /graphql/system

mutation {
	import_file(url: "https://source.unsplash.com/random", data: { title: "Example" }) {
		id
	}
}

Update a File

Update an existing file, and/or replace it's file contents.

Request

REST

PATCH /files/:id

Provide a partial file object as the body of your request.

GraphQL

POST /graphql/system

type Mutation {
	update_files_item(id: ID!, data: update_trackvision_files_input!): trackvision_files
}

Query Parameters

Supports all global query parameters.

Request Body

You can either submit a JSON object consisting of a partial file object to update the file meta, or send a multipart/form-data request to replace the file contents on disk. See Upload a File for more information on the structure of this multipart/form-data request.

Response

Returns the file object for the updated file.

Example

REST

PATCH /files/0fca80c4-d61c-4404-9fd7-6ba86b64154d

{
	"title": "Example"
}

GraphQL

POST /graphql/system

mutation {
	update_files_item(id: "0fca80c4-d61c-4404-9fd7-6ba86b64154d", data: { title: "Example" }) {
		id
		title
	}
}

Update Multiple Files

Update multiple files at the same time.

Request

REST

PATCH /files

{
	"keys": file_id_array ,
	"data": partial_file_object
}

GraphQL

POST /graphql/system

type Mutation {
	update_files_items(ids: [ID!]!, data: update_trackvision_files!): [trackvision_files]
}

Query Parameters

Supports all global query parameters.

Request Body

keys Required
Array of primary keys of the files you'd like to update.

data Required
Any of the file object's properties.

Response

Returns the file objects for the updated files.

Example

REST

PATCH /files

{
	"keys": ["b6123925-2fc0-4a30-9d86-863eafc0a6e7", "d17c10aa-0bad-4864-9296-84f522c753e5"],
	"data": {
		"tags": ["cities"]
	}
}

GraphQL

POST /graphql/system

mutation {
	update_files_items(
		ids: ["b6123925-2fc0-4a30-9d86-863eafc0a6e7", "d17c10aa-0bad-4864-9296-84f522c753e5"]
		data: { tags: ["cities"] }
	)
}

Delete a File

Delete an existing file.

Destructive

This will also delete the file from disk.

Request

REST

DELETE /files/:id

GraphQL

POST /graphql/system

type Mutation {
	delete_files_item(id: ID!): delete_one
}

Query Parameters

Supports all global query parameters.

Response

Empty response.

Example

REST

DELETE /files/0fca80c4-d61c-4404-9fd7-6ba86b64154d

GraphQL

POST /graphql/system

mutation {
	delete_files_item(id: "0fca80c4-d61c-4404-9fd7-6ba86b64154d") {
		id
	}
}

Delete Multiple Files

Delete multiple files at once.

Destructive

This will also delete the files from disk.

Request

REST

DELETE /files

Provide an array of file IDs as the body of your request.

GraphQL

POST /graphql/system

type Mutation {
	delete_files_items(ids: [ID!]!): delete_many
}

Query Parameters

Supports all global query parameters.

Request Body

Array of file primary keys

Returns

Empty response.

Example

REST

DELETE /files

["d17c10aa-0bad-4864-9296-84f522c753e5", "b6123925-2fc0-4a30-9d86-863eafc0a6e7"]

GraphQL

POST /graphql/system

mutation {
	delete_files_items(ids: ["d17c10aa-0bad-4864-9296-84f522c753e5", "b6123925-2fc0-4a30-9d86-863eafc0a6e7"]) {
		ids
	}
}