Skip to main content
POST
/
v0
/
boards
/
{boardId}
/
charts
curl --request POST \
  --url https://api.formo.so/v0/boards/{boardId}/charts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "projectId": "proj_abc",
  "query": "SELECT 1",
  "chart_type": "funnel",
  "title": "Onboarding Funnel",
  "steps": [
    {
      "type": "event",
      "event": "page"
    },
    {
      "type": "event",
      "event": "connect"
    },
    {
      "type": "event",
      "event": "transaction"
    }
  ],
  "settings": {
    "funnelType": "closed",
    "conversionWindow": {
      "value": 7,
      "unit": "day"
    }
  }
}
'
{
  "id": "<string>",
  "title": "<string>",
  "query": "<string>",
  "project_id": "<string>",
  "board_id": "<string>",
  "description": "<string>",
  "x_axis": "<string>",
  "y_axis": [
    "<string>"
  ],
  "group_by": "<string>",
  "steps": [
    {
      "event": "<string>"
    }
  ],
  "settings": {
    "funnelType": "closed",
    "conversionWindow": {
      "value": 2
    },
    "startStep": {
      "event": "<string>"
    },
    "endStep": {
      "event": "<string>"
    },
    "maxSteps": 3,
    "nodesPerStep": 5,
    "filters": "<string>",
    "retentionFilter": {
      "event": "<string>"
    },
    "retentionUserFilters": [
      {
        "field": "<string>",
        "value": "<string>"
      }
    ],
    "retentionSignalType": "event",
    "retentionLabelSignal": {
      "tag_id": "<string>",
      "op": "greater",
      "value": "<string>",
      "chain_id": ""
    }
  }
}

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

Body

application/json

Request body for creating a chart.

​
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 automatically.
  • 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, retentionSignalType, retentionLabelSignal

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

Response

201 - application/json

Chart created

A saved chart attached to a board.

​
id
string
required
​
chart_type
enum<string>
required

Visualization type.

Available options:
table,
number,
funnel,
bar,
line,
pie,
stacked,
user_paths,
retention
​
title
string
required
​
query
string
required

SQL query powering the chart. For funnel and retention charts this is a system-managed placeholder.

​
project_id
string
required
​
board_id
string
required
​
description
string | null
​
x_axis
string | null

Column used as the X axis.

​
y_axis
string[] | null

Column(s) used as Y axis metric(s).

​
group_by
string | null

Column used to group/stack series.

​
steps
object[] | null

Ordered list of funnel steps. Only present when chart_type is funnel.

​
settings
object

Type-specific configuration. See ChartSettings for all fields.