File Object

This section outlines the File object.

File Object Attributes

The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Attribute	Data Type	Description
container_sid createupdate	string	The secure ID of the container which this file belongs to.
content_classification read only	string	The content classification for the uploaded files. Values accepted in this field are: archive document executable media unknown The classifications are used for the allowed_classifications and blocked_classifications values of the Container object.
content_duration read only	number	The duration of the file. This field cannot be modified.
content_format read only	string	The format of the uploaded file. This field cannot be modified.
content_transcoding_progress read only	integer	The progress of the content transcoding. This field cannot be modified.
date_last_accessed read only	string	The date and time when the file was last accessed using the Download Data by File SID method. The date is updated at most once a minute.
date_modified read only	string	The date and time when the last update of the file took place.
desired_bitrate create	integer	The desired bit rate for MP3 audio files when no transcoding is required. Values accepted in this field are: 8, 16, 24, 32, 40, 48, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320.
desired_format createupdate	string	The desired format for audio and video files. The default value is null, meaning that the file will not be transcoded to any other format. Refer to the table below for all file types supported.
file_access_name createupdate	string	The path to the file within the container. This field defaults to the file secure ID with extension, where possible.
file_bytes read only	integer	The file size, specified in bytes.
file_sid read only	string	The file secure ID.
integer_key_1 createupdate	integer	A user-defined integer key.
integer_key_2 createupdate	integer	A user-defined integer key.
lifecycle_action createupdate	string	The action to be triggered after lifecycle_ttl has elapsed. Values accepted in this field are: delete to delete the file when its lifecycle TTL comes to an end. no_action to do nothing with the file after its lifecycle TTL elapses. The default value is no_action and can be set using the default_file_lifecycle_action attribute of the Container object.
lifecycle_ttl createupdate	integer	How long in seconds before the lifecycle_action will be triggered. The default value is -1 (or indefinite) and can be set using the default_file_lifecycle_ttl attribute of the Container object.
mime_type createupdate	string	The content type of the file.
name createupdate	string	The file name.
parent_file_sid createupdate	string	The parent file secure ID. Setting a parent_file_sid forms a folder-like structure. Files can have a parent_file_sid and this will organize them in groups. If this field is set, and the parent_file_sid no longer exists, files associated with this folder-like structure will be deleted.
partner_sid read only	string	The secure ID of the partner the file belongs to.
publish createupdate	string	Whether to publicly serve a file, and how to store it. Values accepted in this field are: file_access_name to serve the URL in the following manner: /c/{container_sid}/{file_access_name} file_sid to serve the URL in the following manner: /f/{file_sid} no to not serve the URL via public HTTP. The default value is file_sid and can be set using the default_file_publish attribute of the Container object.
publish_uri read only	string	The web accessible URI where the file can be retrieved. This value is only applicable if publish is set to either file_access_name or file_sid.
string_key_1 createupdate	string	A user-defined string key.
string_key_2 createupdate	string	A user-defined string key.
string_key_3 createupdate	string	A user-defined string key.
string_key_4 createupdate	string	A user-defined string key.
threshold_include createupdate	boolean	Whether the file is taken into account when calculating the threshold_total_bytes, threshold_total_files, threshold_available_files_percent, and threshold_available_bytes_percent attributes of the Container object, and participates in the storage cleanup jobs. The default value is true and can be set using the default_file_threshold_include attribute of the Container object.
type create	string	The type of the file. Values accepted in this field are: file is the default value. audio verifies the file type, adds appropriate fields, and allows the ability to transcode to another audio format. video verifies the file type, and acts similarly to the audio type. conference is less commonly used. The default value is file.
unique create	boolean	Whether or not the file key set (integer_key_1, integer_key_2, string_key_1, string_key_2, string_key_3, and string_key_4) must be unique. If you create a file with the unique attribute set to true, other unique files (that also have unique set to true) with the same file key set will not be created. Please set this field when the File object is initially created to avoid errors. The default value for this field is false and can be set using the default_file_unique attribute of the Container object.

Sample File Object

{
    "container_sid": "cb05c1f4-2398-432c-8314-cc306156281c",
    "content_classification": "unknown",
    "content_duration": null,
    "content_format": "mp3",
    "content_transcoding_progress": null,
    "date_last_accessed": "2024-07-28T09:02:11.208Z",
    "date_modified": "2022-01-22T18:13:30.900Z",
    "desired_bitrate": null,
    "desired_format": null,
    "file_access_name": "f6070be2-9abd-4726-870c-c86c9aac5c7e.mp3",
    "file_bytes": 29799,
    "file_sid": "f6070be2-9abd-4726-870c-c86c9aac5c7e",
    "integer_key_1": null,
    "integer_key_2": null,
    "lifecycle_action": "no_action",
    "lifecycle_ttl": -1,
    "mime_type": "audio/mpeg",
    "name": "my_audio.mp3",
    "parent_file_sid": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "publish": "file_sid",
    "publish_uri": "http://storage-carrierx.com/f/f6070be2-9abd-4726-870c-c86c9aac5c7e",
    "string_key_1": null,
    "string_key_2": null,
    "string_key_3": null,
    "string_key_4": null,
    "threshold_include": true,
    "type": "file",
    "unique": false
}

desired_format

The following table outlines the capabilities attached to each file format. The Duration Detection column will be marked yes if the file format will detect the duration of the file.

Transcode from Codec will be marked yes if files can be transcoded from this file format.

Transcode to Codec will be marked yes if files can be transcoded to this file format.

EXAMPLE

For example, files can be transcoded from wav to mp3 because the former can be transcoded from and the latter can be transcoded to.

Format	Duration Detection	Transcode from Codec	Transcode to Codec
al, alaw	yes	yes	yes
flac	yes	yes	yes
g722	yes	yes	yes
m4a	yes	yes	yes
mp3	yes	yes	yes
mp4	yes	no	yes
ogg	yes	yes	yes
ul, ulaw	yes	yes	yes
wav	yes	yes	yes