Skip to navigation
Visualizations

Create a visualization

View as Markdown

Creates a visualization. Rejects a specification that fails to build a chart from the data. If a visualization draws the same chart from the same data, returns it instead, regardless of name and labels.

Requires an API key with the write scope.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
namestringRequired1-255 characters
Name, unique among the organization's visualizations.
specificationmap from strings to anyRequired

Chart specification. It needs a chart_type: line, bar, scatter, box, or violin with traces, a list of {x_field, y_field, title?, group_by?, group_label?}; image with image_field and an optional caption_field; cube with x_field, y_field, channel_field, and intensity_field; big_number with value_field and optional aggregation, unit, and decimal_places; or sankey with stage_fields, two or more columns in stage order, and an optional value_field. Optional title, x_label, and y_label label the chart. Every field must be a column the data returns.

descriptionstring or nullOptional
Description shown with the chart.
dataset_idstring or nullOptionalformat: "uuid"
ID of a saved dataset to plot.
querystring or nullOptional

SQL query: a single read-only SELECT statement. Reference parameters as :name. The query is saved as a dataset named after the visualization, unless a dataset with the same query and default parameters exists.

default_parametersmap from strings to any or nullOptional
Default values for the query's parameters, keyed by name. Give one for every parameter the query uses. Only used with query.

Response

OK
idstringformat: "uuid"
namestring
publish_statusenum
Whether an authored object is finished enough for others to rely on. In review marks a draft its author considers ready for an admin to publish.
Allowed values:
date_updateddatetime
descriptionstring or nullOptional
datasetobject or nullOptional
specificationmap from strings to any or nullOptional
userobject or nullOptional
access_levelenum or nullOptional
What a grant lets its grantee do. Manage includes edit and adds sharing, archiving and deleting.
Allowed values:

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
500
Internal Server Error
503
Service Unavailable Error