Home
Folders
This endpoint allows you to create arbitrarily-deep, nested folders and
list the children of a folder (similar to ls
).
Reference
Authorization
You must have an account to make folders and so you must be logged in or
must provide the appropriate credentials, see
authentication. New folders start
at your directory root unless a parent
field is given.
Actions
The only supported actions at the folders endpoint are create and retrieve.
create
To create a folder, POST to this endpoint with at least the path
field filled out with a valid value:
Example:
// POST https://api.plotly.com/v2/folders --> 201 Created
{
"path": "/starts/at/root/and/ends/here"
}
Additionally, you may specify a parent
field, which must be a folder. If
a parent field is specified, the path
field must only contain the name
of the new folder to be created with the specified parent (i.e., the path
field must no longer contain folders).
Example:
// POST https://api.plotly.com/v2/folders --> 201 Created
{
"path": "new_folder",
"parent": 84
}
Note that the parent field's value refers to an
idlocal of a file with filetype fold
.
detail
When accessing a detail view on a folder, a successful response will return an object that contains an array of serialized files and or folders within the target folder wrapped within the "children" field.
Example response for GET on folder:
// GET https://api.plotly.com/v2/folders/test:15
{
"children": {
"count": 2,
"next": null,
"previous": null,
"first": "https://api-local.plot.ly/v2/folders/test:15?page=1",
"last": "https://api-local.plot.ly/v2/folders/test:15?page=1",
"results": [
{
"filename": "Stacked Bar Chart",
"filetype": "plot",
"fid": "test:11",
"files_url": "https://api-local.plot.ly/v2/files/test:11"
},
{
"filename": "User Traffic",
"filetype": "plot",
"fid": "test:9",
"files_url": "https://api-local.plot.ly/v2/files/test:9"
}
]
}
}
home
Get all files in the home
folder for a given user which are also viewable
by the current user.
When given without query params, the request will assume
the home
folder of the request.user
is desired. To view the home
folder of another user, use the user
query param. See
query params for more details.
Example:
// Get *your* home folder
// GET https://api.plotly.com/v2/folders/home --> 200 OK
{ .. }
// Verbose version of getting your home folder (same as above)
// GET https://api.plotly.com/v2/folders/home?user=you --> 200 OK
{ .. }
// Get someone else's home folder
// GET https://api.plotly.com/v2/folders/home?user=someone_else --> 200 OK
{ .. }
shared
This returns all files shared with the requester.
Examples:
// Get all files shared with you
// GET https://api.plotly.com/v2/folders/shared --> 200 OK
{ .. }
starred
This returns all the files the requester has starred.
Example:
// Get all the files you thought were cool!
// GET https://api.plotly.com/v2/folders/starred --> 200 OK
{ .. }
trashed
This returns all the files the requester has ever deleted.
Example:
// Get all the files you decided to delete
// GET https://api.plotly.com/v2/folders/trashed --> 200 OK
{ .. }
all
This returns all the active files that the requester owns. If user query is present, only public files are returned.
Example:
// GET https://api.plotly.com/v2/folders/all --> 200 OK
{ .. }
owned themes
This returns all themes the requestor owns.
Example:
// GET https://api.plotly.com/v2/folders/themes_owned --> 200 OK
{ .. }
shared themes
This returns all themes that were shared with the requestor.
Example:
// GET https://api.plotly.com/v2/folders/themes_shared --> 200 OK
{ .. }
owned templates
This returns all templates the requestor owns.
Example:
// GET https://api.plotly.com/v2/folders/templates_owned --> 200 OK
{ .. }
shared templates
This returns all templates that were shared with the requestor.
Example:
// GET https://api.plotly.com/v2/folders/templates_shared --> 200 OK
{ .. }
query params
The following parameters may be used (they're neglected if unnecessary):
- user Who's home folder are we looking at? see home
- filetype Return only results matching this filetype (e.g. plot).
- order_by Order results by given value.
user
Specify the owner of the pseudo-folder, (pseudo-folders being home
,
starred
, trashed
, etc.). That is, target user's shared folders,
target user's home folder, etc. This is how you view another user's
home
folder.
Example:
// Get all of jonhamm's files in his home folder
// GET https://api.plotly.com/v2/folders/home?user=jonhamm --> 200 OK
filetype
Return the subset of results which have the specified filetypes. Filtering by multiple filetypes is supported.
Filetype options:
- plot
- grid
- fold
Examples:
// Get your plots in the home folder (i.e., not folders or grids)
// GET https://api.plotly.com/v2/folders/home?filetype=plot --> 200 OK
{ .. }
// Get all the folders in a folder
// GET https://api.plotly.com/v2/folders/home?filetype=fold --> 200 OK
{ .. }
// Get all the plots and grids in a folder
// GET https://api.plotly.com/v2/folders/home?filetype=plot&filetype=grid
{ .. }
world_readable
Return the subset of results which have the specified value for their
world_readable
field. A value of true
will return all public files in
the folder, and a value of false
will return all private files in
the folder.
Examples:
// Return only public files
// GET https://api.plotly.com/v2/folders/home?world_readable=true --> 200 OK
{ .. }
// Return only private files
// GET https://api.plotly.com/v2/folders/home?world_readable=false --> 200 OK
{ .. }
order_by
Order by a field in ascending or descending order. Ascending order is
assumed. To order in a descending manner, prepend the field with a -
(minus sign):
?order_by=[-]<order_by-field>
Available order_by fields:
- creation_time
- date_modified
- filename
- filetype
- views
Examples:
// Get your files ordered by date_modified, descending
// GET https://api.plotly.com/v2/folders/home?order_by=-date_modified --> 200 OK
{ .. }
// Get your files ordered alphabetically
// GET https://api.plotly.com/v2/folders/home?order_by=filename --> 200 OK
{ .. }
trash
Recursively trash a folder and its children. This action is reversible. To
trash a folder, you POST
at the /trash endpoint under the folder's detail
url. A successful POST
will receive a 200 OK
response.
Examples:
// This works once
// POST https://api.plotly.com/v2/folders/greg:387/trash --> 200 OK
restore
Recursively restore a folder and its children from the Trash. To restore
a folder, you POST
to the /restore
endpoint under the folder's detail
url. A successful POST
will receive a 200 OK
response.
Example:
// This works once if the folder is in the Trash
// POST https://api.plotly.com/v2/folders/greg:387/restore --> 200 OK
permanent delete
Recursively, permanently delete a folder and its children. To permanently
delete a folder, you DELETE
to the /permanent_delete
endpoint under the
folder's detail url. A successful POST
will receive a 200 OK
response.
Note that children trashed separately from this folder will also be
permanently deleted by this action. This is because these children cannot
be restored to their previous parent folder anyway.
Examples:
// This works once
// DELETE https://api.plotly.com/v2/folders/greg:387/permanent_delete --> 200 OK
// But fails a second time because the resource no longer exists
// DELETE https://api.plotly.com/v2/folders/greg:387/permanent_delete --> 404 Not Found
GET /v2/folders/home?format=api&user=s3792283
{
"detail": "Unrecognized query params found: ['format']. Valid params: ['path', 'exists', 'filetype', 'share_key', 'image_name', 'page', 'world_readable', 'page_size', 'order_by', 'user', 'parent']",
"errors": [
{
"code": "UNKNOWN",
"message": "Unrecognized query params found: ['format']. Valid params: ['path', 'exists', 'filetype', 'share_key', 'image_name', 'page', 'world_readable', 'page_size', 'order_by', 'user', 'parent']",
"path": null,
"field": null
}
]
}