Files Instance
Files
The files endpoint performs file-level operations on Plotly accounts. This includes retrieving meta information about files/folders, getting file content, permanently deleting, trashing and restoring a file, and updating writable meta information.
Reference
Authorization
Any user with or without a Plotly account may view public folders and files. For access to private folders and files, see authentication, which touches on permissions.
File Meta Information
read-only fields:
api_urls
creation_time
comments
date_modified
deleted
-adminembed_url
fid
filetype
img_url
image_urls
owner
parented
preview
references
referencers
share_key
-adminshare_key_enabled
-adminstars
collaborators
subfolder_count
title
views
web_url
current_user_permission
write-only fields:
parent_path
read-write fields:
filename
parent
share_key_enabled
-adminworld_readable
is_theme
is_template
Admin Fields
Fields marked as -admin are only readable by users with a permision
level of admin
. This permission level is currently associated with all
file owners and is not yet assignable to file collaborators.
Actions
The supported actions at the files endpoint are retrieve, content, trash,
restore, permanent_delete, update, partial update, copy, lookup and path.
The retrieve action returns generic meta information when the target is a file/folder.
The content of a file is found by adding /content
to a detail url for a file.
See content. The filename
, parent
(or parent_path
), and
world_readable
meta information fields are writable. Files can be trashed
by making a POST request to the custom /trash endpoint. See trash.
In order to trash a file, you must be an owner or a collaborator of the file's parent folder.
A trashed file can be restored by making a POST request to the custom /restore endpoint.
See restore. A file can be permanently deleted by the file owner. To do this,
the file must first be trashed via the /trash endpoint (a recoverable action) and then
permanently removed by making a DELETE request to the custom /permanent_delete endpoint.
See permanent delete. Note that once a file is permanently removed, it
can never be restored. If the file is a folder, the actions of the /trash, /restore, and
/permanent_delete endpoints will be applied recursively to all children of the
folder. Update allows for the complete replacement of the writable
meta information. Partial update allows for the replacement of targeted writable
meta information. The lookup action returns a file using its path
and parent
instead of using its fid. The path endpoint
returns a file's full path given fid.
Note that folders and your root folder (username:-1) cannot contain content. To view the files contained within these directories, use the folders endpoint.
retrieve
When accessing a detail view on any file or folder, you will receive generic file meta information about that file/folder.
Example:
// GET https://api.plotly.com/v2/files/plotlvr:9
content
The only way to download the raw content of any file is via the content resource. The Content-Type header will be appropriately set for the response body.
Example:
// GET https://api.plotly.com/v2/files/plotlvr:9/content
update
To completely replace the writable meta information of an existing file, you make a PUT request to the files endpoint and include the fid for the file.
Note, only the writable meta information may be updated. This includes filename
,
parent
or (parent_path
), and world_readable
.
Note that parent_path
may be specified in place of the parent
field.
Unlike parent
, the parent_path
field is not an integer id, but rather
the complete path of the parent folder from your root folder
(e.g., '/folder_nested_off_root/parent_folder/'
).
A successful PUT response will have a status code of 200 OK.
Example:
// PUT https://api.plotly.com/v2/files/bob:45 --> 200 OK
{
"parent": -1,
"world_readable": true,
"filename": "my_new_filename"
}
partial update
To partially update an existing file, you make a PATCH request to the files endpoint and include the fid for the file.
Note, only the writable meta information may be updated. This includes filename
,
parent
or (parent_path
), and world_readable
.
A successful PATCH response will have a status code of 200 OK.
Example:
// PATCH https://api.plotly.com/v2/files/bob:45 --> 200 OK
{
"world_readable": true,
"filename": "my_new_filename"
}
copy
To copy a file, make a POST request to the file's copy endpoint.
For plots, we will attempt a linked copy by default, where the new plot still links to the original data. If this is not possible (because the grid containing the data can't be read by you), a deep copy will be performed and a warning will be returned.
To request a deep copy, set the deep_copy attribute to true. In a deep copy, the plot's data will be copied as well and the new plot will use the new data. For grids, deep_copy is ignored.
If you want the copied file to be world readable (regardless whether or not the original file is), set the make_public attribute to true.
A successful copy response will have a status code of 200 OK. The response will contain information on each new file, as well as the fid of the main new file.
Example:
// POST https://api.plotly.com/v2/files/treebeard:25/copy --> 200 OK
{
"files": [
{ ... file data for the new file ... }
],
"new_fid": "treebeard:50",
"warnings: []
}
image
Get the most up-to-date image for a file. This currently only works for plots.
Note that this endpoint may move to https://api.plotly.com/v2/plots/<fid>/image
query_params
This endpoint has one available query_param, image_name
. It decides which
image to return for the file. The default image_name
is 'default', a png
image with dimensions set by the file's content. The options are as
follows:
default
block-thumb
list-thumb
Examples:
// GET https://api.plotly.com/v2/files/bob:45/image --> 200 OK
// GET https://api.plotly.com/v2/files/bob:45/image?image_name=block-thumb --> 200 OK
// GET https://api.plotly.com/v2/files/bob:45/image?image_name=list-thumb --> 200 OK
// GET https://api.plotly.com/v2/files/bob:45/image?image_name=does+not+exist --> 400 Bad Request
collaborators
This endpoint allows for listing(GET
), adding(POST
) and
deleting(DELETE
) of collaborators and teams.
Examples:
-
List collaborators and teams for a file:
// GET https://api.plotly.com/v2/files/bob:45/collaborators --> 200 OK [ {"username": "user1", "email": "user@example.com", "readonly": false .. }, {"type": "email", "email": "abc@example.com", "readonly": true}, {"type": "team", "name": "team_A", "readonly": true} ]
-
Add new collaborators and teams:
// POST https://api.plotly.com/v2/files/bob:45/collaborators --> 200 OK { "users": ["user1", "user2", "abc@example.com"], "teams": ["team_A", "team_B"], "send_email": true, "email_text": "This is sent as the part of invitation email." "add_to_grids": true, "readonly": true }
-
Delete collaborators and teams:
// DELETE https://api.plotly.com/v2/files/bob:45/collaborators --> 200 OK { "users": ["user1", "user2", "abc@example.com"], "teams": ["team_A", "team_B"] }
drop reference
Any file may reference another file in Plotly. Currently, we limit user-managed references to extras. Because extras may be referenced from many files, instead of deleting them to remove them, you may just dereference them. This is a safer approach and is used to manage extras in the Plotly webapp.
Example:
// POST https://api.plotly.com/v2/files/bob:45/drop_reference --> 200 OK
{
"fid": "bob:81"
}
trash
This endpoint allows for the recoverable trashing of the file specified in the endpoint detail. If the file is a folder, this endpoint will recursively trash the folder and its children.
A successful trash response will have a status code of 200 OK.
Example:
// POST https://api.plotly.com/v2/files/plotlvr:9/trash ---> 200 OK
This request is idempotent. Trashing a folder that is already trashed will also succeed and return 200 OK.
star
This endpoint allows you to star/unstar a file using its fid.
POST-ing to the url creates the star on behalf of the authenticated user,
while DELETE-ing to the url deletes the respective star.
A successful POST request returns a status code of 200 OK, while
on successful deletion, response will have a status code of 204 No Content
.
Example:
// POST https://api.plotly.com/v2/files/plotlvr:9/star ---> 200 OK
// DELETE https://api.plotly.com/v2/files/plotlvr:9/star ---> 204 No Content
Deletion is idempotent, i.e., DELETE-ing a file which is not starred by a user
will still succeed with a status code of 204 No Content
restore
This endpoint allows for a trashed file to be restored. Only the owner of the file has permission to restore that file. If the file is a folder, this endpoint will recursively restore all children of the folder from the trash.
A successful restore response will have a status code of 200.
Example:
// POST https://api.plotly.com/v2/files/my_deleted_file:9/restore ---> 200
This request is idempotent. Restoring a folder that is not yet trashed will also succeed and return 200 OK.
If restoring the file would result in a filename conflict or a subscription limit being exceeded, the restore will be unsuccessful and a status code of 409 will be returned.
Example:
// POST https://api.plotly.com/v2/files/my_conflicting_file:8/restore ---> 400
permanent_delete
This endpoint allows for the permanent deletion of the file specified in the endpoint detail. If the file is a folder, this endpoint will recursively permanently delete the folder and its children.
A successful deletion response will have a status code of 204 No Content.
Example:
// DELETE https://api.plotly.com/v2/files/plotlvr:9/permanent_delete ---> 204 No Content
lookup
Get a file using its path
and parent
instead of using its
fid. If the parent
is not specified,
it's assumed to be a user's home
folder. The path
given is assumed
to be relative to the parent
.
By default, the user
making the request is assumed to be the owner of the
file being found. However, this is controlled via the user
query param.
query params
Only the path
param is required.
- path (required) The '/'-delimited path specifying the file location.
- parent (optional) The parent id, an integer, which the path is relative to.
- user (optional) The username of the owner of the file.
- exists (optional) If
true
, don't return a file, just return whether or not the file exists.
Examples:
// GET https://api.plotly.com/v2/files/lookup?path=my_folder/my_file ---> 200 OK
// GET https://api.plotly.com/v2/files/lookup?parent=200&path=my_file ---> 200 OK
// GET https://api.plotly.com/v2/files/lookup?user=wonderwoman&path=her_folder/her_file ---> 200 OK
// GET https://api.plotly.com/v2/files/lookup?user=wonderwoman&parent=22&path=her_file ---> 200 OK
// GET https://api.plotly.com/v2/files/lookup?parent=22&path=my_file&exists=true ---> 200 OK
path
Return a file's full path given its fid. Returns a 400 Bad request if the requested file is an extra.
Examples:
// GET https://api.plotly.com/v2/files/some_file:123/path ---> 200 OK
// GET https://api.plotly.com/v2/files/some_extra:123/path ---> 400 Bad Request
sources
Get the source relationships of a file: which files were created from this file, and which files were created from it.
Example:
// GET https://api.plotly.com/v2/files/snek:17/sources --> 200 OK
The response follows the JSON Graph Format. Several types of relationships are shown, if available:
-
If this file was copied from another file, a "parent" relationship from that file will be shown.
-
If this file was copied to produce other file(s), a "child" relationship to those file(s) will be shown.
-
If this file is a grid, all plots that use its data will be shown as "created plots".
-
If this file is a plot, all grids used as data will be shown as "source grids".
-
If this file is a grid and it was created by importing an external URL, the URL will appear as a "source URL".
Notes:
Sources are only available for plots and grids.
If you can't read the file at the other end of a source relationship, the relationship will not be shown.
Up to 5 of each source relationship will be returned. If more than that exist, artifical "next" and/or "prev" nodes will be returned. These can be followed to view more of that type of relationship.
GET /v2/files/Trahaearn:0?format=api
https://plotly.com/~Trahaearn/0.embed", "fid": "Trahaearn:0", "filename": "Japan Hostel Mapbox", "filetype": "plot", "img_url": "https://storage.googleapis.com/plotly-prod-images/Trahaearn/0/9_NSYI6TEJCRTRFNZAP7GVB5ZGM89E72.png", "image_urls": { "default": "https://storage.googleapis.com/plotly-prod-images/Trahaearn/0/2_Z8CWXJEXOP50G9UZ1RR4TL70CW5OUP.png", "block-thumb": "https://storage.googleapis.com/plotly-prod-images/Trahaearn/0/8_OYB6L5HMJXPXLY9P11LEO31Y3ULW3O.png", "list-thumb": "https://storage.googleapis.com/plotly-prod-images/Trahaearn/0/9_NSYI6TEJCRTRFNZAP7GVB5ZGM89E72.png" }, "api_urls": { "files": "https://api.plotly.com/v2/files/Trahaearn:0", "plots": "https://api.plotly.com/v2/plots/Trahaearn:0", "parent": "https://api.plotly.com/v2/folders/home?user=Trahaearn" }, "owner": "Trahaearn", "parent": -1, "preview": "", "referencers": [], "references": [], "title": "Hostels in Japan", "views": 25, "web_url": "https://plotly.com/~Trahaearn/0/hostels-in-japan/", "world_readable": true, "date_modified": "2019-05-12T03:55:32.599Z", "stars": { "results": [], "count": 0 }, "collaborators": { "results": [], "count": 0 }, "subfolder_count": null, "refresh_interval": null, "organize_view_url": "https://plotly.com/~Trahaearn/0/", "current_user_permission": "read", "is_theme": null, "is_template": null }{ "creation_time": "2019-03-21T03:13:50.213901Z", "comments": { "results": [], "count": 0 }, "parented": true, "embed_url": "