Plotly REST API, v2

Grids

Grids are the core of Plotly's data API. A plot's traces reference underlying grid data. This endpoint allows API creation and manipulation of grids.

Reference

authorization
grid meta information
actions
- create
- upload
- row
- col
- retrieve
- content
- destroy
- partial update
- update
- drop_reference
- trash
- restore
- permanent delete
- lookup

Authorization

Any user with or without a Plotly account may view public grid files. For private files, see authentication.

Grid Meta Information

The grid meta information extends the file meta information with the following fields:

write-only fields:

data only accessible from the create endpoint

read-write fields:

cols only writable from the col endpoint
rows only accessible from the row endpoint
metadata

Actions

create

To create a grid, POST to this endpoint with any of the writable grid fields included in the body of the request. The only required field is data.

The data field takes the following form:

{
    "cols":
        {
            "first column": {"data": ["a", "b", "c"], "order": 0},
            "second column": {"data": [1, 2, 3], "order": 1}
        }
}

Note: each column of the cols field is a key-value pair with the key corresponding to the column header name and the value corresponding to an object specifying the column's order and data.

Example:

// POST https://api.plotly.com/v2/grids --> 201 Created
{
    "data": {"cols": {"first": {"data": [1,2,3], "order": 0}}}
}

// POST https://api.plotly.com/v2/grids --> 201 Created
{
    "data": "{\"cols\": {\"first\": {\"data\": [1,2,3], \"order\": 0}}}",
    "parent": 932,
    "filename": "new grid"
}

Note: the integer associated with the parent field corresponds to a file with idlocal 932. This file must have filetype fold for a sucessful POST.

When creating a grid, you can optionally specify source fields to indicate where a grid has come from:

source_fid: the fid of a grid that was copied (and presumably edited) to produce this one
source_url: the URL this grid was imported from
source_referer: if source_url is given, you can optionally add this field to give the URL of an index page where the source_url link appears. (This could give more information about the data, or present it in alternate formats.)

upload

A raw file may be uploaded by making a POST request to the upload endpoint. This will create a new grid for a single 2D data source, or a folder containing multiple grids when there are multiple data sources (e.g. a spreadsheet with many tabs, or a zip archive). To determine which type of file has been created, check the filetype key in the response, which will either be grid or fold.

The following options may be passed as HTTP headers to control the upload.

X-File-Name: gives the filename of the file being uploaded. The extension is used as a first guess of the file type for parsing and will be used as the created filename if possible.
Plotly-World-Readable: controls the visibility of the created grid or folder. May be true or false. Defaults to false.
Plotly-Parent: gives the parent folder id, like for create.
Plotly-Parent-Path: gives the path to the parent folder, like for create.

row

The row endpoint allows you to append existing grids with new information. This endpoint requires a POST and returns a 201 Created response on success.

Examples:

// POST https://api.plotly.com/v2/grids/henreitta:88/row --> 201 Created
// Add three rows to the existing grid with fid henrietta:88
{
    "rows": [[1, 0.5], [2, 0.1], [3, 0.7]]
}

col

The col endpoint allows you to retrieve existing columns of a grid via a GET request, completely replace existing columns of a grid via a PUT request, or append existing grids with full columns of new data via a POST request. Both the GET and PUT requests require the existing columns to be specified via a uid query (see examples below) and return a 200 OK response on success. The data, name and order fields of a column can be updated via a PUT request. The POST request does not take a column query and returns a 201 Created response on success.

Example GET:

// GET https://api.plotly.com/v2/grids/henreitta:88/col?uid=some_uid --> 200 OK
// Retrieve a column with uid "some_uid"

// GET https://api.plotly.com/v2/grids/henreitta:88/col?uid=some_uid,some_other_uid --> 200 OK
// Retrieve multiple columns with uids "some_uid" and "some_other_uid"

// GET https://api.plotly.com/v2/grids/henreitta:88/col?uid=not_contained_in_grid --> 400 Bad Request
// Attempt to retrieve a column not contained in grid

Example PUT:

// PUT https://api.plotly.com/v2/grids/henreitta:88/col?uid=some_uid --> 200 OK
// Replace a column with uid "some_uid"
{
    "cols": "[{\"data\": [0, 1], \"name\": \"new name\"}]"
}

// PUT https://api.plotly.com/v2/grids/henreitta:88/col?uid=some_uid,some_other_uid --> 200 OK
// Replace multiple columns with uids "some_uid" and "some_other_uid"
{
    "cols": "[{\"data\": [0, 1], \"order\": 0}, {\"data\": [\"a\", \"b\"]}]"
}

// PUT https://api.plotly.com/v2/grids/henreitta:88/col?uid=not_contained_in_grid --> 400 Bad Request
// Attempt to replace a column not contained in grid
{
    "cols": "[{\"data\": [0, 1]}]"
}

// PUT https://api.plotly.com/v2/grids/henreitta:88/col?uid=only_one_uid_specified --> 400 Bad Request
// Attempt to update a column with multiple columns of data
{
    "cols": "[{\"data\": [0, 1]}, {\"data\": [\"a\", \"b\"]}]"
}

Note: The data to be updated via a PUT request will respect the order of the columns specified by the uids of the query.

Example POST:

// POST https://api.plotly.com/v2/grids/henreitta:88/col --> 400 Bad Request
// Add two columns
{
    "cols": [{"name": "col name 1", "data": [0, 1]}, {"name": "col name 2", "data": [9, 9]}]
}

// POST https://api.plotly.com/v2/grids/henreitta:88/col --> 201 Created
// Add two columns
{
    "cols": "[{\"name\": \"col name 1\", \"data\": [0, 1]}, {\"name\": \"col name 2\", \"data\": [9, 9]}]"
}

