Files


Jump to API response

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 -admin
  • embed_url
  • fid
  • filetype
  • img_url
  • image_urls
  • owner
  • parented
  • preview
  • references
  • referencers
  • share_key -admin
  • share_key_enabled -admin
  • stars
  • collaborators
  • subfolder_count
  • title
  • views
  • web_url
  • current_user_permission

write-only fields:

  • parent_path

read-write fields:

  • filename
  • parent
  • share_key_enabled -admin
  • world_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/xuzhaoqing:14?format=api
HTTP 200 OK
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "creation_time": "2019-03-21T03:15:23.895824Z",
    "comments": {
        "results": [],
        "count": 0
    },
    "parented": true,
    "embed_url": "https://plotly.com/~xuzhaoqing/14.embed",
    "fid": "xuzhaoqing:14",
    "filename": "plot from API (6)",
    "filetype": "plot",
    "img_url": "https://storage.googleapis.com/plotly-prod-images/xuzhaoqing/14/9_PQK3EKYXTM3UPQ4Z4ZGHRD3X9UH3AG.png",
    "image_urls": {
        "default": "https://storage.googleapis.com/plotly-prod-images/xuzhaoqing/14/2_6FRUOBL2CC02POSFUOP4R5JG1MV588.png",
        "block-thumb": "https://storage.googleapis.com/plotly-prod-images/xuzhaoqing/14/8_VJFQAXQ2Q5JCUI684QE4OEMGBVKNAQ.png",
        "list-thumb": "https://storage.googleapis.com/plotly-prod-images/xuzhaoqing/14/9_PQK3EKYXTM3UPQ4Z4ZGHRD3X9UH3AG.png"
    },
    "api_urls": {
        "files": "https://api.plotly.com/v2/files/xuzhaoqing:14",
        "plots": "https://api.plotly.com/v2/plots/xuzhaoqing:14",
        "parent": "https://api.plotly.com/v2/folders/home?user=xuzhaoqing"
    },
    "owner": "xuzhaoqing",
    "parent": -1,
    "preview": "",
    "referencers": [],
    "references": [],
    "title": "A.M. and P.M. Fatal Collisions by Age",
    "views": 46,
    "web_url": "https://plotly.com/~xuzhaoqing/14/am-and-pm-fatal-collisions-by-age/",
    "world_readable": true,
    "date_modified": "2019-03-21T03:15:24.382Z",
    "stars": {
        "results": [],
        "count": 0
    },
    "collaborators": {
        "results": [],
        "count": 0
    },
    "subfolder_count": null,
    "refresh_interval": null,
    "organize_view_url": "https://plotly.com/~xuzhaoqing/14/",
    "current_user_permission": "read",
    "is_theme": null,
    "is_template": null
}