Charthop report API

swagger: '2.0'
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access report 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: report
paths:
  /v1/org/{orgId}/report:
    get:
      tags:
      - report
      summary: Return all reports in the organization paginated
      operationId: findReports
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: fromId
        in: query
        description: Offset
        required: false
        type: string
      - name: limit
        in: query
        description: Limit
        required: false
        type: integer
        format: int32
      - name: sort
        in: query
        description: Sort
        required: false
        type: string
      - name: filter
        in: query
        description: Filter
        required: false
        type: string
      - name: fields
        in: query
        description: Fields to retrieve, comma-separated
        required: false
        type: string
      - name: format
        in: query
        description: Data format to use; default is json, can also use json-extended or json-readable
        required: false
        type: string
      - name: returnAccess
        in: query
        description: 'Return access information -- pass a list of actions to check, for example: create,update,delete'
        required: false
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ReportDataStreamResults'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
    post:
      tags:
      - report
      summary: Create a report
      operationId: createReport
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        description: Report data to create
        required: true
        schema:
          $ref: '#/definitions/CreateReport'
      responses:
        '201':
          description: report created
          schema:
            $ref: '#/definitions/Report'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
  /v1/org/{orgId}/report/bulk-delete:
    post:
      tags:
      - report
      summary: Delete a set of reports
      operationId: bulkDelete
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        description: List of report ids to delete
        required: true
        schema:
          type: array
          items:
            type: string
            example: 588f7ee98f138b19220041a7
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Process'
        '400':
          description: invalid data
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/org/{orgId}/report/bulk-duplicate:
    post:
      tags:
      - report
      summary: Duplicate a set of reports
      operationId: bulkDuplicate
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        description: List of report ids to duplicate
        required: true
        schema:
          type: array
          items:
            type: string
            example: 588f7ee98f138b19220041a7
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Process'
        '400':
          description: invalid data
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/org/{orgId}/report/count:
    get:
      tags:
      - report
      summary: Return count of reports in an organization
      operationId: getReportCount
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ReportCount'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/report/query:
    post:
      tags:
      - report
      summary: Return timeseries data from arbitrary queries
      operationId: getReportFromQuery
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/ReportQuery'
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/ReportResult'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/report/{reportId}:
    get:
      tags:
      - report
      summary: Return a particular report by id
      operationId: getReport
      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/Report'
        '400':
          description: bad request
        '404':
          description: not found
    patch:
      tags:
      - report
      summary: Update an existing report
      operationId: updateReport
      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: referencedReportUrl
        in: query
        description: Displayed report url
        required: false
        type: string
      - name: body
        in: body
        description: Report data to update
        required: true
        schema:
          $ref: '#/definitions/UpdateReport'
      responses:
        '204':
          description: report updated
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
    delete:
      tags:
      - report
      summary: Delete a report
      operationId: deleteReport
      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:
        '204':
          description: report deleted
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/org/{orgId}/report/{reportId}/chart/{chartId}/export/csv:
    post:
      tags:
      - report
      summary: Export a particular chart in a report
      operationId: exportChartCsv
      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: false
        type: boolean
      - name: filter
        in: query
        description: Additional filter to apply
        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: successful operation
          schema:
            $ref: '#/definitions/Process'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/report/{reportId}/clone:
    post:
      tags:
      - report
      summary: Create an exact copy of an existing report
      operationId: cloneReport
      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:
        '201':
          description: report created
          schema:
            $ref: '#/definitions/Report'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
  /v1/org/{orgId}/report/{reportId}/query:
    get:
      tags:
      - report
      summary: Query all the charts in a report
      operationId: getAllReportResults
      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: 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: false
        type: boolean
      - name: filter
        in: query
        description: Filter to apply to all results
        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: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/ReportResult'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
