DocsFAQContactSign inGet API key, free

API Reference

All requests require the X-API-Key header. Sign up for free to get your API key.

Quick Start

Your API key is pre-filled. Replace ch_YOUR_ID with the ID returned in step 2.

1. Create a live chart slot

Returns { "id": "ch_...", "embedUrl": "..." }

curl -X POST https://www.plotmarks.com/api/charts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "line",
    "output_type": "live_iframe",
    "refresh_interval": 30,
    "config": { "title": "Live Revenue", "yLabel": "Amount ($)" }
  }'

2. Push data to the chart

Full replacement on every push. Returns { ok: true }.

curl -X POST https://www.plotmarks.com/api/charts/ch_YOUR_ID/data \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plots": [
      {
        "color": "#4F46E5",
        "data": [
          { "x": "Jan", "Revenue": 4200 },
          { "x": "Feb", "Revenue": 5800 }
        ]
      }
    ]
  }'

3. Embed the chart

The chart polls for new data every 30 seconds automatically.

<iframe
  src="https://www.plotmarks.com/charts/ch_YOUR_ID"
  width="800"
  height="400"
  frameborder="0">
</iframe>

Create a chart slot

POST/api/charts

Creates a persistent chart slot and returns an embed URL. Push data to it separately. The iframe at the embed URL polls for new data automatically.

FieldTypeReq.Description
type"bar" | "line" | "pie" | "doughnut" | "scatter" | "radar"✓Chart type.
output_typestring✓"static_iframe" — persistent slot, data updated manually by pushing. "live_iframe" — persistent slot, iframe polls every refresh_interval seconds.
refresh_intervalnumber—Polling interval in seconds. Required when output_type is live_iframe. Min: 10, Max: 86400.
configobject—Optional display settings applied to the iframe chart. See Config Options below.
// Request
POST /api/charts
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "type": "line",
  "output_type": "live_iframe",
  "refresh_interval": 30,
  "config": { "title": "Live Revenue", "yLabel": "Amount ($)" }
}

// Response
{
  "id": "ch_abc123",
  "embedUrl": "https://www.plotmarks.com/charts/ch_abc123"
}

Push data to a chart slot

POST/api/charts/:id/data

Replaces all existing data for the chart with the new payload. Every push is a full replacement — there is no append or merge. The iframe picks up the new data on its next poll cycle.

FieldTypeReq.Description
plotsobject[]✓Array of plot/slice objects. See Chart Types for the exact shape per chart type.
// Request — bar chart
POST /api/charts/ch_abc123/data
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "plots": [
    {
      "color": "#4F46E5",
      "opacity": 1,
      "borderRadius": 4,
      "data": [
        { "x": "Jan", "Source": 4200 },
        { "x": "Feb", "Source": 5800 },
        { "x": "Mar", "Source": 6100 }
      ]
    },
    {
      "color": "#10B981",
      "opacity": 0.8,
      "borderRadius": 4,
      "data": [
        { "x": "Jan", "Target": 5000 },
        { "x": "Feb", "Target": 5500 },
        { "x": "Mar", "Target": 6000 }
      ]
    }
  ]
}

// Response
{ "ok": true }

Fetch chart data

GET/api/charts/:id/data

Public — no API key required. Returns the chart config and latest data payload. This is the endpoint the embedded iframe polls automatically. You do not need to call this directly.

// Response
{
  "type": "line",
  "config": { "title": "Live Revenue", "yLabel": "Amount ($)" },
  "refreshInterval": 30,
  "plots": [
    {
      "color": "#4F46E5",
      "data": [
        { "x": "Jan", "Revenue": 4200 },
        { "x": "Feb", "Revenue": 5800 }
      ]
    }
  ]
}

Embedding a chart

Each chart slot has a public embed URL returned when you create it. Drop it into an <iframe> — no API key or account required to view.

Basic embed

<iframe
  src="https://www.plotmarks.com/charts/ch_abc123"
  width="600"
  height="340"
  frameborder="0"
  style="border-radius:8px"
></iframe>

Responsive embed

