API: Files

API v6

Sections: List files | Show a file | Update the notes of a file | Max upload file size | Uploads folder information | Upload a file | Download a file | Delete a file

See also: Files in passwords and projects

Note: the methods described in this document work with files in passwords, personal passwords and projects.

List files

You can list the files of a password or a project. See the following links in the corresponding sections of the passwords and projects API documents to learn how to do it:

List files of a password
List files of a personal password
List files of a project

Show a file

This method returns all the data of a file, identified by its internal id. You get this id by listing files with the API (see the List files methods or, in the UI, by clicking the "Info" button on the list of files of a password or project.

GET /files/ID.json

If successful, the response code is 200 OK with the results of the call in the response body.

Example response body:

{
    "id": 3,
    "name": "server_specs.pdf",
    "container": {
        "type": "password",
        "id": 68,
        "is_linked": false,
        "source_id": 0
    },
    "notes": "Definitive VPS server specs",
    "size_bytes": 70337,
    "size_txt": "68.69 kb",
    "uploaded_on": "2024-12-18 06:46:00",
    "uploaded_by": {
        "id": 1,
        "username": "john",
        "email_address": "john@teampasswordmanager.com",
        "name": "John Boss",
        "role": "Admin"
    },
    "notes_updated_on": "2024-12-18 07:13:51",
    "notes_updated_by": {
        "id": 1,
        "username": "john",
        "email_address": "john@teampasswordmanager.com",
        "name": "John Boss",
        "role": "Admin"
    }
}

Notes:

• container is the password, personal password or project where the file is stored in. So, container.type can be "password", "my_password" or "project", with its id in container.id. If the container is a linked password, then container.is_linked is true, and the source password id in container.source_id.
• To view the data for a file of a locked password, the X-Unlock-Reason header must be supplied with a reason. When a file in a locked password is accessed with the X-Unlock-Reason, a notification will be sent to the password manager with the supplied reason. Note that locked passwords that require permission to be unlocked cannot be used with the API, and if in this case and the X-Unlock-Reason header is provided a "409 Conflict" error will be returned.

Metadata only

The show a file request can include the following header: X-Metadata-Only: true. When this header is used, the response will only include the metadata fields of the file. For example:

{
    "id": 3,
    "uploaded_by": {
        "id": 1
    },
    "uploaded_on": "2024-12-18 06:46:00",
    "notes_updated_by": {
        "id": 1
    },
    "notes_updated_on": "2024-12-18 07:13:51"
}

Update the notes of a file

This method updates the notes of a file, identified by its internal id.

PUT /files/ID.json

The request body must include the notes for the file:

{
  "notes": "Some notes"
}

If successful, the response code is 204 No content and the response body is empty.

Notes:

• To delete the notes in a file, simply send an empty string in the notes field of the request body: { "notes": "" }
• To update a file in a locked password, the X-Unlock-Reason header must be supplied with a reason, otherwise the response code 403 Forbidden will be returned. When a locked password is accessed with the X-Unlock-Reason, a notification will be sent to the password manager with the supplied reason. Note that locked passwords that require permission to be unlocked cannot be used with the API, and if in this case and the X-Unlock-Reason header is provided a "409 Conflict" error will be returned.
• Files in Linked passwords cannot be updated (they're read only). If you try to update the notes of a file in linked password you'll get a 403 Forbidden response.

Max upload file size

This method returns the maximum size allowed for uploaded files.

GET /files/max_upload_file_size.json

Example response body:

{
  "max_upload_file_size_bytes": 335544320,
  "max_upload_file_size_text": "320Mb"
}

See also: Admin stuff: how to change the maximum file size

Uploads folder information

This method returns information about the uploads folder, specially if it's writable. If the uploads folder is not writable it's not possible to upload files.

GET /files/uploads_folder_info.json

Example response body:

{
  "uploads_folder": "./uploads/",
  "writable": true
}

See also: Admin stuff: the uploads folder

Upload a file

You can upload a file to a password or a project. See the following links in the corresponding sections of the passwords and projects API documents to learn how to do it:

Upload a file to a password
Upload a file to a personal password
Upload a file to a project

Download a file

This method downloads a file, identified by its internal id.

GET /files/download/ID.json

If successful, the response code is 200 OK and the response body contains the data of the file.

Note that the requester is responsible for saving the data to disk or other media. This method just returns the data. Check the download example below to learn how to do it in PHP.

To download a file in a locked password, the X-Unlock-Reason header must be supplied with a reason, otherwise the response code 403 Forbidden will be returned. When a locked password is accessed with the X-Unlock-Reason, a notification will be sent to the password manager with the supplied reason. Note that locked passwords that require permission to be unlocked cannot be used with the API, and if in this case and the X-Unlock-Reason header is provided a "409 Conflict" error will be returned.

Download a file example in PHP

The following script shows you how to download a file using PHP. To run it, save it to a PHP file and replace the variables on top with your own values:

<?php
	// API URL
	$tpm_base_url  = 'https://YOUR_TPM_URL/index.php/api/v6';

	// User with at least Read permission on the password/project where the file is stored in
	$username = 'YOUR_TPM_USERNAME';
	$password = 'YOUR_TPM_PASSWORD';

	// File id of the file to download
	$file_id = YOUR_FILE_ID;  // For example: 390

	// File name of the file to download
	// You get it using the "Show a file" method (https://teampasswordmanager.com/docs/api-files/#show_file)
	// Here we just assign it directly to focus on the download method
	$file_name = 'YOUR_FILE_NAME'; // For example: 'server_specs.pdf'

	// Method to download
	$request_uri = '/files/download/' . $file_id . '.json';

	// Headers: JSON and UTF-8
	$headers = array(
		'Content-Type: application/json; charset=utf-8'
	);

	// GET request
	$ch = curl_init($tpm_base_url . $request_uri);
	curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
	curl_setopt($ch, CURLOPT_HEADER, TRUE); // Includes the header in the output		
	curl_setopt($ch, CURLOPT_USERPWD, $username . ":" . $password); // HTTP Basic Authentication
	curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

	// Execute
	$result = curl_exec($ch);	
	$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
	curl_close($ch);

	// Separate response headers and body
	list($headers, $body) = explode("\r\n\r\n", $result, 2);

	// Show response and save file
	// If status is 200 (OK) we save the file to disk, otherwise we output the headers and body with the error
	echo 'Status: ' . $status . '<br/>';
	if ( $status == 200 ) {
		$saved_file_bytes = file_put_contents($file_name, $body);
		echo 'Saved file bytes: ' . $saved_file_bytes;
	} else {		
		echo 'Headers: ' . $headers . '<br/>';
		echo 'Body: ' . $body;		
	}

If successful, the result should show something like this, with the YOUR_FILE_NAME file created in the same folder as the script:

Status: 200
Saved file bytes: 70337

Delete a file

This method deletes a file, identified by its internal id.

DELETE /files/ID.json

If successful, the response code is 204 No content and the response body is empty.

To delete a file in a locked password, the X-Unlock-Reason header must be supplied with a reason, otherwise the response code 403 Forbidden will be returned. When a locked password is accessed with the X-Unlock-Reason, a notification will be sent to the password manager with the supplied reason. Note that locked passwords that require permission to be unlocked cannot be used with the API, and if in this case and the X-Unlock-Reason header is provided a "409 Conflict" error will be returned.

Note: files in linked passwords cannot be deleted (they're read only). If you try to delete a file in a linked password you'll get a 403 Forbidden response.