definitions:
  LogData:
    type: object
    required:
    - level
    - at
    - data
    properties:
      level:
        type: string
        enum:
        - INFO
        - WARN
        - ERROR
      at:
        type: string
        description: created timestamp
        example: '2017-01-24T13:57:52Z'
      message:
        type: string
      data:
        type: object
        additionalProperties:
          type: object
  ReportResult:
    type: object
    required:
    - id
    - orgId
    - key
    - startDate
    - endDate
    - options
    - queries
    - results
    - createId
    - createAt
    - status
    properties:
      id:
        type: string
        description: globally unique id
        example: 588f7ee98f138b19220041a7
      orgId:
        type: string
        description: parent org id
        example: 588f7ee98f138b19220041a7
      key:
        type: string
        description: identifying key for this report result
      startDate:
        type: string
        format: date
        description: date that the report result interval begins, inclusive
      endDate:
        type: string
        format: date
        description: date that the report result interval ends, exclusive
      options:
        type: object
        description: options that were used for the query
      queries:
        type: array
        description: list of queries that were requested
        items:
          $ref: '#/definitions/ReportQuery'
      results:
        type: array
        description: list of the results, one per query that was requested
        items:
          $ref: '#/definitions/ReportQueryResult'
      buildStartAt:
        type: string
        description: start time of last build
        example: '2017-01-24T13:57:52Z'
      buildEndAt:
        type: string
        description: end time of last build
        example: '2017-01-24T13:57:52Z'
      message:
        type: string
        description: status or error message
      progress:
        type: number
        format: double
        description: percent progress so far
      viewId:
        type: string
        description: viewer user id
        example: 588f7ee98f138b19220041a7
      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'
      status:
        type: string
        description: status of the report result
        enum:
        - OK
        - LOCKED
        - RETRY
        - ERROR
      reportId:
        type: string
        description: corresponding report id for the built query
        example: 588f7ee98f138b19220041a7
      chartId:
        type: string
        description: corresponding chart id for the built query
        example: 588f7ee98f138b19220041a7
  ReportCount:
    type: object
    required:
    - count
    properties:
      count:
        type: integer
        format: int64
  UpdateReport:
    type: object
    properties:
      label:
        type: string
        description: report label
        example: Headcount Report
        minItems: 1
        maxItems: 255
      description:
        type: string
        description: report description
        example: This is a report on headcount etd
        minItems: 0
        maxItems: 2000
      filter:
        type: string
        description: filter automatically applied to every chart in this report
        example: department:engineering
      share:
        type: string
        description: sharing settings of report
        enum:
        - NORMAL
        - FULL
      sensitive:
        type: string
        description: sensitivity level of report
        enum:
        - GLOBAL
        - ORG
        - SENSITIVE
        - PERSONAL
        - MANAGER
        - HIGH
        - PRIVATE
      shareAccess:
        type: array
        description: users who are specifically granted permission to view or edit this report
        items:
          $ref: '#/definitions/ShareAccess'
      chartIds:
        type: array
        description: list of charts in this report
        items:
          type: string
          example: 588f7ee98f138b19220041a7
  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'
  ReportFilter:
    type: object
    required:
    - label
    - filter
    properties:
      label:
        type: string
        description: human-readable label for the filter
      filter:
        type: string
        description: filter expression
  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
  Process:
    type: object
    required:
    - id
    - orgId
    - label
    - type
    - status
    - runUserId
    - createId
    - createAt
    - options
    properties:
      id:
        type: string
        description: globally unique id
        example: 588f7ee98f138b19220041a7
      orgId:
        type: string
        description: parent org id
        example: 588f7ee98f138b19220041a7
      label:
        type: string
        description: human-readable label that identifies this process
      type:
        type: string
        description: process type
      status:
        type: string
        description: current status of process
        enum:
        - PENDING
        - RUNNING
        - DONE
        - ERROR
      filePath:
        type: string
        description: data file path
      logPath:
        type: string
        description: data log path
      runUserId:
        type: string
        description: user id who is running the process
        example: 588f7ee98f138b19220041a7
      parentProcessId:
        type: string
        description: process id of parent process
        example: 588f7ee98f138b19220041a7
      createId:
        type: string
        description: created by user id (user who requested the process run)
        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'
      startAt:
        type: string
        description: started at timestamp
        example: '2017-01-24T13:57:52Z'
      endAt:
        type: string
        description: ended at timestamp
        example: '2017-01-24T13:57:52Z'
      message:
        type: string
        description: status or error message
      progress:
        type: number
        format: double
        description: percent progress so far
      internalError:
        type: string
        description: internal-only error message
      options:
        type: object
        description: options passed to the process
      results:
        type: object
        description: results summary for the process
        additionalProperties:
          type: object
      logDataList:
        type: array
        description: list of log data that occurred during running of this process
        items:
          $ref: '#/definitions/LogData'
      state:
        type: object
        description: process-specific state data
      summary:
        type: string
        description: human-readable, searchable summary of what this process did
      appId:
        type: string
        description: app id of the process
        example: 588f7ee98f138b19220041a7
      uuid:
        type: string
        description: unique ID of the process at queue time
        example: 84db3c6e-0877-4436-8af1-768c06b29586
  ReportDateInterval:
    type: object
    required:
    - startDate
    - endDate
    properties:
      startDate:
        type: string
        format: date
      endDate:
        type: string
        format: date
      partialStartDate:
        type: string
        format: date
      partialEndDate:
        type: string
        format: date
  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
  ReportDataStreamResults:
    type: object
    required:
    - data
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/Report'
      next:
        type: string
      access:
        type: array
        items:
          $ref: '#/definitions/ResultsAccess'
  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'
  ReportGroupByKey:
    type: object
    required:
    - id
    - color
    - label
    properties:
      id:
        type: string
        description: unique string identifier for this key
      color:
        type: string
        description: color for this key, prior to any overrides
      label:
        type: string
        description: label for this key, prior to any overrides
      imagePath:
        type: string
        description: S3-relative avatar/icon/logo path for this key (EntityTag form), when resolved server-side
      orgId:
        type: string
        description: owning org of this key's entity, when the key spans orgs of a customer
        example: 588f7ee98f138b19220041a7
  ReportQueryResult:
    type: object
    required:
    - series
    properties:
      series:
        type: array
        description: list of series results
        items:
          $ref: '#/definitions/ReportSeriesResult'
      content:
        type: string
        description: the results of rendering the content block, if a content template was used in the query
      groupBys:
        type: array
        description: list of group-by dimensions with default values
        items:
          $ref: '#/definitions/ReportGroupByDimension'
      dateIntervals:
        type: array
        description: list of group-by dimensions with default values
        items:
          $ref: '#/definitions/ReportDateInterval'
      version:
        type: integer
        format: int32
        description: version used to generate the results
  ReportGroupByDimension:
    type: object
    required:
    - keys
    properties:
      keys:
        type: array
        description: list of keys appearing in the groupBy
        items:
          $ref: '#/definitions/ReportGroupByKey'
  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
  Report:
    type: object
    required:
    - id
    - orgId
    - label
    - share
    - sensitive
    - shareAccess
    properties:
      id:
        type: string
        description: globally unique id
        example: 588f7ee98f138b19220041a7
      orgId:
        type: string
        description: parent organization id
        example: 588f7ee98f138b19220041a7
      label:
        type: string
        description: report label
        example: Headcount Report
        minItems: 1
        maxItems: 255
      description:
        type: string
        description: report description
        example: This is a report on headcount etd
        minItems: 0
        maxItems: 2000
      filter:
        type: string
        description: filter automatically applied to every chart in this report
        example: department:engineering
      share:
        type: string
        description: sharing settings of report
        enum:
        - NORMAL
        - FULL
      sensitive:
        type: string
        description: sensitivity level of report
        enum:
        - GLOBAL
        - ORG
        - SENSITIVE
        - PERSONAL
        - MANAGER
        - HIGH
        - PRIVATE
      shareAccess:
        type: array
        description: users who are specifically granted permission to view or edit this report
        items:
          $ref: '#/definitions/ShareAccess'
      chartIds:
        type: array
        description: list of charts in this report
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      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'
  ReportSeriesResult:
    type: object
    required:
    - label
    - color
    - format
    - data
    - isIntervalMetric
    properties:
      label:
        type: string
        description: human-readable label for the series
      color:
        type: string
        description: suggested color for the series
      format:
        type: string
        description: number format (currently 'number', 'money', 'percent' allowed)
      data:
        type: array
        description: array of items in the series
        items:
          type: object
      xAxis:
        type: array
        description: labels and colors of the values in the X-axis, if the X-axis is not a timeseries
        items:
          $ref: '#/definitions/LabelColor'
      isIntervalMetric:
        type: boolean
        description: true if the metric being returned is reporting on the entire interval (includes the intervalFrom or intervalUntil metric), false if just the last date in the interval
  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
  CreateReport:
    type: object
    required:
    - label
    properties:
      label:
        type: string
        description: report label
        example: Headcount Report
        minItems: 1
        maxItems: 255
      description:
        type: string
        description: report description
        example: This is a report on headcount etd
        minItems: 0
        maxItems: 2000
      filter:
        type: string
        description: filter automatically applied to every chart

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/charthop/refs/heads/main/openapi/charthop-report-api-openapi.yml