Wrap in a relative container to fill the parent width and lock the aspect ratio.

<!-- 16:9 wrapper — change padding-top to adjust ratio (e.g. 75% = 4:3) -->
<div style="position:relative; width:100%; padding-top:56.25%; border-radius:8px; overflow:hidden">
  <iframe
    src="https://www.plotmarks.com/charts/ch_abc123"
    style="position:absolute; inset:0; width:100%; height:100%; border:0"
  ></iframe>
</div>

Notes

  • Live chart — the iframe polls every refresh_interval seconds and re-renders in place. No page reload needed.
  • Static chart — loads once and shows data as of page load. Refreshes on a hard reload or when you push new data and the visitor reloads.
  • Sizing — the chart fills the iframe dimensions. A minimum of 300 × 200 px is recommended; smaller sizes can clip labels.
  • No scrollbars — the embed page has no scrollbars. Set overflow:hidden on your wrapper if needed.
  • Background — the embed page background is white. For a transparent background add allow="transparency" to the iframe and set background:transparent in your CSS.

Data format

Data is sent as an array of plots. Each plot is one series on the chart with its own styling. A plot's data array holds the points — each must have an x field (axis label) and exactly one numeric y-value key, whose name becomes the legend label. See the chart type sections below for full field reference.

// Bar chart — color, opacity, borderRadius per plot
{
  "type": "bar",
  "plots": [
    { "color": "#4F46E5", "opacity": 1,   "borderRadius": 4, "data": [ { "x": "Jan", "Source": 100 }, { "x": "Feb", "Source": 200 } ] },
    { "color": "#10B981", "opacity": 0.8, "borderRadius": 4, "data": [ { "x": "Jan", "Target": 120 }, { "x": "Feb", "Target": 180 } ] }
  ]
}

// Line chart — color, fill, thickness, style per plot
{
  "type": "line",
  "plots": [
    {
      "color": "#4F46E5",
      "fill": true,
      "thickness": 2,
      "style": "solid",
      "data": [ { "x": "Jan", "Source": 100 }, { "x": "Feb", "Source": 200 } ]
    },
    {
      "color": "#10B981",
      "fill": false,
      "thickness": 2,
      "style": "dashed",
      "data": [ { "x": "Jan", "Target": 120 }, { "x": "Feb", "Target": 180 } ]
    }
  ]
}

// Pie chart — each entry in "plots" is a slice (label, value, color)
{
  "type": "pie",
  "plots": [
    { "label": "Organic Search", "value": 38, "color": "#4F46E5" },
    { "label": "Direct",         "value": 24, "color": "#10B981" },
    { "label": "Referral",       "value": 21, "color": "#F59E0B" },
    { "label": "Social",         "value": 17, "color": "#6B7280" }
  ]
}

// Doughnut chart — same slice format; cutout controls the hole size
{
  "type": "doughnut",
  "config": { "cutout": "60%" },
  "plots": [
    { "label": "Organic Search", "value": 38, "color": "#4F46E5" },
    { "label": "Direct",         "value": 24, "color": "#10B981" },
    { "label": "Referral",       "value": 21, "color": "#F59E0B" },
    { "label": "Social",         "value": 17, "color": "#6B7280" }
  ]
}

// Scatter chart — each point has a numeric x and y (e.g. load time vs bounce rate)
{
  "type": "scatter",
  "plots": [
    {
      "label": "Mobile",
      "color": "#4F46E5",
      "pointRadius": 4,
      "data": [
        { "x": 1.2, "y": 42 },
        { "x": 1.8, "y": 56 },
        { "x": 2.5, "y": 68 }
      ]
    },
    {
      "label": "Desktop",
      "color": "#10B981",
      "pointRadius": 4,
      "data": [
        { "x": 0.7, "y": 24 },
        { "x": 1.1, "y": 33 },
        { "x": 1.6, "y": 47 }
      ]
    }
  ]
}

