Skip to main content
PUT
/
v0
/
boards
/
{boardId}
/
charts
/
{chartId}
Edit chart
curl --request PUT \
  --url https://api.formo.so/v0/boards/{boardId}/charts/{chartId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chartId": "<string>",
  "projectId": "<string>",
  "chart_type": "table",
  "title": "<string>",
  "query": "<string>",
  "description": "<string>",
  "x_axis": "<string>",
  "y_axis": [
    "<string>"
  ],
  "group_by": "<string>",
  "steps": [
    {
      "type": "event",
      "event": "<string>"
    }
  ],
  "settings": {
    "funnelType": "closed",
    "breakdown": "device",
    "endStep": {
      "type": "event",
      "event": "<string>"
    },
    "maxSteps": 3,
    "nodesPerStep": 5,
    "filters": "<string>",
    "retentionFilter": {
      "type": "event",
      "event": "<string>"
    },
    "retentionUserFilters": [
      {
        "operand": "<string>",
        "operator": "equals",
        "value": "<string>"
      }
    ]
  }
}
'
{
  "isSuccess": true,
  "data": "<string>"
}

Authorizations

​
Authorization
string
header
required

Workspace API key (e.g. formo_xxx). Create one in the Formo dashboard under Team Settings > API Keys.

Path Parameters

​
boardId
string
required
​
chartId
string
required

Body

application/json

Request body for updating an existing chart.

​
chartId
string
required

ID of the chart to update.

​
projectId
string
required

Project the chart belongs to.

​
chart_type
enum<string>
required

Visualization type. Determines which other fields are required:

chart_typeExtra required fields
tablequery
numberquery (must return 1 row × 1 column)
barquery, x_axis, y_axis (≥ 1)
linequery, x_axis, y_axis (≥ 1)
piequery, y_axis (exactly 1)
stackedquery, x_axis, y_axis (exactly 1), group_by
funnelsteps (≥ 2), query placeholder "SELECT 1"
user_pathsquery, settings.startStep
retentionnone (query ignored)
Available options:
table,
number,
funnel,
bar,
line,
pie,
stacked,
user_paths,
retention
​
title
string
required

Display name shown on the chart and board.

Minimum string length: 1
​
query
string

SQL query that powers the chart.

  • funnel — pass "SELECT 1"; the actual query is auto-generated from steps.
  • retention — can be omitted or pass ""; data is fetched from the retention pipe directly.
  • All other types — required; must be a valid SQL string.
Minimum string length: 1
​
description
string

Optional description.

​
x_axis
string

Column name for the X axis. Required for bar, line, and stacked.

​
y_axis
string[]

Column name(s) used as Y axis metrics.

  • bar / line — at least 1 element required.
  • pie / stacked — exactly 1 element required.
​
group_by
string

Column to group / stack series by. Required for stacked.

​
steps
object[]

Ordered list of funnel steps. Required for funnel (minimum 2 steps).

Each element is a FunnelStep — add property filters as extra keys on the step object (e.g. "rdns": { "op": "equals", "value": "io.metamask" }).

Minimum array length: 2
​
settings
object

Chart-type-specific configuration. The fields that apply depend on chart_type:

  • funnel: funnelType, conversionWindow, breakdown
  • user_paths: startStep, endStep, maxSteps, nodesPerStep, conversionWindow, filters
  • retention: retentionFilter, retentionUserFilters

All fields are optional at the schema level; see per-type validation rules for which are functionally required.

Response

200 - application/json

Chart updated

​
isSuccess
boolean
​
data
string

Chart ID