Visuals
Charts, pivots, maps, and other visual representations attached to a Dataset.
A visual's component is keyed by its visual type; the configuration inside
is owned by the client and stored verbatim.
GET /api/datasets/{id}/visuals
List the Dataset's visuals, sorted by name.
Authentication: Required
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
pinned | boolean | Filter to pinned (or unpinned) visuals |
List visualsGET /api/datasets/admin:northwind-orders/visuals
Sorted by name. pinned=true filters to pinned visuals. resolvedName carries the display name even for auto-named visuals.
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/visuals"
}
},
"start": 0,
"count": 1,
"total": 1,
"_embedded": {
"inf:visual": [
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/visuals/00000000-0000-4000-8000-000000000001"
},
"view": [
{
"href": "https://informer.example.com/w/00000000-0000-4000-8000-000000000001.png",
"type": "image/png"
},
{
"href": "https://informer.example.com/w/00000000-0000-4000-8000-000000000001.html",
"type": "text/html"
},
{
"href": "https://informer.example.com/w/00000000-0000-4000-8000-000000000001.jpg",
"type": "image/jpeg"
},
"… 1 more items (4 total) — omitted from docs"
],
"inf:dataset": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002"
}
},
"component": {
"chart": {
"dataset": "00000000-0000-4000-8000-000000000002",
"xAxis": {
"field": "ShipCountry"
},
"series": [
{
"fn": "sum",
"field": "orderAmount"
}
],
"chartType": "column"
}
},
"permissions": {
"write": true,
"deletePinned": false
},
"id": "00000000-0000-4000-8000-000000000001",
"datasourceId": null,
"datasetId": "00000000-0000-4000-8000-000000000002",
"source": null,
"name": "Revenue by Country",
"description": null,
"defaultName": null,
"defaultDescription": null,
"embedded": false,
"pinned": false,
"layoutData": {},
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"tenant": "acme",
"ownerId": "admin",
"datasets": [],
"resolvedName": ""
}
]
}
}
resolvedName carries the display name even when the visual is auto-named.
POST /api/datasets/{id}/visuals
Create a visual. The visual is owned by the calling user.
Authentication: Required
Permission: dataset:addVisual (Designer or above on the owning team)
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
component | object | Yes | Keyed by visual type (chart, pivot, map, …) with the type's config inside |
name | string | No | Display name |
description | string | No | Description |
Response: 201 Created with a Location header.
Create a visualPOST /api/datasets/admin:northwind-orders/visuals
component is keyed by the visual type; the type-specific config inside is owned by the client and stored verbatim. The visual lands owned by the calling user.
Request body
{
"name": "Revenue by Country",
"component": {
"chart": {
"dataset": "00000000-0000-4000-8000-000000000001",
"chartType": "column",
"xAxis": {
"field": "ShipCountry"
},
"series": [
{
"field": "orderAmount",
"fn": "sum"
}
]
}
}
}
Response · 201
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/visuals/00000000-0000-4000-8000-000000000002"
},
"view": [
{
"href": "https://informer.example.com/w/00000000-0000-4000-8000-000000000002.png",
"type": "image/png"
},
{
"href": "https://informer.example.com/w/00000000-0000-4000-8000-000000000002.html",
"type": "text/html"
},
{
"href": "https://informer.example.com/w/00000000-0000-4000-8000-000000000002.jpg",
"type": "image/jpeg"
},
"… 1 more items (4 total) — omitted from docs"
],
"inf:dataset": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001"
}
},
"component": {
"chart": {
"dataset": "00000000-0000-4000-8000-000000000001",
"xAxis": {
"field": "ShipCountry"
},
"series": [
{
"fn": "sum",
"field": "orderAmount"
}
],
"chartType": "column"
}
},
"permissions": {
"write": true,
"deletePinned": false
},
"id": "00000000-0000-4000-8000-000000000002",
"pinned": false,
"layoutData": {},
"tenant": "acme",
"name": "Revenue by Country",
"datasetId": "00000000-0000-4000-8000-000000000001",
"embedded": false,
"ownerId": "admin",
"updatedAt": "2026-01-15T16:20:00.000Z",
"createdAt": "2026-01-15T16:20:00.000Z",
"source": null,
"description": null,
"defaultName": null,
"defaultDescription": null,
"datasourceId": null
}
Starter configs
GET /visual-templates and GET /discover (see
Discovery & Templates) answer ready-made
component payloads for every visual type.
GET /api/datasets/{datasetId}/visuals/{id}
Get a single visual.
Authentication: Required
Get a visualGET /api/datasets/admin:northwind-orders/visuals/00000000-0000-4000-8000-000000000001
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/visuals/00000000-0000-4000-8000-000000000001"
},
"view": [
{
"href": "https://informer.example.com/w/00000000-0000-4000-8000-000000000001.png",
"type": "image/png"
},
{
"href": "https://informer.example.com/w/00000000-0000-4000-8000-000000000001.html",
"type": "text/html"
},
{
"href": "https://informer.example.com/w/00000000-0000-4000-8000-000000000001.jpg",
"type": "image/jpeg"
},
"… 1 more items (4 total) — omitted from docs"
],
"inf:dataset": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002"
}
},
"component": {
"chart": {
"dataset": "00000000-0000-4000-8000-000000000002",
"xAxis": {
"field": "ShipCountry"
},
"series": [
{
"fn": "sum",
"field": "orderAmount"
}
],
"chartType": "column"
}
},
"permissions": {
"write": true,
"deletePinned": false
},
"id": "00000000-0000-4000-8000-000000000001",
"datasourceId": null,
"datasetId": "00000000-0000-4000-8000-000000000002",
"source": null,
"name": "Revenue by Country",
"description": null,
"defaultName": null,
"defaultDescription": null,
"embedded": false,
"pinned": false,
"layoutData": {},
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"tenant": "acme",
"ownerId": "admin",
"datasets": []
}
PUT /api/datasets/{datasetId}/visuals/{id}
Update (upsert) a visual.
Authentication: Required
Permission: dataset:addVisual (Designer or above on the owning team)
Update a visualPUT /api/datasets/admin:northwind-orders/visuals/00000000-0000-4000-8000-000000000001
Request body
{
"name": "Revenue by Ship Country",
"component": {
"chart": {
"dataset": "00000000-0000-4000-8000-000000000002",
"xAxis": {
"field": "ShipCountry"
},
"series": [
{
"fn": "sum",
"field": "orderAmount"
}
],
"chartType": "column"
}
}
}
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/visuals/00000000-0000-4000-8000-000000000001"
},
"view": [
{
"href": "https://informer.example.com/w/00000000-0000-4000-8000-000000000001.png",
"type": "image/png"
},
{
"href": "https://informer.example.com/w/00000000-0000-4000-8000-000000000001.html",
"type": "text/html"
},
{
"href": "https://informer.example.com/w/00000000-0000-4000-8000-000000000001.jpg",
"type": "image/jpeg"
},
"… 1 more items (4 total) — omitted from docs"
],
"inf:dataset": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002"
}
},
"component": {
"chart": {
"dataset": "00000000-0000-4000-8000-000000000002",
"xAxis": {
"field": "ShipCountry"
},
"series": [
{
"fn": "sum",
"field": "orderAmount"
}
],
"chartType": "column"
}
},
"permissions": {
"write": true,
"deletePinned": false
},
"id": "00000000-0000-4000-8000-000000000001",
"datasourceId": null,
"datasetId": "00000000-0000-4000-8000-000000000002",
"source": null,
"name": "Revenue by Ship Country",
"description": null,
"defaultName": null,
"defaultDescription": null,
"embedded": false,
"pinned": false,
"layoutData": {},
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"tenant": "acme",
"ownerId": "admin",
"datasets": []
}
DELETE /api/datasets/{datasetId}/visuals/{id}
Delete a visual.
Authentication: Required
Permission: dataset:deleteVisual (Designer or above on the owning team)
Delete a visualDELETE /api/datasets/admin:northwind-orders/visuals/00000000-0000-4000-8000-000000000001
Responds 200 with an empty body.
Response · 200 · no body
Responds 200 with an empty body.