// Radar chart — each point maps an axis name to a value (e.g. team performance)
{
  "type": "radar",
  "plots": [
    {
      "label": "Frontend",
      "color": "#4F46E5",
      "fill": true,
      "data": [
        { "axis": "Velocity",      "value": 82 },
        { "axis": "Code quality",  "value": 75 },
        { "axis": "Test coverage", "value": 68 },
        { "axis": "Collaboration", "value": 91 },
        { "axis": "Documentation", "value": 70 }
      ]
    },
    {
      "label": "Backend",
      "color": "#10B981",
      "fill": true,
      "data": [
        { "axis": "Velocity",      "value": 70 },
        { "axis": "Code quality",  "value": 88 },
        { "axis": "Test coverage", "value": 85 },
        { "axis": "Collaboration", "value": 76 },
        { "axis": "Documentation", "value": 64 }
      ]
    }
  ]
}

// Rules (bar / line):
// — Each plot must have a "color" (6-digit hex, e.g. "#4F46E5")
// — Every data point must have an "x" field
// — Each point must have exactly one y-value key (a number)
// — Between 1 and 5 plots per chart; max 1,000 points per plot

// Rules (pie / doughnut):
// — Each slice must have "label", "value" (number), and "color" (hex)
// — Between 2 and 20 slices per chart

Bar chart

Grouped or stacked vertical (or horizontal) bars. Each entry in plots is one series.

Config fields

Set in the config object when creating the chart slot or pushing data.

FieldTypeReq.Description
titlestring—Chart title displayed above the chart. Max 100 characters.
legendboolean—Show or hide the legend. Default: true when there are 2+ series.
xLabelstring—Label for the x-axis. Max 50 characters.
yLabelstring—Label for the y-axis. Max 50 characters.
horizontalboolean—Render as a horizontal bar chart. Default: false.
stackedboolean—Stack bars instead of grouping. Default: false.
yMinnumber—Explicit y-axis minimum. Overrides automatic scaling.
yMaxnumber—Explicit y-axis maximum.

Plot fields

Set on each object inside the plots array when pushing data.

FieldTypeReq.Description
colorstring✓6-digit hex color for this series, e.g. "#4F46E5".
opacitynumber—Bar fill transparency. 0–1. Default: 1.
borderRadiusnumber—Rounded corner radius in px. 0–20. Default: 0.
borderWidthnumber—Bar border thickness in px. 0–10. Default: 1.
showAllBordersboolean—Show a border on all four sides of each bar. Default: false.
dataobject[]✓Points — each must have "x" (axis label) and exactly one numeric y-value key.

Line chart

Line chart with optional area fill. Each entry in plots is one series.

Config fields

Set in the config object when creating the chart slot or pushing data.

FieldTypeReq.Description
titlestring—Chart title displayed above the chart. Max 100 characters.
legendboolean—Show or hide the legend. Default: true when there are 2+ series.
xLabelstring—Label for the x-axis. Max 50 characters.
yLabelstring—Label for the y-axis. Max 50 characters.
beginAtZeroboolean—Force the y-axis to start at zero. Default: true.
yMinnumber—Explicit y-axis minimum. Overrides beginAtZero.
yMaxnumber—Explicit y-axis maximum.

Plot fields

Set on each object inside the plots array when pushing data.

FieldTypeReq.Description
colorstring✓6-digit hex color for this series, e.g. "#4F46E5".
fillboolean—Fill the area below the line. Default: true.
thicknessnumber—Line width in px. 1–10. Default: 2.
stylestring—"solid" | "dashed" | "dotted". Default: "solid".
tensionnumber—Curve smoothness. 0 = straight lines, 1 = maximum curve. Default: 0.4.
pointRadiusnumber—Data point dot size in px. 0 to hide dots. Default: 3.
dataobject[]✓Points — each must have "x" (axis label) and exactly one numeric y-value key.

Pie chart

Full-circle pie chart. Each entry in plots is one slice.

Config fields

Set in the config object when creating the chart slot or pushing data.

FieldTypeReq.Description
titlestring—Chart title displayed above the chart. Max 100 characters.
legendboolean—Show or hide the legend. Default: true when there are 2+ slices.
circumferencenumber—Arc sweep in degrees. 0–360. Default: 360 (full circle).
rotationnumber—Starting angle of the first slice in degrees. -360–360. Default: 0 (3 o’clock).

