Convert supported input into a Vizb Dataset or self-contained HTML.

POST

const url = 'http://127.0.0.1:8080/';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"input":"region,latency\nwest,12\neast,18\n","id":"api-latency","name":"API latency","description":"Latency by region","tag":"v2","theme":"westeros","parser":"csv","select":["region,latency"],"charts":{"types":["bar","line"],"configs":[{"type":"bar","showLabels":true}]},"output":{"format":"dataset"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://127.0.0.1:8080/ \
  --header 'Content-Type: application/json' \
  --data '{ "input": "region,latency\nwest,12\neast,18\n", "id": "api-latency", "name": "API latency", "description": "Latency by region", "tag": "v2", "theme": "westeros", "parser": "csv", "select": [ "region,latency" ], "charts": { "types": [ "bar", "line" ], "configs": [ { "type": "bar", "showLabels": true } ] }, "output": { "format": "dataset" } }'

Input is inline text or JSON. Parser, grouping, units, selection, and chart options are structured request data. Unknown or inapplicable options are rejected; CLI-style option strings are not accepted.

Request Body^required

application/json

object

input

required

One of:

string

Dataset identifier used by UI deep links.

string

name

Dataset display name.

string

default: Comparisons

title

Chart title used only when grouping.colAxis produces one chart; independent of name.

string

description

Dataset description.

string

tag

Dataset tag or run identifier.

string

themes

Data-owned theme catalog embedded on the converted Dataset. When non-empty, themes[0] is the active theme. Prefer this over the legacy theme string. Built-in "default" is not embedded (UI owns it).

Array<object>

Fully expanded color theme. On Dataset and convert responses, themes[0] is the active theme when the catalog is non-empty.

object

name

required

Theme identifier used by the UI selector.

string

>= 1 characters

colors

required

Categorical series palette.

Array<string>

>= 1 items

visualMapColors

required

Continuous gradient pair (exactly two colors).

Array<string>

>= 2 items <= 2 items

theme

Legacy single theme name, structured theme, or comma-separated hex palette. Expanded into themes when themes is omitted or empty. Prefer themes for new clients.

string

>= 1 characters

parser

string

default: auto

Allowed values: auto csv json go javascript rust

grouping

object

pattern

string

>= 1 characters

regex

string

columns

Array<string>

filter

string

colAxis

Place grouped numeric column names on this free axis so they share one chart.

string

Allowed values: n x y z

units

object

memory

string

Allowed values: b B KB MB GB

time

string

Allowed values: ns us ms s

number

string

Allowed values: K M B T

round

Round numeric values to 2 decimal places in the output data

boolean

select

Structured column selections; each item is one select expression.

Array<string>

jsonPath

JSON-only path to a nested array.

string

charts

object

types

Array<string>

>= 1 items unique items

Allowed values: bar line scatter pie heatmap radar sankey chord

configs

Array

One of: discriminator: type

object

type

required

Allowed value: bar

swap

string

sort

object

enabled

required

boolean

order

required

string

Allowed values: asc desc

scale

One of:

string
object

string

Allowed values: linear log

stack

boolean

showLabels

boolean

borderRadius

Array<integer>

>= 1 items <= 4 items

threeDRotate

boolean

threeD

boolean

threeDVisualMap

boolean

horizontal

boolean

background

object

active

boolean

color

string

borderColor

string

borderWidth

number

borderType

string

Allowed values: solid dashed dotted

borderRadius

One of:

integer
Array<integer>

integer

shadowBlur

number

shadowColor

string

shadowOffsetX

number

shadowOffsetY

number

opacity

number

<= 1

stat

object

enabled

required

boolean

math

required

Array<string>

Allowed values: counts center spread extremes shape percentiles confidence correlations

output

object

format

string

default: dataset

Allowed values: dataset html

Examples

Convert inline CSV into a Dataset.

{
  "input": "region,latency\nwest,12\neast,18\n",
  "id": "api-latency",
  "name": "API latency",
  "description": "Latency by region",
  "tag": "v2",
  "theme": "westeros",
  "parser": "csv",
  "select": [
    "region,latency"
  ],
  "charts": {
    "types": [
      "bar",
      "line"
    ],
    "configs": [
      {
        "type": "bar",
        "showLabels": true
      }
    ]
  },
  "output": {
    "format": "dataset"
  }
}

Convert wide competitor columns into one titled chart.

{
  "input": "load,default,chi\n100,3103.62,3103.73\n1000,32423.67,32421.28\n",
  "name": "Q1 release",
  "title": "Framework throughput",
  "parser": "csv",
  "grouping": {
    "pattern": "y",
    "columns": [
      "load"
    ],
    "colAxis": "x"
  },
  "charts": {
    "types": [
      "bar"
    ]
  }
}

Convert native JSON input into self-contained HTML.

{
  "input": [
    {
      "region": "west",
      "latency": 12
    },
    {
      "region": "east",
      "latency": 18
    }
  ],
  "name": "API latency",
  "parser": "json",
  "grouping": {
    "pattern": "x",
    "columns": [
      "region"
    ]
  },
  "charts": {
    "types": [
      "bar"
    ],
    "configs": [
      {
        "type": "bar",
        "showLabels": true
      }
    ]
  },
  "output": {
    "format": "html"
  }
}

Responses

200

Conversion succeeded. The response media type is selected by output.format and must be acceptable to the client.

object

string

tag

string

timestamp

string

name

required

string

themes

Data-owned theme catalog. When non-empty, themes[0] is the active theme. New writers emit themes only; legacy theme is migrated on load.

Array<object>

Fully expanded color theme. On Dataset and convert responses, themes[0] is the active theme when the catalog is non-empty.

object

name

required

Theme identifier used by the UI selector.

string

>= 1 characters

colors

required

Categorical series palette.

Array<string>

>= 1 items

visualMapColors

required

Continuous gradient pair (exactly two colors).

Array<string>

>= 2 items <= 2 items

theme

Legacy single theme name or palette. Migrated into themes when themes is empty; omitted from new output after migration.

string

history

Array<object>

object

tag

required

string

timestamp

required

string

meta

object

cpu

object

name

string

cores

integer

string

arch

string

pkg

string

description

string

meta

object

cpu

object

name

string

cores

integer

string

arch

string

pkg

string

axes

required

Array<object>

object

key

required

string

Allowed values: name x y z

label

string

type

string

Allowed values: "" value

settings

required

Each chart type may appear at most once.

data

required

Array<object>

object

name

string

xAxis

string

yAxis

string

zAxis

string

metric

string

stats

Array<object>

object

type

string

value

number

symbol

string

preserveRows

boolean

Examples

convertedDataset

{
  "id": "api-latency",
  "name": "API latency",
  "description": "Latency by region",
  "tag": "v2",
  "themes": [
    {
      "name": "westeros",
      "colors": [
        "#516b91",
        "#59c4e6",
        "#edafda",
        "#93b7e3",
        "#a5e7f0",
        "#cbb0e3",
        "#3f5575",
        "#41a7cb",
        "#d58fc4",
        "#789bc7"
      ],
      "visualMapColors": [
        "#59c4e6",
        "#d58fc4"
      ]
    }
  ],
  "axes": [
    {
      "key": "name"
    },
    {
      "key": "y",
      "type": "value"
    }
  ],
  "settings": [
    {
      "type": "bar",
      "showLabels": true
    },
    {
      "type": "line"
    }
  ],
  "data": [
    {
      "name": "west",
      "yAxis": "12"
    },
    {
      "name": "east",
      "yAxis": "18"
    }
  ]
}

string

Examples

convertedHTML

<!doctype html><html><head><title>Vizb</title></head><body>...</body></html>

400

The request body is not a single valid JSON value.

application/problem+json

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

required

string

instance

string format: uri-reference

errors

required

Array<object>

>= 1 items

object

location

required

string

Allowed values: body header query

path

required

JSON Pointer or header/query name.

string

code

required

string

message

required

string

Example

{
  "errors": [
    {
      "location": "body"
    }
  ]
}

406

The request's Accept header does not allow an operation's selected response media type.

application/problem+json

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

required

string

instance

string format: uri-reference

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

413

The request body exceeds the 10 MiB limit.

application/problem+json

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

required

string

instance

string format: uri-reference

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

415

The request Content-Type is not application/json.

application/problem+json

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

required

string

instance

string format: uri-reference

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

422

Valid JSON violates request schema or semantic constraints, or the supplied input cannot be processed.

application/problem+json

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

required

string

instance

string format: uri-reference

Examples

{
  "type": "https://vizb.goptics.org/problems/validation",
  "title": "Unprocessable content",
  "status": 422,
  "detail": "Request validation failed.",
  "instance": "/merge",
  "errors": [
    {
      "location": "body",
      "path": "/tagAxis",
      "code": "invalid_enum",
      "message": "tagAxis must be one of name, x, y, or z."
    }
  ]
}

{
  "type": "https://vizb.goptics.org/problems/processing",
  "title": "Input processing failed",
  "status": 422,
  "detail": "The selected columns could not be read from the CSV input.",
  "instance": "/"
}

500

An unexpected server-side failure occurred.

application/problem+json

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

required

string

instance

string format: uri-reference

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

Convert supported input into a Vizb Dataset or self-contained HTML.

Request Bodyrequired

Examples

Responses

200

Examples

Examples

400

Example

406

Examplegenerated

413

Examplegenerated

415

Examplegenerated

422

Examples

500

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated