> ## Documentation Index > Fetch the complete documentation index at: https://docs.upsolve.ai/llms.txt > Use this file to discover all available pages before exploring further. # Save Chart from Chat > Persists a chart configuration produced by the chat endpoint's generateChart tool so it can be added to dashboards. Pass the chartConfig object exactly as it appears in the chat stream's tool result. Returns a chartId that can be passed directly to the add-charts-to-dashboard endpoint. Authenticate with a project user JWT (from the projects/user-token endpoint), a tenant JWT, or an Upsolve API key. ## OpenAPI ````yaml post /v1/api/chart/save-from-chat openapi: 3.1.0 info: title: Upsolve API version: 1.4.2 servers: - url: https://api.upsolve.ai security: [] tags: [] paths: /v1/api/chart/save-from-chat: post: summary: Save a chart generated by the AI chat agent description: >- Persists a chart configuration produced by the chat endpoint's generateChart tool so it can be added to dashboards. Pass the chartConfig object exactly as it appears in the chat stream's tool result. Returns a chartId that can be passed directly to the add-charts-to-dashboard endpoint. Authenticate with a project user JWT (from the projects/user-token endpoint), a tenant JWT, or an Upsolve API key. operationId: PostV1ApiChartSaveFromChat requestBody: description: POST /v1/api/chart/save-from-chat Request body content: application/json: schema: allOf: - type: object properties: apiKey: description: >- Upsolve API key, generated under Account → Developer settings in the Upsolve Hub. Keys are user-scoped: pass organizationId alongside the key to select which org to act on. type: string minLength: 1 organizationId: type: string description: >- The ID of the organization. Required when using Supabase JWT authentication. connectionId: type: string description: The ID of the connection a guest has access to - type: object properties: chartConfig: type: object properties: title: type: string description: >- Descriptive title for the chart that clearly explains what data is being visualized. Should be concise but informative, e.g., 'Monthly Sales Revenue by Region', 'User Engagement Trends Over Time' type: type: string enum: - line - bar - area - scatter - pie - donut - advancedPie - table - basicTable - statCard - kpiCard - heatMap - map - combo description: >- Visualization type that best represents the data pattern. Choose based on data characteristics: LINE (trends over time), BAR (categorical comparisons), AREA (cumulative trends), SCATTER (correlations between 2+ metrics), PIE/DONUT (part-to-whole with 1 dimension + 1 measure), TABLE (detailed data view), STATCARD/KPICARD (single key metrics), HEATMAP (2D patterns), MAP (geographical data with lat/lng), COMBO (multiple chart types). STRICT REQUIREMENTS: pie/donut need exactly 1 dimension (categories) + 1 measure (count/sum only), scatter needs 2+ measures, map needs latitude + longitude + 1+ dimensions, kpi/stat cards need 1+ measures dimensions: type: array items: type: object properties: name: type: string label: type: string field: type: string type: type: string enum: - string - number - date - boolean - mixed - json aggregation: type: string enum: - count - distinct_count - sum - avg - min - max - first - collect_list bucketing: type: string enum: - hour - day - week - month - quarter - year - yearToDate format: type: object properties: label: description: >- Custom label for the field (overrides default field name) type: string formatOptions: description: >- JSON string containing formatting options for Intl.NumberFormat or Intl.DateTimeFormat. Must be a valid JSON object string. The object must be compatible with Intl.NumberFormat options for numeric fields or Intl.DateTimeFormat options for date fields. Example for numbers (not required format): '{ "style": "currency", "currency": "USD" }'. Example for dates (not required format): '{ "year": "numeric", "month": "long" }'. You can use any valid options from these Intl APIs, not just the examples shown. type: string formatLocale: description: >- Locale string for formatting (e.g., 'en-US', 'de-DE'). Used with both Intl.NumberFormat for numeric fields and Intl.DateTimeFormat for date fields. type: string labelSuffix: description: >- Text to append after the formatted value (e.g., '%', ' units') type: string labelPrefix: description: >- Text to prepend before the formatted value (e.g., '$', 'Total: ') type: string dateFormat: description: >- Date format string for date/time fields (e.g., 'YYYY-MM-DD', 'MM/DD/YYYY') type: string required: - name - field - type description: >- Categorical or time-based fields used to group and segment data. These create the x-axis for most charts and define categories for pie/donut charts. Common examples: date fields (for time series), categorical fields (regions, products, users), or any field that creates meaningful groupings. For pie/donut charts, use exactly 1 dimension representing the main categories you want to compare. Dimensions can have date bucketing (hour/day/week/month/quarter/year) for time-based aggregations measures: type: array items: type: object properties: name: type: string label: type: string field: type: string aggregation: type: string enum: - count - distinct_count - sum - avg - min - max - first - collect_list format: type: object properties: label: description: >- Custom label for the field (overrides default field name) type: string formatOptions: description: >- JSON string containing formatting options for Intl.NumberFormat or Intl.DateTimeFormat. Must be a valid JSON object string. The object must be compatible with Intl.NumberFormat options for numeric fields or Intl.DateTimeFormat options for date fields. Example for numbers (not required format): '{ "style": "currency", "currency": "USD" }'. Example for dates (not required format): '{ "year": "numeric", "month": "long" }'. You can use any valid options from these Intl APIs, not just the examples shown. type: string formatLocale: description: >- Locale string for formatting (e.g., 'en-US', 'de-DE'). Used with both Intl.NumberFormat for numeric fields and Intl.DateTimeFormat for date fields. type: string labelSuffix: description: >- Text to append after the formatted value (e.g., '%', ' units') type: string labelPrefix: description: >- Text to prepend before the formatted value (e.g., '$', 'Total: ') type: string dateFormat: description: >- Date format string for date/time fields (e.g., 'YYYY-MM-DD', 'MM/DD/YYYY') type: string required: - name - field - aggregation description: >- Numeric fields that get aggregated to create the y-axis values or chart data points. Each measure must specify an aggregation type: COUNT (number of records), SUM (total values), AVG (average), MIN/MAX (extreme values), DISTINCT_COUNT (unique values). For pie/donut charts, use exactly 1 measure with COUNT or SUM aggregation. For scatter plots, use 2+ measures for x/y coordinates. Measures support formatting options like currency, percentages, and decimal places comparisons: description: >- Period-over-period comparisons to show growth/decline trends. Options: 'previous_period' (compare to previous time bucket), 'year_over_year' (compare same period last year), 'custom' (user-defined period). Each comparison references a measure and applies the comparison logic. Useful for showing percentage changes, growth rates, and trend analysis in business metrics type: array items: type: object properties: name: type: string measure: type: string compareBy: type: string enum: - previous_period - year_over_year - custom customPeriod: type: number required: - name - measure - compareBy mapConfig: description: >- Required only for MAP chart types. Specifies which fields contain latitude and longitude coordinates. Both fields must be numeric and contain valid coordinate values. Used in combination with dimensions to create geographical visualizations showing data distribution across locations type: object properties: latitude: type: string longitude: type: string filters: description: >- Pre-aggregation filters applied to raw data before grouping and calculations. Supports operators: LIKE (text pattern matching), IN (value inclusion), BETWEEN (range filtering). Use to exclude irrelevant data, focus on specific segments, or handle data quality issues. Examples: filter by date ranges, specific categories, or exclude null values. Filters help create focused, relevant visualizations type: array items: type: object properties: field: type: string operator: type: string enum: - LIKE - IN - BETWEEN value: anyOf: - type: string - type: number - type: boolean - type: array items: anyOf: - type: string - type: number - type: boolean required: - field - operator - value havingFilters: description: >- Post-aggregation filters applied after grouping and measure calculations. Used to filter out aggregated results that don't meet criteria. Common use cases: show only categories with count > 10, exclude regions with sales < $1000, focus on top performers. Essential for creating clean visualizations by removing noise or low-value data points type: array items: type: object properties: field: type: string aggregation: type: string operator: type: string value: anyOf: - type: string - type: number - type: boolean required: - field - operator - value settings: description: >- Visual customization and presentation options. Controls: layout (horizontal/vertical), colors (custom color palettes), legend (show/hide and position), stacking (for bar/area charts), data labels (show values on chart), axis labels, debug mode. Use to enhance readability, match brand colors, or optimize for different screen sizes and use cases type: object properties: layout: description: >- Chart orientation: 'horizontal' renders bars/categories horizontally with values extending right, 'vertical' renders bars/categories vertically with values extending upward. Primarily affects BAR charts. Use horizontal for long category names or many categories (easier to read labels), vertical for typical column charts or time series. Default is usually horizontal type: string enum: - horizontal - vertical secondYAxis: description: >- Enables the second Y-axis for charts with exactly 2 measures. When enabled, the second measure will be rendered on the right Y-axis with independent scaling. This is useful when comparing two metrics with different scales or units (e.g., revenue in dollars vs. quantity in units). Only applies to line, area, bar, and combo chart types with exactly 2 measures. Default is false type: boolean colors: description: >- Custom color palette for chart series and categories. Provide an array of color strings in any valid CSS format (hex: '#FF5733', rgb: 'rgb(255,87,51)', named: 'blue'). Colors are applied sequentially to measures/series. Use to match brand guidelines, improve accessibility, or create visual hierarchy. If not specified, default color scheme is applied. Minimum 1 color recommended, but provide enough colors to cover all series to avoid repetition type: array items: type: string legend: description: >- Controls legend visibility on the chart. Set to true to show the legend (which displays labels for different series, measures, or categories), false to hide it. Legends help users identify what each color/line/bar represents. Hide legend for single-series charts or when labels are self-explanatory. Show legend for multi-series charts, pie/donut charts, or when colors represent different data categories. Default is typically true type: boolean legendPosition: description: >- Legend placement relative to chart area. Options: 'bottom' (common default, good for wide charts, also use this when generating PIE or DONUT charts), 'right' (doesn't affect chart width), 'left' (uncommon), 'top' (good for horizontal space-constrained displays). Choose based on available space and chart aspect ratio. Left/right work well for tall charts, top/bottom for wide charts. Only applies when legend is set to true default: bottom type: string enum: - left - right - top - bottom stacking: description: >- Enables stacked mode for BAR and AREA charts with multiple series. When true, values are stacked on top of each other showing cumulative totals and part-to-whole relationships. When false, series are displayed side-by-side (bars) or overlapping (areas). Use stacking to show total values and individual contributions simultaneously, or to emphasize cumulative trends. Not applicable for pie, scatter, or single-series charts. Default is false type: boolean showDataLabels: description: >- Controls whether numeric values are displayed directly on chart elements (on bars, lines, pie slices, etc.). When true, shows the actual data values as labels on or near the visual elements. Improves readability and eliminates need to reference axes, but can clutter charts with many data points. Best for charts with few data points (< 20), important for presentations or when precise values matter. Default is false to maintain clean appearance type: boolean enableLegendSlider: description: >- Adds interactive slider/scroll functionality to the legend when there are many series or categories. Useful for charts with 5+ series where a static legend would consume too much space. When true, legend becomes scrollable or paginable. Improves usability for complex multi-series visualizations without overwhelming the interface. Only relevant when legend is enabled and there are multiple items. Default is false type: boolean showAxisLabels: description: >- Controls visibility of axis labels (x-axis and y-axis labels/titles). When true, displays axis labels that describe what each axis represents (e.g., 'Revenue ($)', 'Month', 'Sales Count'). When false, hides these labels for a cleaner, more compact chart. Show labels for clarity and context, especially for presentations or standalone charts. Hide for dashboards where context is clear or space is limited. Default is typically true type: boolean debug: description: >- Enables debug/development mode for troubleshooting. When true, may display additional information like raw data, generated SQL queries, configuration details, or console logs. Intended for developers and debugging purposes only. Should always be false in production environments. Use to diagnose chart configuration issues, verify data transformations, or understand chart behavior during development type: boolean pageSize: description: >- Number of rows to display per page in BAR chart types. Common values: 10 (compact), 15 (default balance), 25-50 (data-heavy tables). Larger values reduce pagination clicks but increase initial load time and scrolling. Default is 15 rows per page default: 15 type: number sliceLimit: description: >- Number of categories to display in PIE and DONUT chart types. Default is 7 categories default: 7 type: number orderBy: description: >- Sorting configuration for chart data. Specify field name and sort direction (ascending/descending). Supports multiple sort fields for complex ordering. Common use cases: sort bars by value (descending for top performers), sort time series by date (ascending), sort categories alphabetically. Helps create meaningful data hierarchy and improves chart readability type: array items: type: object properties: field: type: string direction: type: string enum: - ascending - descending required: - field - direction sqlOverride: description: >- Advanced: Custom SQL query to override auto-generated chart query. Use only when standard schema cannot express complex data requirements. Must return data compatible with specified dimensions and measures. Warning: bypasses schema validation and may cause errors if not properly formatted type: string required: - title - type - dimensions - measures description: >- The chart configuration exactly as returned by the chat endpoint's generateChart tool result (`toolResult.result.chartConfig`). Should include the `sqlOverride` field the agent bakes onto the config; if it doesn't, pass the query on the top-level `sql` field instead — without either the saved chart cannot query data when rendered on a dashboard. sql: description: >- The chart's source SQL. Only needed when `chartConfig.sqlOverride` is absent — some generateChart tool-result shapes carry the query on the tool's sibling `sql` field instead of on the config. When both are present, `chartConfig.sqlOverride` wins. type: string agentId: description: >- The project agent ID the chart was generated by (the same ID used to call the chat endpoint). When provided, the chart is linked to the agent's data connection and project so it can be rendered on any dashboard. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ connectionId: description: >- Explicit connection ID to associate with the chart. Overrides the connection resolved from agentId. When both agentId and connectionId are given, the connection must belong to the agent's project. A resolvable connection (from either field) is required. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ name: description: >- Display name for the saved chart. Defaults to the chart config's title. type: string thumbnail: description: Optional thumbnail image (data URL) for the chart. type: string required: - chartConfig required: true responses: '200': description: POST /v1/api/chart/save-from-chat Positive response content: application/json: schema: type: object properties: status: type: string const: success data: type: object properties: chartId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ description: >- The ID of the saved chart. Pass this to /v1/api/dashboard/add-charts to add the chart to a dashboard. name: type: string description: The name the chart was saved with. required: - chartId - name additionalProperties: false required: - status - data additionalProperties: false '400': description: POST /v1/api/chart/save-from-chat Negative response content: application/json: schema: type: object properties: status: type: string const: error error: type: object properties: message: type: string code: type: string details: type: object propertyNames: type: string additionalProperties: {} required: - message additionalProperties: false required: - status - error additionalProperties: false security: - APIKEY_2: [] components: securitySchemes: APIKEY_2: type: apiKey in: header name: authorization ````