Plot fields

Set on each object inside the plots array when pushing data.

FieldTypeReq.Description
labelstring✓Slice label shown in the legend and tooltip.
valuenumber✓Numeric value for this slice.
colorstring✓6-digit hex color for this slice, e.g. "#4F46E5".
hoverOffsetnumber—How far the slice pops out on hover in px. 0–30. Default: 8.
offsetnumber—Permanent explode offset in px. 0–50. Default: 0.

Doughnut chart

Pie chart with a hollow centre. Same plot format as pie.

Config fields

Set in the config object when creating the chart slot or pushing data.

FieldTypeReq.Description
titlestring—Chart title displayed above the chart. Max 100 characters.
legendboolean—Show or hide the legend. Default: true when there are 2+ slices.
circumferencenumber—Arc sweep in degrees. 0–360. Default: 360 (full circle).
rotationnumber—Starting angle of the first slice in degrees. -360–360. Default: 0 (3 o’clock).
cutoutstring | number—Size of the hollow centre. CSS percentage string e.g. "60%" or a pixel number. Default: "50%".

Plot fields

Set on each object inside the plots array when pushing data.

FieldTypeReq.Description
labelstring✓Slice label shown in the legend and tooltip.
valuenumber✓Numeric value for this slice.
colorstring✓6-digit hex color for this slice, e.g. "#4F46E5".
hoverOffsetnumber—How far the slice pops out on hover in px. 0–30. Default: 8.
offsetnumber—Permanent explode offset in px. 0–50. Default: 0.

Scatter chart

X/Y scatter plot. Both axes are numeric. Each entry in plots is one series.

Config fields

Set in the config object when creating the chart slot or pushing data.

FieldTypeReq.Description
titlestring—Chart title displayed above the chart. Max 100 characters.
legendboolean—Show or hide the legend. Default: true when there are 2+ series.
xLabelstring—Label for the x-axis. Max 50 characters.
yLabelstring—Label for the y-axis. Max 50 characters.
xMinnumber—Explicit x-axis minimum.
xMaxnumber—Explicit x-axis maximum.
yMinnumber—Explicit y-axis minimum.
yMaxnumber—Explicit y-axis maximum.

Plot fields

Set on each object inside the plots array when pushing data.

FieldTypeReq.Description
labelstring—Series label shown in the legend. Default: "Series N".
colorstring✓6-digit hex color for this series, e.g. "#4F46E5".
pointRadiusnumber—Point size in px. 1–20. Default: 4.
pointStylestring—"circle" | "cross" | "triangle" | "rect" | "star". Default: "circle".
showLineboolean—Connect points with a line (connected scatter). Default: false.
opacitynumber—Point fill transparency. 0–1. Default: 0.8.
dataobject[]✓Points — each must have numeric "x" and "y" fields.

Radar chart

Spider/radar chart. Each entry in plots is one series. All series must share the same axes in the same order.

Config fields

Set in the config object when creating the chart slot or pushing data.

FieldTypeReq.Description
titlestring—Chart title displayed above the chart. Max 100 characters.
legendboolean—Show or hide the legend. Default: true when there are 2+ series.
maxnumber—Maximum value on the radial scale. Fixes all axes to the same range, e.g. 100.

Plot fields

Set on each object inside the plots array when pushing data.

FieldTypeReq.Description
labelstring—Series label shown in the legend. Default: "Series N".
colorstring✓6-digit hex color for this series, e.g. "#4F46E5".
fillboolean—Fill the area inside the radar shape. Default: true.
opacitynumber—Fill transparency. 0–1. Default: 0.2.
thicknessnumber—Line width in px. 1–10. Default: 2.
pointRadiusnumber—Vertex dot size in px. 0–20. Default: 3. Set to 0 to hide.
stylestring—"solid" | "dashed" | "dotted". Default: "solid".
dataobject[]✓Points — each must have "axis" (string) and "value" (number). Min 3, max 20 axes.