swagger: '2.0' info: description: REST API for ChartHop version: V1.0.0 title: ChartHop access reportChart API contact: name: ChartHop url: https://www.charthop.com email: support@charthop.com host: localhost schemes: - https - http consumes: - application/json produces: - application/json tags: - name: reportChart paths: /v1/org/{orgId}/report/chart/{chartId}: get: tags: - reportChart summary: Return a particular report chart by id operationId: getChart consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: chartId in: path description: Chart id required: true type: string responses: '200': description: successful operation schema: $ref: '#/definitions/ReportChart' '400': description: bad request '404': description: not found patch: tags: - reportChart summary: Update an existing report chart operationId: updateChart consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: chartId in: path description: Chart id required: true type: string - name: body in: body description: Chart data to update required: true schema: $ref: '#/definitions/UpdateReportChart' responses: '204': description: updated '400': description: invalid data '401': description: not authorized '403': description: permission denied '404': description: not found delete: tags: - reportChart summary: Delete a chart from a report operationId: deleteChart consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: chartId in: path description: Chart id required: true type: string responses: '204': description: deleted '400': description: invalid data '401': description: not authorized '403': description: permission denied '404': description: not found /v1/org/{orgId}/report/{reportId}/chart: get: tags: - reportChart summary: Return all of the charts for a particular report operationId: findCharts consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: reportId in: path description: Report id required: true type: string responses: '200': description: successful operation schema: $ref: '#/definitions/ResultsReportChart' '400': description: bad request '401': description: not authorized '404': description: not found post: tags: - reportChart summary: Create a new chart in a report operationId: createChart consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: reportId in: path description: Report id required: true type: string - name: body in: body description: Report chart data to create required: true schema: $ref: '#/definitions/CreateReportChart' responses: '201': description: created schema: $ref: '#/definitions/ReportChart' '400': description: invalid data '401': description: not authorized '403': description: permission denied '404': description: org not found /v1/org/{orgId}/report/{reportId}/chart/{chartId}/clone: post: tags: - reportChart summary: Clone a chart in a report operationId: cloneChart consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: reportId in: path description: Report id required: true type: string - name: chartId in: path description: Chart id required: true type: string - name: chartLabel in: query description: New label required: true type: string responses: '201': description: successful operation schema: $ref: '#/definitions/ReportChart' '400': description: invalid data '401': description: not authorized '403': description: permission denied '404': description: org not found /v1/org/{orgId}/report/{reportId}/chart/{chartId}/data: get: tags: - reportChart summary: Export a particular chart's data operationId: exportChartData consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: reportId in: path description: Report id required: true type: string - name: chartId in: path description: Chart id required: true type: string - name: startDate in: query description: Start date, inclusive required: false type: string - name: endDate in: query description: End date, exclusive required: false type: string - name: interval in: query description: Interval required: false type: string enum: - DAY - WEEK - MONTH - QUARTER - FISCAL_QUARTER - YEAR - FISCAL_YEAR - name: scenarioId in: query description: Scenario id required: false type: string - name: projectHires in: query description: Project future hires required: true type: boolean - name: format in: query description: Data format to use; default is json, can also use html required: false type: string - name: changeGroupingType in: query description: Type of change grouping required: false type: string enum: - PRIMARY - SCENARIO - COMP_REVIEW - name: changeGroupingId in: query description: Change grouping id to query (null for primary) required: false type: string responses: '200': description: ok schema: type: object '400': description: bad request '401': description: not authorized '404': description: not found definitions: AccessAction: type: object required: - action properties: action: type: string fields: type: array uniqueItems: true items: type: string types: type: array uniqueItems: true items: type: string ResultsAccess: type: object required: - allowed properties: ids: type: array uniqueItems: true items: type: string example: 588f7ee98f138b19220041a7 allowed: type: array uniqueItems: true items: $ref: '#/definitions/AccessAction' LabelOverride: type: object required: - id properties: id: type: string description: The unique identifier to use to locate the key to override. For entities and enum values, this will be an id. For numbers, this will be the normalized numeric representation. For others, this will be the string label: type: string description: If set, overrides this label color: type: string description: If set, overrides the default color sort: type: integer format: int32 description: If set, overrides the sorting order CreateReportChart: type: object required: - label - type - query - sort properties: label: type: string description: chart label example: Headcount Report minItems: 1 maxItems: 255 type: type: string description: chart type enum: - LINE - AREA - STACKED - BAR - VERTICAL_BAR - HORIZONTAL_BAR - PIE - TABLE - TABLE_CROSSTAB - SINGLE_METRIC - BUBBLE - HEADER - TEXT - GAUGE - WATERFALL - WATERFALL_TIMESERIES - HEATMAP - GEO - GEO_HEATMAP - GEO_SCATTER - RADAR - N_GRID - NETWORK - COMBO - COMBO_TIMESERIES - DONUT - FUNNEL - FUNNEL_TIMESERIES - SANKEY - SANKEY_TIMESERIES - WORDCLOUD - EMOJI_CLOUD - CALENDAR_HEATMAP - GANTT filter: type: string description: filter that applies to this chart example: department='Engineering' filterOverride: type: boolean description: whether the chart filter overrides the global filter query: description: query for all series in the chart $ref: '#/definitions/ReportQuery' sort: type: integer format: int32 description: sort order isAdvancedQueryMode: type: boolean description: whether the chart configuration is using advanced mode ReportSeriesQuery: type: object required: - label - color - y properties: label: type: string description: label to use color: type: string description: color to use y: type: string description: y-value to calculate example: sum{headcount, gender:f} / sum{headcount} groupByConfigs: type: array description: Configuration for aggregations performed by the groupBy operator items: $ref: '#/definitions/GroupByConfig' GroupByConfig: type: object properties: overrides: type: array description: Overrides by label of label, color, or sort order items: $ref: '#/definitions/LabelOverride' limit: type: integer format: int32 description: Maximum number of results to display includeOther: type: boolean description: When combined with limit, whether to include an 'Other' group includeNone: type: boolean description: Whether to include a 'None' group (null values aggregated) includeAllValues: type: boolean description: When combined with fieldId or questionId, will include all values from that fieldId or questionId, even if none of them were used fieldId: type: string description: The field to use to retrieve values, when includeAllValues is in use example: 588f7ee98f138b19220041a7 questionId: type: string description: The question to use to retrieve values, when includeAllValues is in use example: 588f7ee98f138b19220041a7 sortBy: type: string description: Whether to sort the results -- by default, will sort by label if there is no limit, will sort by value descending if there is a limit enum: - LABEL - KEY - VALUE - COUNT sortDirection: type: string description: The direction to sort the results enum: - ASC - DESC ReportChart: type: object required: - id - orgId - label - type - query properties: id: type: string description: globally unique id example: 588f7ee98f138b19220041a7 orgId: type: string description: parent organization id example: 588f7ee98f138b19220041a7 reportId: type: string description: parent report id example: 588f7ee98f138b19220041a7 label: type: string description: chart label example: Headcount Report minItems: 1 maxItems: 255 type: type: string description: chart type enum: - LINE - AREA - STACKED - BAR - VERTICAL_BAR - HORIZONTAL_BAR - PIE - TABLE - TABLE_CROSSTAB - SINGLE_METRIC - BUBBLE - HEADER - TEXT - GAUGE - WATERFALL - WATERFALL_TIMESERIES - HEATMAP - GEO - GEO_HEATMAP - GEO_SCATTER - RADAR - N_GRID - NETWORK - COMBO - COMBO_TIMESERIES - DONUT - FUNNEL - FUNNEL_TIMESERIES - SANKEY - SANKEY_TIMESERIES - WORDCLOUD - EMOJI_CLOUD - CALENDAR_HEATMAP - GANTT filter: type: string description: filter that applies to this chart example: department='Engineering' filterOverride: type: boolean description: whether the chart filter overrides the global filter query: description: query for all series in the chart $ref: '#/definitions/ReportQuery' sort: type: integer format: int32 description: sort order isAdvancedQueryMode: type: boolean description: whether the chart configuration is using advanced mode createId: type: string description: created by user id example: 588f7ee98f138b19220041a7 createBehalfId: type: string description: created on behalf of user id example: 588f7ee98f138b19220041a7 createAttribution: $ref: '#/definitions/Attribution' createAt: type: string description: created timestamp example: '2017-01-24T13:57:52Z' updateId: type: string description: last updated by user id example: 588f7ee98f138b19220041a7 updateBehalfId: type: string description: last updated on behalf of user id example: 588f7ee98f138b19220041a7 updateAttribution: $ref: '#/definitions/Attribution' updateAt: type: string description: last updated timestamp example: '2017-01-24T13:57:52Z' deleteId: type: string description: deleted by user id example: 588f7ee98f138b19220041a7 deleteBehalfId: type: string description: deleted on behalf of user id example: 588f7ee98f138b19220041a7 deleteAttribution: $ref: '#/definitions/Attribution' deleteAt: type: string description: deleted timestamp example: '2017-01-24T13:57:52Z' Attribution: type: object properties: principalUserId: type: string example: 588f7ee98f138b19220041a7 agentUserIds: type: array items: type: string example: 588f7ee98f138b19220041a7 eventId: type: string example: 588f7ee98f138b19220041a7 aiChatId: type: string example: 588f7ee98f138b19220041a7 aiToolUseId: type: string channel: type: string enum: - WEB - MOBILE - SLACK - TEAMS - MCP UpdateReportChart: type: object properties: label: type: string description: chart label example: Headcount Report minItems: 1 maxItems: 255 type: type: string description: chart type enum: - LINE - AREA - STACKED - BAR - VERTICAL_BAR - HORIZONTAL_BAR - PIE - TABLE - TABLE_CROSSTAB - SINGLE_METRIC - BUBBLE - HEADER - TEXT - GAUGE - WATERFALL - WATERFALL_TIMESERIES - HEATMAP - GEO - GEO_HEATMAP - GEO_SCATTER - RADAR - N_GRID - NETWORK - COMBO - COMBO_TIMESERIES - DONUT - FUNNEL - FUNNEL_TIMESERIES - SANKEY - SANKEY_TIMESERIES - WORDCLOUD - EMOJI_CLOUD - CALENDAR_HEATMAP - GANTT filter: type: string description: filter that applies to this chart example: department='Engineering' filterOverride: type: boolean description: whether the chart filter overrides the global filter query: description: query for all series in the chart $ref: '#/definitions/ReportQuery' sort: type: integer format: int32 description: sort order isAdvancedQueryMode: type: boolean description: whether the chart configuration is using advanced mode ReportQuery: type: object required: - options properties: series: type: array description: series to evaluate items: $ref: '#/definitions/ReportSeriesQuery' filters: type: array description: filters to crosstab all results by (deprecated in reports V2, should use groupBy instead) items: $ref: '#/definitions/ReportFilter' content: type: string description: content block to evaluate as a Carrot Template, as an alternative to using series startDate: type: string description: start date, in either relative (-7d) or exact (YYYY-MM-DD) format endDate: type: string description: end date, in either relative (-7d) or exact (YYYY-MM-DD) format; if not present, defaults to today interval: type: string description: interval, if the query is a timeseries; if no interval, query is crosstabbed enum: - DAY - WEEK - MONTH - QUARTER - FISCAL_QUARTER - YEAR - FISCAL_YEAR intervalDates: type: array description: interval dates, if a specific set of irregular dates are being queried in a timeseries items: type: string format: date options: type: object description: options, including format, filter, scenarioId, projectHires, and numerous display options ReportFilter: type: object required: - label - filter properties: label: type: string description: human-readable label for the filter filter: type: string description: filter expression ResultsReportChart: type: object required: - data properties: data: type: array items: $ref: '#/definitions/ReportChart' next: type: string access: type: array items: $ref: '#/definitions/ResultsAccess'