Api Root
Plotly's API
Reference:
Beta Endpoints
Endpoints marked as -beta are subject to change, possibly without notice. Behaviour of action may not necessarily remain backwards compatible upon update.
Definitions
Plotly uses a few terms often which have specific internal meaning.
idlocal: Each user's files are numbered (starting at 0) uniquely. The the idlocal is this unique number for a given user.
fid: This stands for 'file id' and is the combination of a username and a id number (e.g., 'username:10'). Plotly uses this ubiquitously to identify user's files and it is the lookup field in our api urls.
file: The generic term file is used to encompass any file-like object in Plotly. This includes plots, grids, supplemental materials, etc.
reference: File A references file B if file B provides data or context for File A. Plots often reference grids. Plots and grids often reference Extras.
referencer: The reverse relationship of a reference.
metadata: Information belonging to a grid that describes context for the data. For example, component values or machine settings for a given test. The metadata field can only be added to a grid via the grids api and it can only be queried via the search api.
Authentication
Calls from external libraries use basic authentication using your Plotly username and API key. Your API key can be found on the settings page when you are logged in to the site.
In the future, we will require OAuth
A Plotly-Client-Platform header must be present, consisting of
the platform name and an optional version. The version is the
version of the client library, not the client language itself. It
is a string consisting of only decimal digits and periods, and
must be preceded by at least one space.
Examples:
Plotly-Client-Platform: Lisp
Plotly-Client-Platform: Python 0.2
Plotly-Client-Platform: Python 0.2.5
Plotly-Client-Platform: Python 3 0.3.2
The versions here are: unspecified, 0.2, 0.2.5, and 0.3.2 respectively.
Calls from the webapp have a session cookie, CSRF cookie, and CSRF header as for standard Django applications.
Responses
When an API request fails, the response content usually has a 'detail' field. This field gives more information about the failed request. Note that the availability of this field shouldn't be depended on.
400 Bad Request: Simply an improperly formatted request.
401 Unauthorized: The action attempted requires authentication and you are not logged in or did not provide adequate credentials.
403 Forbidden: You are authenticated and the file exists, but you don't have permission to complete the desired action.
404 Not Found: You are authenticated, but either (1) the file doesn't exist or (2) you don't have permission complete the desired action.
405 Method Not Allowed: The endpoint exists but is currently inactive. This usually indicates plans for future support.
Endpoints
search:
The search endpoint currently supports searching grid metadata. That is, you cannot perform searches that reach content of of files (e.g., a plot title) or other non-metadata fields (e.g., filename).
files:
Performs file-level operations on Plotly accounts.
This included getting the content of Plotly files (e.g., the data in a plot), returning generic meta information about files/folders, trashing files (recoverable), restoring files, permanently deleting files, and (partially) updating writable meta information.
grids
Handles all manipulation of Plotly grids and detail views for meta information about grids.
plots:
Handles the retrieving of plot content/meta inforation and the listing of all public or handpicked feed plots.
extras:
Handles creating, updating, and getting meta information about related files. Extras are supplemental materials associated with other files, like plots or grids.
folders:
An endpoint to create new folders with arbitrarily deep nesting.
images:
An endpoint to generate static plot images from plot JSON.
comments:
An Endpoint to create and delete comments.
plot-schema:
An endpoint to get a schema for validating plotlyjs JSON blobs.
users:
An endpoint to list/retrieve user meta information.
memberships:
organizations:
subscriptions:
jupyter notebooks:
View Jupyter notebooks api page
shapefiles:
external images:
dashboards:
analysis:
GET /v2/?format=api
{ "users": "https://api.plot.ly/v2/users?format=api", "plot-schema": "https://api.plot.ly/v2/plot-schema?format=api", "oauth-apps": "https://api.plot.ly/v2/oauth-apps?format=api", "search": "https://api.plot.ly/v2/search?format=api", "files": "https://api.plot.ly/v2/files?format=api", "grids": "https://api.plot.ly/v2/grids?format=api", "plots": "https://api.plot.ly/v2/plots?format=api", "extras": "https://api.plot.ly/v2/extras?format=api", "folders": "https://api.plot.ly/v2/folders?format=api", "images": "https://api.plot.ly/v2/images?format=api", "memberships": "https://api.plot.ly/v2/memberships?format=api", "organizations": "https://api.plot.ly/v2/organizations?format=api", "subscriptions": "https://api.plot.ly/v2/subscriptions?format=api", "comments": "https://api.plot.ly/v2/comments?format=api", "jupyter-notebooks": "https://api.plot.ly/v2/jupyter-notebooks?format=api", "shapefiles": "https://api.plot.ly/v2/shapefiles?format=api", "external-images": "https://api.plot.ly/v2/external-images?format=api", "dashboards": "https://api.plot.ly/v2/dashboards?format=api", "analysis": "https://api.plot.ly/v2/analysis?format=api" }