{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/linkbreakers-com/json-schema/linkbreakers-com-create-dashboard-request-schema.json",
  "title": "CreateDashboardRequest",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/linkbreakers-com-analytics-dashboard-api-openapi.yml#/components/schemas/CreateDashboardRequest",
  "properties": {
    "config": {
      "$ref": "#/$defs/DashboardConfig",
      "description": "Initial widgets. Empty means the dashboard starts with none, because its\ncontents are normally agreed with the assistant before anything is created."
    },
    "id": {
      "description": "Client-supplied dashboard id. Generated server-side when empty.",
      "type": "string"
    },
    "linkId": {
      "description": "Link to scope this dashboard to. Empty creates the workspace-wide dashboard.",
      "type": "string"
    },
    "name": {
      "description": "Display name. Defaults to \"Default Dashboard\" when empty.",
      "type": "string"
    },
    "useDefaultWidgets": {
      "description": "Fill the dashboard with a starter set instead of leaving it empty, for a\ndashboard made in one step rather than agreed in a conversation. Without\nlink_id it is the workspace set (scans over time, top links, geography,\ntechnology and more). With link_id it is the link set: scans over time,\ngeography, technology, peak hours, and new versus returning visitors, which\nis everything any link records. The service applies it to any link; whether\nit suits one is the caller's judgement, since a workflow that collects\nanswers deserves widgets for them. Ignored when config is set, and hidden\nfrom the assistant, which agrees its widgets with the user and would\notherwise stack them on top of these.",
      "type": "boolean"
    }
  },
  "type": "object",
  "$defs": {
    "DashboardConfig": {
      "properties": {
        "gridColumns": {
          "description": "Width of the grid the widget positions and sizes are expressed in.\nAbsent or 0 means the legacy two-column grid, where w=1 is half-width and\nw=2 is full-width. New dashboards use 8.",
          "format": "int32",
          "type": "integer"
        },
        "widgets": {
          "items": {
            "$ref": "#/$defs/DashboardWidget",
            "type": "object"
          },
          "type": "array"
        }
      },
      "title": "DashboardConfig is the structured configuration for a dashboard",
      "type": "object"
    },
    "DashboardWidget": {
      "properties": {
        "dataSource": {
          "$ref": "#/$defs/WidgetDataSource",
          "title": "What data to fetch"
        },
        "id": {
          "title": "Unique widget identifier",
          "type": "string"
        },
        "position": {
          "$ref": "#/$defs/WidgetPosition",
          "title": "Grid position"
        },
        "size": {
          "$ref": "#/$defs/WidgetSize",
          "title": "Grid size"
        },
        "title": {
          "title": "Display title",
          "type": "string"
        },
        "visualization": {
          "$ref": "#/$defs/WidgetVisualization",
          "title": "How to visualize the data"
        }
      },
      "title": "DashboardWidget represents a single monitor widget on the dashboard",
      "type": "object"
    },
    "WidgetDataSource": {
      "properties": {
        "endpoint": {
          "title": "The API endpoint path, e.g. \"/v1/timeseries/events\"",
          "type": "string"
        },
        "method": {
          "title": "HTTP method: \"GET\" or \"POST\"",
          "type": "string"
        },
        "params": {
          "title": "Static parameters always sent with the request",
          "type": "object"
        },
        "responseDataPath": {
          "title": "Dot-notation path to the data array in the response, e.g. \"timeSeries.data\" or \"data\"\nEmpty string means the root object is the data (for single-value endpoints like metrics)",
          "type": "string"
        },
        "usesDateRange": {
          "title": "Whether the dashboard date range should be injected (startDate/endDate)",
          "type": "boolean"
        },
        "usesInterval": {
          "title": "Whether interval calculation should be injected (for time-bucketed data)",
          "type": "boolean"
        }
      },
      "title": "WidgetDataSource describes which API endpoint to call and how to pass parameters",
      "type": "object"
    },
    "WidgetFieldMapping": {
      "properties": {
        "chartRole": {
          "title": "Role in the chart: \"label\", \"value\", \"value2\", \"timestamp\", \"category\"",
          "type": "string"
        },
        "displayLabel": {
          "title": "Display label shown in legend and tooltips",
          "type": "string"
        },
        "sourceField": {
          "title": "Field name in the API response objects, e.g. \"eventCount\", \"timestamp\"",
          "type": "string"
        }
      },
      "title": "WidgetFieldMapping maps a field from the API response to a chart role",
      "type": "object"
    },
    "WidgetPosition": {
      "properties": {
        "x": {
          "format": "int32",
          "title": "Leftmost column the widget occupies, 0-based",
          "type": "integer"
        },
        "y": {
          "format": "int32",
          "title": "Topmost row the widget occupies, 0-based",
          "type": "integer"
        }
      },
      "title": "WidgetPosition defines where a widget sits in the grid",
      "type": "object"
    },
    "WidgetSize": {
      "properties": {
        "h": {
          "format": "int32",
          "title": "Row span, one row being roughly 80px tall",
          "type": "integer"
        },
        "w": {
          "description": "Column span. In an 8-column config: 8 = full width, 4 = half, 2 = quarter.",
          "format": "int32",
          "type": "integer"
        }
      },
      "title": "WidgetSize defines how many grid cells a widget spans",
      "type": "object"
    },
    "WidgetTab": {
      "properties": {
        "label": {
          "title": "Tab display label",
          "type": "string"
        },
        "mode": {
          "$ref": "#/$defs/WidgetTabMode",
          "description": "How this tab produces its content. Absent means data."
        },
        "params": {
          "title": "Params that override the base data source params when this tab is active",
          "type": "object"
        },
        "view": {
          "$ref": "#/$defs/WidgetTabView",
          "description": "How it is drawn. The map used to be chosen by a tab literally labelled\n\"Map\", so renaming it to \"Carte\" lost the map and a data tab called\n\"Site Map clicks\" was hijacked into one."
        }
      },
      "title": "WidgetTab represents a tab for grouped views in a widget",
      "type": "object"
    },
    "WidgetTabMode": {
      "default": "WIDGET_TAB_MODE_UNSPECIFIED",
      "description": "WidgetTabMode says how a tab produces what it shows.\n\n - WIDGET_TAB_MODE_UNSPECIFIED: Fetches the widget's data source with this tab's params, on switch.\n - WIDGET_TAB_MODE_ASSISTANT_SUMMARY: Shows an assistant's analysis of the widget's values. Runs only when the user\nasks, because it costs platform credits, and its result is stored rather\nthan regenerated on every view.",
      "enum": [
        "WIDGET_TAB_MODE_UNSPECIFIED",
        "WIDGET_TAB_MODE_DATA",
        "WIDGET_TAB_MODE_ASSISTANT_SUMMARY"
      ],
      "type": "string"
    },
    "WidgetTabView": {
      "default": "WIDGET_TAB_VIEW_UNSPECIFIED",
      "description": "WidgetTabView says how a tab draws what it fetched.\n\n - WIDGET_TAB_VIEW_UNSPECIFIED: The widget's own chart type.\n - WIDGET_TAB_VIEW_MAP: A world map, which needs rows carrying a country code.",
      "enum": [
        "WIDGET_TAB_VIEW_UNSPECIFIED",
        "WIDGET_TAB_VIEW_CHART",
        "WIDGET_TAB_VIEW_MAP"
      ],
      "type": "string"
    },
    "WidgetVisualization": {
      "properties": {
        "chartType": {
          "title": "Chart type: \"bar\", \"horizontal_bar\", \"line\", \"area\", \"stacked_area\", \"pie\", \"number\", \"list\", \"funnel\"",
          "type": "string"
        },
        "colors": {
          "items": {
            "type": "string"
          },
          "title": "Ordered list of colors for chart series/segments",
          "type": "array"
        },
        "fieldMappings": {
          "items": {
            "$ref": "#/$defs/WidgetFieldMapping",
            "type": "object"
          },
          "title": "Maps response fields to chart roles",
          "type": "array"
        },
        "tabs": {
          "description": "Optional tabs for grouped views. Each tab has label and params that override the base params.",
          "items": {
            "$ref": "#/$defs/WidgetTab",
            "type": "object"
          },
          "type": "array"
        }
      },
      "title": "WidgetVisualization describes how to render the fetched data",
      "type": "object"
    }
  }
}