Charthop reportChart API

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'