Folders


Jump to API response

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=andrew.j.stephens
HTTP 400 Bad Request
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "detail": "Unrecognized query params found: ['format']. Valid params: ['path', 'page_size', 'world_readable', 'page', 'image_name', 'exists', 'order_by', 'user', 'parent', 'share_key', 'filetype']",
    "errors": [
        {
            "code": "UNKNOWN",
            "message": "Unrecognized query params found: ['format']. Valid params: ['path', 'page_size', 'world_readable', 'page', 'image_name', 'exists', 'order_by', 'user', 'parent', 'share_key', 'filetype']",
            "path": null,
            "field": null
        }
    ]
}