Create a dashboard; with a ref already in use, return that dashboard with created false. One call can make a live page: send visuals and publish true, and the answer carries the dashboard's url. A ref already used by one of the owner's dashboards returns that dashboard, unchanged, with created false; its visuals are then created or found by their own refs, so a run cut short is finished by the next one. Needs an API key: with none yet, call signup first.
View input schema
{
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Not blank."
},
"description": {
"type": "string",
"maxLength": 500,
"default": ""
},
"scheme": {
"type": "string",
"enum": [
"ink",
"carbon",
"paper",
"ledger",
"slate",
"signal"
],
"default": "ink"
},
"ref": {
"type": "string",
"pattern": "^[a-z0-9-]{1,64}$",
"description": "A slug you choose, 1 to 64 of a-z, 0-9 and -. Unique per owner for dashboards and per dashboard for visuals, and set once. Create with a ref so a later run finds the same object instead of making a duplicate."
},
"visuals": {
"type": "array",
"description": "Created in order, each as POST /v1/dashboards/{id}/visuals would, so give every visual a ref when the dashboard has one.",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"bar",
"bar-horizontal",
"line",
"area",
"pie",
"kpi",
"table",
"markdown",
"scatter",
"funnel",
"gauge",
"map"
]
},
"title": {
"type": "string",
"maxLength": 120,
"default": "Untitled"
},
"document": {
"type": "object",
"description": "The visual's whole JSON document, valid for its type. Rules and an example per type:\n- bar: orientation is vertical. mode is grouped or stacked. Each data row is an object whose keys are exactly the xKey and each series key. Series values are numbers. xKey values are strings. No other keys. series has 1 to 6 items. data has at most 500 rows. Optional references: up to 6 items, each { value, label } for a flat line at a number (a value reference may take axis right when a series is on the right axis) or { at, label } for a marker at a category. A series may have as line (drawn as a line, never stacked); such a series may have dashed true and axis right. Keep at least one bar series. Example: {\"orientation\":\"vertical\",\"mode\":\"grouped\",\"xKey\":\"month\",\"series\":[{\"key\":\"revenue\",\"label\":\"Revenue\"},{\"key\":\"cost\",\"label\":\"Cost\"}],\"data\":[{\"month\":\"Jan\",\"revenue\":120,\"cost\":80},{\"month\":\"Feb\",\"revenue\":140,\"cost\":90}]}\n- bar-horizontal: orientation is horizontal. mode is grouped or stacked. Each data row is an object whose keys are exactly the xKey and each series key. Series values are numbers. xKey values are strings. No other keys. Optional references: up to 6 items, each { value, label } for a flat line at a number or { at, label } for a marker at a category. Example: {\"orientation\":\"horizontal\",\"mode\":\"grouped\",\"xKey\":\"month\",\"series\":[{\"key\":\"revenue\",\"label\":\"Revenue\"},{\"key\":\"cost\",\"label\":\"Cost\"}],\"data\":[{\"month\":\"Jan\",\"revenue\":120,\"cost\":80},{\"month\":\"Feb\",\"revenue\":140,\"cost\":90}]}\n- line: curve is linear, monotone, or step. Each data row is an object whose keys are exactly the xKey and each series key. Series values are numbers. xKey values are strings. No other keys. Optional references: up to 6 items, each { value, label } for a flat line at a number (a value reference may take axis right when a series is on the right axis) or { at, label } for a marker at a category. A series may have dashed true. A series may have axis left or right; keep at least one series on the left. Example: {\"xKey\":\"date\",\"curve\":\"monotone\",\"series\":[{\"key\":\"users\",\"label\":\"Users\"}],\"data\":[{\"date\":\"2026-01\",\"users\":10}]}\n- area: Same row rules as line. stacked is a boolean. Each data row is an object whose keys are exactly the xKey and each series key. Series values are numbers. xKey values are strings. No other keys. Optional references: up to 6 items, each { value, label } for a flat line at a number or { at, label } for a marker at a category. A series may have dashed true. Example: {\"xKey\":\"date\",\"curve\":\"monotone\",\"stacked\":false,\"series\":[{\"key\":\"users\",\"label\":\"Users\"}],\"data\":[{\"date\":\"2026-01\",\"users\":10}]}\n- pie: Each data row is an object whose keys are exactly nameKey and valueKey. nameKey values are strings. valueKey values are numbers greater than or equal to 0. At most 24 slices. donut is a boolean. Example: {\"nameKey\":\"category\",\"valueKey\":\"amount\",\"donut\":true,\"data\":[{\"category\":\"New\",\"amount\":40},{\"category\":\"Returning\",\"amount\":60}]}\n- kpi: label is a string, value is a number, format is number, compact, or percent. Optional prefix, suffix, delta, deltaFormat (number or percent), deltaLabel, and trend (up to 60 numbers, oldest first, in the same unit as value). No other keys. Example: {\"label\":\"MRR\",\"value\":12840,\"format\":\"number\",\"prefix\":\"$\",\"suffix\":\"\",\"delta\":0.12,\"deltaFormat\":\"percent\",\"deltaLabel\":\"vs last month\"}\n- table: columns has 1 to 12 entries with key, label, align left or right, and format text, number, or percent. data has at most 200 rows. Each row's keys are column keys and hrefKey keys. Cell values are strings, numbers, or null. A text column may have statuses, a map from cell text to good, warn, or bad (1 to 20 entries). A number or percent column may have rules: 1 to 6 items, each { below or atLeast, status }; the first match wins. A text column may have hrefKey, a row key whose value (an http or https URL, null or empty) links the cell. Example: {\"columns\":[{\"key\":\"name\",\"label\":\"Name\",\"align\":\"left\",\"format\":\"text\"},{\"key\":\"amount\",\"label\":\"Amount\",\"align\":\"right\",\"format\":\"number\"}],\"data\":[{\"name\":\"Acme\",\"amount\":10}]}\n- markdown: The only key is source, a string of at most 20000 characters. Example: {\"source\":\"## Notes\\n\\n- Pipeline is up\\n- See [status](https://example.com)\"}\n- scatter: xKey and yKey values are numbers. labelKey is optional and its values are strings. Each row's keys are exactly xKey, yKey, and labelKey when labelKey is present. At most 500 points. Example: {\"xKey\":\"price\",\"yKey\":\"units\",\"labelKey\":\"label\",\"data\":[{\"price\":10,\"units\":3,\"label\":\"A\"}]}\n- funnel: Each row's keys are exactly nameKey and valueKey. Names are strings. Values are numbers greater than or equal to 0. data may be empty or have at most 12 stages. Keep array order. Example: {\"nameKey\":\"stage\",\"valueKey\":\"count\",\"data\":[{\"stage\":\"Visit\",\"count\":1000},{\"stage\":\"Signup\",\"count\":400},{\"stage\":\"Paid\",\"count\":80}]}\n- gauge: label is a string. value, min, and max are numbers with min less than max. suffix is an optional string. No other keys. Example: {\"label\":\"Utilization\",\"value\":72,\"min\":0,\"max\":100,\"suffix\":\"%\"}\n- map: region is world, us-states or us-counties. idKey and valueKey name the row fields; labelKey is optional. format is number (default), compact or percent; prefix and suffix are optional strings. Each data row's keys are exactly idKey, valueKey and labelKey when set. The idKey value is a region code: for world an ISO 3166-1 alpha-2 code such as DE (alpha-3 accepted), for us-states a USPS code such as CA (two-digit FIPS accepted), for us-counties a five-digit county FIPS code such as 06037 (the 2017 county lines, leading zero kept); case is ignored. At most one row per region; a code with no shape on the map (Puerto Rico and the territories on us-states; territories drawn as part of their country on world; Connecticut's planning regions and Alaska's Chugach and Copper River on us-counties) is refused with the region's name. valueKey values are numbers. Example: {\"region\":\"world\",\"idKey\":\"country\",\"valueKey\":\"signups\",\"format\":\"number\",\"data\":[{\"country\":\"US\",\"signups\":412},{\"country\":\"GB\",\"signups\":138},{\"country\":\"DE\",\"signups\":96},{\"country\":\"IN\",\"signups\":87},{\"country\":\"CA\",\"signups\":64},{\"country\":\"BR\",\"signups\":41},{\"country\":\"AU\",\"signups\":33},{\"country\":\"JP\",\"signups\":19}]}"
},
"size": {
"type": "object",
"description": "Defaults to the type's default size. Width and height within the type's limits, which describe_visual_types lists per type with the widths the editor offers.",
"additionalProperties": false,
"properties": {
"w": {
"type": "integer",
"minimum": 3,
"maximum": 12,
"description": "Columns out of 12."
},
"h": {
"type": "integer",
"minimum": 3,
"maximum": 16,
"description": "Height in 50-pixel rows."
}
},
"required": [
"w",
"h"
]
},
"ref": {
"type": "string",
"pattern": "^[a-z0-9-]{1,64}$",
"description": "A slug you choose, 1 to 64 of a-z, 0-9 and -. Unique per owner for dashboards and per dashboard for visuals, and set once. Create with a ref so a later run finds the same object instead of making a duplicate."
}
},
"required": [
"type",
"document"
]
},
"minItems": 1,
"maxItems": 24
},
"publish": {
"type": "boolean",
"default": false,
"description": "Make the page public for anyone with the link, as POST /v1/dashboards/{id}/publish would."
},
"shareWith": {
"type": "array",
"description": "People who may view the dashboard after signing in with these addresses, each made as POST /v1/dashboards/{id}/shares would and emailed the link: view-only, and the dashboard stays private unless publish is true too.",
"items": {
"type": "string",
"format": "email",
"maxLength": 128
},
"minItems": 1,
"maxItems": 20,
"uniqueItems": true
},
"dryRun": {
"type": "boolean",
"default": false,
"description": "Check everything and write nothing; answers 200 { dryRun: true } or the error the real call would give."
}
},
"required": [
"title"
],
"additionalProperties": false
}