Skip to content
One command to visualize your data

Merge two or more Vizb Datasets.

POST
/merge
curl --request POST \
  --url http://127.0.0.1:8080/merge \
  --header 'Content-Type: application/json' \
  --data '{ "tagAxis": "x", "datasets": [ { "name": "Sort", "tag": "v1", "axes": [ { "key": "name" }, { "key": "y" } ], "settings": [ { "type": "bar" } ], "data": [ { "name": "quicksort", "yAxis": "12" } ] }, { "name": "Sort", "tag": "v2", "axes": [ { "key": "name" }, { "key": "y" } ], "settings": [ { "type": "bar" } ], "data": [ { "name": "quicksort", "yAxis": "10" } ] } ] }'

The operation is atomic: every supplied Dataset must be valid and take part in the merge. Server file paths and directory scanning are intentionally not part of this API.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
datasets
required
Array<object>
>= 2 items
object
id
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
os
string
arch
string
pkg
string
description
string
meta
object
cpu
object
name
string
cores
integer
os
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
tagAxis
string
default: name
Allowed values: name x y z
Examples
ExampletaggedDatasets

Merge two tagged runs and inject tags on the x axis.

{
  "tagAxis": "x",
  "datasets": [
    {
      "name": "Sort",
      "tag": "v1",
      "axes": [
        {
          "key": "name"
        },
        {
          "key": "y"
        }
      ],
      "settings": [
        {
          "type": "bar"
        }
      ],
      "data": [
        {
          "name": "quicksort",
          "yAxis": "12"
        }
      ]
    },
    {
      "name": "Sort",
      "tag": "v2",
      "axes": [
        {
          "key": "name"
        },
        {
          "key": "y"
        }
      ],
      "settings": [
        {
          "type": "bar"
        }
      ],
      "data": [
        {
          "name": "quicksort",
          "yAxis": "10"
        }
      ]
    }
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

Merge succeeded. The response is always an array, including when it contains one Dataset.

Media typeapplication/json
Array<object>
object
id
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
os
string
arch
string
pkg
string
description
string
meta
object
cpu
object
name
string
cores
integer
os
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
ExamplemergedDatasets
[
  {
    "name": "Sort",
    "axes": [
      {
        "key": "name"
      },
      {
        "key": "x"
      },
      {
        "key": "y"
      }
    ],
    "settings": [
      {
        "type": "bar"
      }
    ],
    "data": [
      {
        "name": "quicksort",
        "xAxis": "v1",
        "yAxis": "12"
      },
      {
        "name": "quicksort",
        "xAxis": "v2",
        "yAxis": "10"
      }
    ]
  }
]

400

Section titled “400”

The request body is not a single valid JSON value.

Media typeapplication/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

Section titled “406”

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

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
instance
string format: uri-reference
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

413

Section titled “413”

The request body exceeds the 10 MiB limit.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
instance
string format: uri-reference
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

415

Section titled “415”

The request Content-Type is not application/json.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
instance
string format: uri-reference
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

422

Section titled “422”

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

Media typeapplication/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."
    }
  ]
}

500

Section titled “500”

An unexpected server-side failure occurred.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
instance
string format: uri-reference
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}