retrieve

The grid meta information can be retrieved by making a GET request to the grids endpoint.

Example:

// GET https://api.plotly.com/v2/grids/henrietta:88

content

The contents of a grid can be downloaded via a GET request to the content resource. The Content-Type header will be appropriately set for the response body.

Example:

// GET https://api.plotly.com/v2/grids/henrietta:88/content

destroy

To delete an grid, make a DELETE request to the grids endpoint and include the fid for the grid file. A successful response will have a status code of 204 No Content.

Example:

// DELETE https://api.plotly.com/v2/grids/henrietta:88 --> 204 No Content

partial update

To update the writable meta information of an existing grid, you make a PATCH request to the grids endpoint and include the fid for the grid file. A successful response will have a status code of 200 OK.

Example:

// PATCH https://api.plotly.com/v2/grids/henrietta:88 --> 200 OK
{
    "metadata": "{\"content\": \"copy copy copy copy copy\"}",
    "filename": "my new and unique grid name",
    "parent": 123
}

update

To completely replace the writable meta information of an existing grid, you make a PUT request to the grids endpoint and include the fid for the grid file. A successful response will have a status code of 200 OK.

Example:

// PUT https://api.plotly.com/v2/grids/henrietta:88 --> 200 OK
{
    "parent": -1,
    "world_readable": true,
    "filename": "my new and unique grid name"
    "metadata": "{\"content\": \"copy copy copy copy copy\"}",
}

drop reference

Grids may reference other files in Plotly called extras. Because extras may be referenced from many files, instead of deleting them to remove them, you may just dereference them via a POST request to this endpoint. This is a safer approach and is used to manage extras in the Plotly webapp. A successful response will have a status code of 200 OK.

Example:

// POST https://api.plotly.com/v2/grids/henrietta:88/drop_reference --> 200 OK
{
    "fid": "henrietta:99"
}

trash

A POST request to this endpoint allows for the recoverable trashing of the grid specified in the detail. A successful response will have a status code of 200 OK.

Example:

// POST https://api.plotly.com/v2/grids/henrietta:88/trash ---> 200 OK

Note: This request is idempotent. Trashing a folder that is already trashed will also succeed and return 200 OK.

restore

This endpoint allows for a trashed grid to be restored via a POST request. Only the owner of the grid has permission to restore that grid. A successful restore response will have a status code of 200 OK.

Example:

// POST https://api.plotly.com/v2/grids/henrietta:88/restore ---> 200

Note: This request is idempotent. Restoring a grid that is not yet trashed will also succeed and return 200 OK.

permanent delete

A DELETE request to this endpoint allows for the permanent deletion of the grid specified in the endpoint detail. A successful response will have a status code of 204 No Content.

Example:

// DELETE https://api.plotly.com/v2/grids/plotlvr:9/permanent_delete ---> 204 No Content

lookup

Get a grid 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 grid location.
parent (optional) The parent id, an integer, which the path is relative to.
user (optional) The username of the owner of the file.

Examples:

// GET https://api.plotly.com/v2/grids/lookup?path=my_folder/my_file ---> 200 OK

// GET https://api.plotly.com/v2/grids/lookup?parent=200&path=my_file ---> 200 OK

// GET https://api.plotly.com/v2/grids/lookup?user=wonderwoman&path=her_folder/her_file ---> 200 OK

// GET https://api.plotly.com/v2/grids/lookup?user=wonderwoman&parent=22&path=her_file ---> 200 OK

GET /v2/grids/Gomez96:120/?format=api

HTTP 200 OK
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "creation_time": "2023-05-14T22:35:08.645196Z",
    "comments": {
        "results": [],
        "count": 0
    },
    "parented": true,
    "embed_url": "https://chart-studio.plotly.com/~Gomez96/120.embed",
    "fid": "Gomez96:120",
    "filename": "Grid 120",
    "filetype": "grid",
    "img_url": "",
    "image_urls": {},
    "api_urls": {
        "files": "https://api.plotly.com/v2/files/Gomez96:120",
        "grids": "https://api.plotly.com/v2/grids/Gomez96:120",
        "parent": "https://api.plotly.com/v2/folders/home?user=Gomez96"
    },
    "owner": "Gomez96",
    "parent": -1,
    "preview": {
        "A": [
            "0.1",
            "0.2",
            "0.3",
            "0.5",
            "0.6",
            "0.9",
            "1",
            "1.1",
            "1.2",
            "1.3"
        ],
        "B": [
            "3.5",
            "4",
            "1.333333",
            "2.5",
            "2.5",
            "2.5",
            "8",
            "3",
            "2.333333",
            "1"
        ]
    },
    "referencers": [],
    "references": [],
    "title": "",
    "views": 1,
    "web_url": "https://chart-studio.plotly.com/~Gomez96/120/",
    "world_readable": true,
    "date_modified": "2023-05-14T22:35:09.292Z",
    "stars": {
        "results": [],
        "count": 0
    },
    "collaborators": {
        "results": [],
        "count": 0
    },
    "subfolder_count": null,
    "refresh_interval": null,
    "organize_view_url": "https://chart-studio.plotly.com/~Gomez96/120/",
    "current_user_permission": "read",
    "is_theme": null,
    "is_template": null,
    "cols": [
        {
            "name": "A",
            "uid": "3a2610"
        },
        {
            "name": "B",
            "uid": "bea359"
        }
    ],
    "metadata": {},
    "parent_id": -1
}

Grids Instance

Grids

Reference

Authorization

Grid Meta Information

write-only fields:

read-write fields:

Actions

create

upload

row

col

retrieve

content

destroy

partial update

update

drop reference

trash

restore

permanent delete

lookup

query params