Charthop report API

openapi: 3.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
servers:
- url: https://localhost
- url: http://localhost
tags:
- name: report
paths:
  /v1/org/{orgId}/report:
    get:
      tags:
      - report
      summary: Return all reports in the organization paginated
      operationId: findReports
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: fromId
        in: query
        description: Offset
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Limit
        required: false
        schema:
          type: integer
          format: int32
      - name: sort
        in: query
        description: Sort
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filter
        required: false
        schema:
          type: string
      - name: fields
        in: query
        description: Fields to retrieve, comma-separated
        required: false
        schema:
          type: string
      - name: format
        in: query
        description: Data format to use; default is json, can also use json-extended or json-readable
        required: false
        schema:
          type: string
      - name: returnAccess
        in: query
        description: 'Return access information -- pass a list of actions to check, for example: create,update,delete'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportDataStreamResults'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
    post:
      tags:
      - report
      summary: Create a report
      operationId: createReport
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '201':
          description: report created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReport'
        description: Report data to create
        required: true
  /v1/org/{orgId}/report/bulk-delete:
    post:
      tags:
      - report
      summary: Delete a set of reports
      operationId: bulkDelete
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '400':
          description: invalid data
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                example: 588f7ee98f138b19220041a7
        description: List of report ids to delete
        required: true
  /v1/org/{orgId}/report/bulk-duplicate:
    post:
      tags:
      - report
      summary: Duplicate a set of reports
      operationId: bulkDuplicate
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '400':
          description: invalid data
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                example: 588f7ee98f138b19220041a7
        description: List of report ids to duplicate
        required: true
  /v1/org/{orgId}/report/count:
    get:
      tags:
      - report
      summary: Return count of reports in an organization
      operationId: getReportCount
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReportResult'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportQuery'
        required: true
  /v1/org/{orgId}/report/{reportId}:
    get:
      tags:
      - report
      summary: Return a particular report by id
      operationId: getReport
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: reportId
        in: path
        description: Report id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '400':
          description: bad request
        '404':
          description: not found
    patch:
      tags:
      - report
      summary: Update an existing report
      operationId: updateReport
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: reportId
        in: path
        description: Report id
        required: true
        schema:
          type: string
      - name: referencedReportUrl
        in: query
        description: Displayed report url
        required: false
        schema:
          type: string
      responses:
        '204':
          description: report updated
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateReport'
        description: Report data to update
        required: true
    delete:
      tags:
      - report
      summary: Delete a report
      operationId: deleteReport
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: reportId
        in: path
        description: Report id
        required: true
        schema:
          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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: reportId
        in: path
        description: Report id
        required: true
        schema:
          type: string
      - name: chartId
        in: path
        description: Chart id
        required: true
        schema:
          type: string
      - name: startDate
        in: query
        description: Start date, inclusive
        required: false
        schema:
          type: string
      - name: endDate
        in: query
        description: End date, exclusive
        required: false
        schema:
          type: string
      - name: interval
        in: query
        description: Interval
        required: false
        schema:
          type: string
          enum:
          - DAY
          - WEEK
          - MONTH
          - QUARTER
          - FISCAL_QUARTER
          - YEAR
          - FISCAL_YEAR
      - name: scenarioId
        in: query
        description: Scenario id
        required: false
        schema:
          type: string
      - name: projectHires
        in: query
        description: Project future hires
        required: false
        schema:
          type: boolean
      - name: filter
        in: query
        description: Additional filter to apply
        required: false
        schema:
          type: string
      - name: changeGroupingType
        in: query
        description: Type of change grouping
        required: false
        schema:
          type: string
          enum:
          - PRIMARY
          - SCENARIO
          - COMP_REVIEW
      - name: changeGroupingId
        in: query
        description: Change grouping id to query (null for primary)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: reportId
        in: path
        description: Report id
        required: true
        schema:
          type: string
      responses:
        '201':
          description: report created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: reportId
        in: path
        description: Report id
        required: true
        schema:
          type: string
      - name: startDate
        in: query
        description: Start date, inclusive
        required: false
        schema:
          type: string
      - name: endDate
        in: query
        description: End date, exclusive
        required: false
        schema:
          type: string
      - name: interval
        in: query
        description: Interval
        required: false
        schema:
          type: string
          enum:
          - DAY
          - WEEK
          - MONTH
          - QUARTER
          - FISCAL_QUARTER
          - YEAR
          - FISCAL_YEAR
      - name: scenarioId
        in: query
        description: Scenario id
        required: false
        schema:
          type: string
      - name: projectHires
        in: query
        description: Project future hires
        required: false
        schema:
          type: boolean
      - name: filter
        in: query
        description: Filter to apply to all results
        required: false
        schema:
          type: string
      - name: changeGroupingType
        in: query
        description: Type of change grouping
        required: false
        schema:
          type: string
          enum:
          - PRIMARY
          - SCENARIO
          - COMP_REVIEW
      - name: changeGroupingId
        in: query
        description: Change grouping id to query (null for primary)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReportResult'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
