Upload File

This request uploads a file to the specified container.

post	/storage/files

Samples

A sample POST request to upload a file to a container using the multipart/form-data content type:

curl -X POST \
'https://api.carrierx.com/core/v2/storage/files' \
-H 'Content-Type: multipart/form-data' \
-F 'file_object={"container_sid":"cb05c1f4-2398-432c-8314-cc306156281c"}' \
-F 'data=@my_audio.mp3' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A sample POST request to upload a file to a container using the application/octet-stream content type:

curl -X POST \
'https://api.carrierx.com/core/v2/storage/files?container_sid=cb05c1f4-2398-432c-8314-cc306156281c&name=my_audio.mp3' \
-H 'Content-Type: application/octet-stream' \
--data-binary '@my_audio.mp3' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

201 status code with a serialized copy of the 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
}

Required Scopes

To create a File object, the partner must have one of the following scopes enabled:

• storage.manage
• storage.create

note

You can upload files to the container using either the multipart/form-data or application/octet-stream content types. Depending on the selected content type, the required parameters and the POST request will look different. Refer to our How It Works: Storing Filex with CarrierX section for more details on this.

Query Arguments

Parameter	Data Type	Description
conflict_action	string	Action in the case you try to upload a file with the unique field set to true, and a file with the same attributes already exists and conflicts with the one being uploaded. Values accepted in this field are: error to throw an error and abort the file upload. overwrite to overwrite the old file with the new one. overwrite_empty to overwrite the old file with the new one only in the case the old file has 0 bytes length. The argument is used for file uploads with both the multipart/form-data and application/octet-stream content types. The default value is error.
container_sid	string	The secure ID of the container where the file will be uploaded. Required if you upload the file using the application/octet-stream content type, and not used with the multipart/form-data content type.

Form Arguments

The form arguments are only used when you upload the file using the multipart/form-data content type.

Parameter	Data Type	Description
data required	file path	The path of the file to be uploaded.
file_object required	object	The fields and values of the file to be uploaded. You need to specify at least the container_sid attribute of the File object to successfully upload it. Refer to this table to view all fields that appear in the File object.

Body Arguments

The body arguments are only used when you upload the file using the application/octet-stream content type.

Parameter	Data Type	Description
file required	file path	The path of the file to be uploaded.

Response

If the request is successful, a 201 response code will be returned with a serialized copy of the File object.

Otherwise, if an error occurs, the system will return one of the HTTP errors used with CarrierX system.

File Object Specific Errors

Unique File Error

If you try to upload a file with the unique attribute set to true and the file key set (integer_key_1, integer_key_2, string_key_1, string_key_2, string_key_3, and string_key_4), which has already been used with some other file, a 422 (object validation error) error will be returned. It has the following structure:

Response Field	Data Type	Description
field	string	The field that caused the error.
message	string	The detailed error description.
reference_sid	string	The secure ID of the file, which has the same set of unique keys.

• If the query conflict_action argument is set to overwrite_empty, the returned error field value will be set to conflict_action, and the message value will be set to overwrite_empty cannot be applied because container has non-empty files, indicating that you try to overwrite an existing non-empty unique file with new data.

• If the query conflict_action argument is set to error, the returned error field value will be set to unique, and the message value will be set to file with the same set of keys already exists, indicating that you try to overwrite an existing unique file with the same file key set.

Unique File Error Samples

A sample overwrite_empty cannot be applied because container has non-empty files error:

{
    "message": "object validation error",
    "errors": [
        {
            "field": "conflict_action",
            "message": "overwrite_empty cannot be applied because container has non-empty files",
            "reference_sid": "c1d71642-643d-4f56-89f6-3bef3f5e22e7"
        }
    ]
}

A sample file with the same set of keys already exists error:

{
    "message":"object validation error",
    "errors":[
        {
            "field":"unique",
            "message":"file with the same set of keys already exists",
            "reference_sid":"f6070be2-9abd-4726-870c-c86c9aac5c7e"
        }
    ]
}

To avoid this error, you can:

• change the query conflict_action argument to overwrite;
• change the unique field for the file to be uploaded to false;
• change the key set for the file to be uploaded, so that the uploaded file was different from the existing one.

File Classifications Error

If you try and upload a file that has the content_classification value equal to one of the blocked_classifications values of the parent Container object, it will produce the 422 error and the file will not be uploaded. The same result will be if the file classification is not in the list of the Container object allowed_classifications attribute (if the allowed_classifications value is equal to anything but null).

A sample blocked content classification error:

{
    "message": "object validation error",
    "errors": [
        {
            "field": null,
            "message": "Content data type \"document\" is restricted",
            "reference_sid": null
        }
    ]
}

To avoid this error, you can:

• upload another file which is not in the container blocked classifications list;
• update the container allowed_classifications or blocked_classifications attributes to allow the classification for the file you want to upload.