Files

We'll assume you've already got the API authentication settled and you have our API token with you.

List files in your account #

By making GET request to the /api/files endpoint, you can list all uploaded and secured files in your account.

curl https://privasfer.com/api/files \
    -H 'Authorization: Bearer 7xcB5XlinBWGzajPdSW7bHr12erWZICIJN4jk0RpasoLYLpoiD6ErYnVSzld' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

As a result, you get the details for every file you've uploaded.

{
    "data": [
        {
            "id": "fad2027a-ac89-4ef4-baab-95b2fb316cf1",
            "filename": "invoice",
            "type": "application/pdf",
            "extension": "pdf",
            "full_filename": "invoice.pdf",
            "size": 43389,
            "formatted_size": "42.37 KB",
            "encrypted_size": 78508,
            "formatted_encrypted_size": "76.67 KB",
            "created_by": {
                "name": "Author Name",
                "initials": "Author N.",
                "email": "[email protected]",
                "photo_url": "https://www.privasfer.com/storage/profiles/Qj1lOxYuBE23taYibnRE3N0MnvwM5mreEQ1Q6Zaq.png",
                "timezone": "Europe/Vilnius"
            },
            "created_at": "2019-05-08 00:18:03",
            "disk": "local-spaces",
            "trashed": false
        }

        // ...
    ]
}

Read more about returned properties here.

Extra parameters #

name	value	description
include	category	Include category object. Example: `/api/files?include=category`
sort	filename_original, size, encrypted_size, created_at	Include category object. Example: `/api/files?sort=size to make reverse sorting use negative value /api/files?sort=-size`
keyword	search keyword	Perform search in filename field by given value. Example: `/api/files?keyword=test`

Get a specific file via the API #

If you want get specific file, you can specify file ID in endpoint. The example below will get the details of file ID fad2027a-ac89-4ef4-baab-95b2fb316cf1.

curl https://privasfer.com/api/files/fad2027a-ac89-4ef4-baab-95b2fb316cf1 \
    -H 'Authorization: Bearer 7xcB5XlinBWGzajPdSW7bHr12erWZICIJN4jk0RpasoLYLpoiD6ErYnVSzld' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Single file payload.

{
    "data": {
            "id": "fad2027a-ac89-4ef4-baab-95b2fb316cf1",
            "filename": "invoice",
            "type": "application/pdf",
            "extension": "pdf",
            "full_filename": "invoice.pdf",
            "size": 43389,
            "formatted_size": "42.37 KB",
            "encrypted_size": 78508,
            "formatted_encrypted_size": "76.67 KB",
            "created_by": {
                "name": "Author Name",
                "initials": "Author N.",
                "email": "[email protected]",
                "photo_url": "https://www.privasfer.com/storage/profiles/Qj1lOxYuBE23taYibnRE3N0MnvwM5mreEQ1Q6Zaq.png",
                "timezone": "Europe/Vilnius"
            },
            "created_at": "2019-05-08 00:18:03",
            "disk": "local-spaces",
            "trashed": false
        }
}

Return properties #

id: an internal identifier.
filename: file name without extension.
type: file mime type.
extension: file extension.
full_filename: file name with extension.
size: file size in bytes.
formatted_size: human readable file size.
encrypted_size: encrypted file size in bytes(encrypted files usually weight about 50% more than original file).
formatted_encrypted_size: human readable encrypted file size.
created_by: author details. More about user details object you can read here.
created_at: date ant time when file was uploaded. Time is formatted to your time zone(time zone can be changed in you settings).
disk: file storage name. More about disks you can read here.
trashed: determine if file trashed or not. After deleting file, only file itself is deleted from storage, but record in database is stored for one more month with parameter trashed: true

Add(upload) file via the API #

To add a file, make a POST request to the /api/files endpoint. Here's an example.

curl -X POST https://privasfer.com/api/files \
    -H 'Authorization: Bearer 7xcB5XlinBWGzajPdSW7bHr12erWZICIJN4jk0RpasoLYLpoiD6ErYnVSzld' \
    -H 'Accept: application/json' \
    -F 'file=@/path/to/file'

Form fields #

name	description	type
file	The file you want to upload	file

When submitting file over CURL you should use -F(form data) option and specify path to file. You can upload only one file per request.

If the API call succeeded, you'll be given output like this.

{
    "data": {
            "id": "fad2027a-ac89-4ef4-baab-95b2fb316cf1",
            "filename": "invoice",
            "type": "application/pdf",
            "extension": "pdf",
            "full_filename": "invoice.pdf",
            "size": 43389,
            "formatted_size": "42.37 KB",
            "encrypted_size": 78508,
            "formatted_encrypted_size": "76.67 KB",
            "category": {
                "id": "05089389-8986-452b-b16d-b5615e285ba3",
                "name": "Uploads",
                "created_at": "2019-05-07 21:03:07"
            },
            "created_by": {
                "name": "Author Name",
                "initials": "Author N.",
                "email": "[email protected]",
                "photo_url": "https://www.privasfer.com/storage/profiles/Qj1lOxYuBE23taYibnRE3N0MnvwM5mreEQ1Q6Zaq.png",
                "timezone": "Europe/Vilnius"
            },
            "created_at": "2019-05-08 00:18:03",
            "disk": "local-spaces",
            "trashed": false
        },
    "success": true
}

As you can see, there is a new parameter called category. At the moment we do not support files categorization, but we still working hard to fully implement and test this feature. For now there is only one category Uploads and all files will be automatically attached to this category.

Error handling #

If an error occurred, you'll be given a non-HTTP/200 response code. The resulting payload might look like this.

{
      "message": "The given data was invalid.",
      "errors": {
                "file": [
                        "The file field is required."
                ]
        }
}

Deleting a file #

Use the DELETE request to delete a file through the API. In this example, we'll delete a file with ID fad2027a-ac89-4ef4-baab-95b2fb316cf1.

curl -X DELETE https://privasfer.com/api/files/fad2027a-ac89-4ef4-baab-95b2fb316cf1 \
    -H 'Authorization: Bearer 7xcB5XlinBWGzajPdSW7bHr12erWZICIJN4jk0RpasoLYLpoiD6ErYnVSzld' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

After successful delete request you will receive a 204 HTTP status.