components:
  schemas:
    ReportQuery:
      type: object
      required:
      - options
      properties:
        series:
          type: array
          description: series to evaluate
          items:
            $ref: '#/components/schemas/ReportSeriesQuery'
        filters:
          type: array
          description: filters to crosstab all results by (deprecated in reports V2, should use groupBy instead)
          items:
            $ref: '#/components/schemas/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
    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 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: '#/components/schemas/ShareAccess'
        chartIds:
          type: array
          description: list of charts in this report
          items:
            type: string
            example: 588f7ee98f138b19220041a7
    ShareAccess:
      type: object
      required:
      - access
      properties:
        access:
          type: string
          description: access permission level
          enum:
          - NONE
          - LIMITED_READ
          - LIMITED_WRITE
          - STANDARD_READ
          - STANDARD_WRITE
          - COMPENSATION_READ
          - FULL_READ
          - COMP_PLANNING_PARTICIPANT
          - COMPENSATION_WRITE
          - WRITE
          - COMPENSATION_OWNER
          - OWNER
        userId:
          type: string
          description: user id
          example: 5887a7718f138b6a2a0041a7
        groupId:
          type: string
          description: group id
          example: 5887a7718f138b6a2a0041a7
        fields:
          type: string
          description: fields
          example: name,image,title
    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
    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: '#/components/schemas/GroupByConfig'
    ReportFilter:
      type: object
      required:
      - label
      - filter
      properties:
        label:
          type: string
          description: human-readable label for the filter
        filter:
          type: string
          description: filter expression
    ResultsAccess:
      type: object
      required:
      - allowed
      properties:
        ids:
          type: array
          uniqueItems: true
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        allowed:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/AccessAction'
    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: '#/components/schemas/ReportQuery'
        results:
          type: array
          description: list of the results, one per query that was requested
          items:
            $ref: '#/components/schemas/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: '#/components/schemas/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
    ReportGroupByDimension:
      type: object
      required:
      - keys
      properties:
        keys:
          type: array
          description: list of keys appearing in the groupBy
          items:
            $ref: '#/components/schemas/ReportGroupByKey'
    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: '#/components/schemas/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: '#/components/schemas/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: '#/components/schemas/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
    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
    ReportCount:
      type: object
      required:
      - count
      properties:
        count:
          type: integer
          format: int64
    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
    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
    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
    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: '#/components/schemas/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
    LabelColor:
      type: object
      required:
      - label
      - color
      properties:
        label:
          type: string
          description: human-readable label for the value
        color:
          type: string
          description: suggested color for the value
    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: '#/components/schemas/ShareAccess'
        chartIds:
          type: array
          description: list of charts in this report
          items:
            type: string
            example: 588f7ee98f138b19220041a7
    ReportQueryResult:
      type: object
      required:
      - series
      properties:
        series:
          type: array
          description: list of series results
          items:
            $ref: '#/components/schemas/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: '#/components/schemas/ReportGroupByDimension'
        dateIntervals:
          type: array
 

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