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 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 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 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 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