Create report charts
/report-chartsSave a chart, or a copy of one. Saving in a shared space needs Reports_Manage as well.
RchtCmdCopyRchtCmdCreatePermissions
reports:queryRequires the `query` action on `reports` for the supplied runtime context
Request body
This body is a typed union. Pick a variant to see its fields and a matching example.
typetype = "RchtCmdCopy"copyOfRchtIdrequiredThe chart to copy.
Example rcht_9f2Kd8QpLzXw
reportSpaceIdRspcIdWhere to save the copy. Absent for the original's space, or for the caller's default space when the original is in the System space.
Example rspc_9f2Kd8QpLzXw
titlestringAbsent for the original's title with (copy) after it.
curl -X POST https://api.tst.au.apgpay.dev/report-charts \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "RchtCmdCopy",
"copyOf": "rcht_9f2Kd8QpLzXw",
"reportSpaceId": "rspc_9f2Kd8QpLzXw",
"title": "string"
}'Responses
The response is a tagged shape: type is always "RchtCreateRspAttributes". Switch on it; subtypes can be added, and a client that already reads it will not break.
typetype = "RchtCreateRspAttributes"The resource that was created.
typeenumrequiredRchtViewAttributesreportChartIdRchtIdrequiredIdentifier of a saved chart.
Example rcht_9f2Kd8QpLzXw
reportSpaceIdRspcIdrequiredIdentifier of a report space.
Example rspc_9f2Kd8QpLzXw
titlestringrequiredAsk a dataset a question. With measures, the answer is one row per combination of the dimensions and time buckets; with none, it is one row per record, in the dataset's row columns.
typeenumrequiredRqryCmdRunreportDatasetIdstringrequiredmeasuresarray of stringWhat to add up, by name from the dataset's measures.
dimensionsarray of stringWhat to group by, by name from the dataset's dimensions.
Bucket by time. Absent for a total over all time.
typeenumrequiredRqryTimeSliceAttributesgrainstringrequiredA grain the dataset offers, by name.
typeFrom one date to another, both inclusive, in the question's timezone.
fromstring (date)requiredExample 2026-08-19
tostring (date)requiredExample 2026-08-19
The current period of grain so far.
grainstringrequiredThe last count whole periods of grain before the current one, ending where it starts.
countinteger (int32)requiredExample 42
grainstringrequiredFrom startsAt up to but not including endsAt, exactly: the first and last buckets are cut at the period's ends rather than widened to whole buckets, so a statement cycle that starts at 16:00 starts there. Buckets are still local time in the question's timezone.
periodstringA period the dataset declares in its periods, such as a statement cycle, or absent for bounds the caller names alone.
startsAtstring (date-time)requiredExample 2026-08-19T04:21:07Z
endsAtstring (date-time)requiredExample 2026-08-19T04:21:07Z
The whole period of grain before the current one.
grainstringrequiredcompareRqryComparisonAlso answer for an earlier range, adding a previous column for each measure, and a change column for each but a date.
PreviousPeriodSamePeriodLastYearPreviousBucketUnknownEvery filter must hold. A value is written as text whatever the dimension's kind: 12.50, 2026-09-01.
typeKeeps every row whose value is above this one. Only a dimension whose operators lists Above takes it; a row with no value is not kept.
dimensionstringrequiredvaluestringrequireddimensionstringrequiredKeeps every row whose value is this one or above. Only a dimension whose operators lists AtLeast takes it; a row with no value is not kept.
dimensionstringrequiredvaluestringrequiredKeeps every row whose value is this one or below. Only a dimension whose operators lists AtMost takes it; a row with no value is not kept.
dimensionstringrequiredvaluestringrequiredKeeps every row whose value is below this one. Only a dimension whose operators lists Below takes it; a row with no value is not kept.
dimensionstringrequiredvaluestringrequiredBoth ends inclusive.
dimensionstringrequiredfromstringrequiredtostringrequiredKeeps every row whose value holds this text, ignoring case. Only a dimension whose matchesText is true may be searched, and a search of a column needs a time slice to bound the rows it tests.
dimensionstringrequiredtextstringrequireddimensionstringrequiredvaluestringrequireddimensionstringrequiredvaluesarray of stringKeeps every row whose value is not this one, including a row with no value.
dimensionstringrequiredvaluestringrequiredKeeps every row whose value is none of these, including a row with no value.
dimensionstringrequiredvaluesarray of stringtypedimensionstringrequiredascendingbooleanrequiredExample true
Orders by the measure. A money measure in several currencies, the question grouping by its currency, is ordered by currency first and by amount within each currency, since amounts in different currencies are no one scale.
measurestringrequiredascendingbooleanrequiredExample true
ascendingbooleanrequiredExample true
limitinteger (int32)At most this many rows.
Example 25
pagestringnext from the previous answer, to continue the same row-mode question. It is opaque and forward only, and a question changed in anything but limit refuses it with 400.
segmentsarray of stringNamed filters from the dataset's segments, applied as well as filters.
Every one must hold of a group for it to be kept, tested after grouping. Each names one of measures; a value is a decimal written as text. Absent for none.
typemeasurestringrequiredvaluestringrequiredmeasurestringrequiredvaluestringrequiredmeasurestringrequiredvaluestringrequiredmeasurestringrequiredvaluestringrequiredmeasurestringrequiredvaluestringrequiredKeep only the values of one dimension with the most of a measure, and fold the rest into an Others row.
typeenumrequiredRqryTopAttributesdimensionstringrequiredOne of the question's dimensions, whose values are ranked.
countinteger (int32)requiredHow many values to keep, from 1 to 100, within each combination of the other dimensions.
Example 42
measurestringrequiredOne of the question's measures, largest first, summed over the whole range.
Ask as tenants beneath the caller, as a marketplace views a report as some of its merchants. Every tenant must be one the caller may read, and the answer stays within the caller's own tenants. Absent to ask as the caller.
typeOnly these customers.
customerIdsarray of CustIdrequiredExample cust_9f2Kd8QpLzXw
Only these enterprises.
enterpriseIdsarray of EntIdrequiredExample ent_9f2Kd8QpLzXw
Only these marketplaces.
marketplaceIdsarray of MktpIdrequiredExample mktp_9f2Kd8QpLzXw
Only these merchants.
merchantIdsarray of MchtIdrequiredExample mcht_9f2Kd8QpLzXw
asAtstring (date-time)Read each balance as at this instant: its latest snapshot before it, and every earlier one for a highest or lowest. Only balance measures have a value at an instant, and the question takes no time. Absent for all time.
Example 2026-08-19T04:21:07Z
Lay the answer out as a grid: rows and columns each name some of dimensions, together each of them once. The answer stays one row per cell of the grid, each row saying its level, with a total and, with subtotals, a subtotal per leading row dimension. Absent for none.
typeenumrequiredRqryPivotAttributesrowsarray of stringThe dimensions down the side, outermost first. The time bucket, when there is one, is always the first row key.
columnsarray of stringThe dimensions across the top. Each must have few values: together at most 50.
subtotalsbooleanrequiredAlso answer a subtotal for each leading prefix of rows. The grand total is always answered.
Example true
timezonestringThe timezone the question is answered in, an IANA name such as Australia/Perth or an offset such as +10:00, which keeps no daylight saving: where its buckets start, how its dates, periods and relative ranges are read, and which local day or hour a date part names. Absent for the asker's own, which the dataset's timezone gives: the timezone every active merchant the asker reads keeps, or the dataset's where they keep several.
How a chart draws its answer. What it asks is its question.
typeenumrequiredRchtPresentationAttributeschartTypeRchtChartTyperequiredAutoLineAreaColumnBarStackedNumberTablePieUnknownAbsent for the palette the chart's shape calls for.
typeenumrequiredRchtColoursAttributespaletteRchtPaletteAbsent for the palette the chart's shape calls for.
CategoricalSequentialBandsUnknowntypeenumrequiredRchtColourOverrideAttributesseriesstringrequiredThe series it colours: a measure's name, or a value of the dimension the chart is split by.
swatchstringrequiredA step of a palette, its prefix and its number: cat-3, seq-5, band-1.
descriptionstringWhat the figure means, shown under the chart's title.
riseIsRchtRiseIsWhether a rise in the figure is good news, which colours its change. Absent, a measure's target decides, and without one a change is not judged.
GoodBadNeutralUnknownstackTotalstringGiven, a stacked chart also draws its stack's total, as a line under this label.
typeA fixed figure, written as a decimal.
labelstringrequiredvaluestringrequiredThe figure of one of the dataset's measures over the chart's own range, such as a peak.
labelstringrequiredmeasurestringrequiredThe target the catalogue sets the measure.
labelstringrequiredmeasurestringrequiredHow a chart drawn as a table shows its rows, beyond the answer itself.
typeenumrequiredRchtTableAttributesrowLinkstringThe dimension whose value opens its own page, such as a customer.
typeenumrequiredRchtStatusColumnAttributescolumnstringrequiredA dimension by its name, or a target's status by its measure's.
typeenumrequiredRchtValueToneAttributesvaluestringrequiredA value of the column, as its answer writes it.
toneRchtTonerequiredDangerWarningSuccessMutedUnknownstalestringPresent when the catalogue has moved under the question since it was saved, so asking it now would be refused: why, as the refusal would say. The chart is still read, and saving a new question clears it.
accessRspcAccessrequiredPrivateSharedSystemUnknowntypeThe tenant an item was saved under: the platform, or the enterprise, marketplace or merchant its saver signed in as.
enterpriseIdEntIdrequiredIdentifier of an enterprise.
Example ent_9f2Kd8QpLzXw
The tenant an item was saved under: the platform, or the enterprise, marketplace or merchant its saver signed in as.
marketplaceIdMktpIdrequiredIdentifier of a marketplace.
Example mktp_9f2Kd8QpLzXw
The tenant an item was saved under: the platform, or the enterprise, marketplace or merchant its saver signed in as.
merchantIdMchtIdrequiredIdentifier of a merchant.
Example mcht_9f2Kd8QpLzXw
The platform, which no enterprise, marketplace or merchant bounds.
The platform, which no enterprise, marketplace or merchant bounds.
ownedByCallerbooleanrequiredExample true
editablebooleanrequiredWhether the caller may change, move or delete it.
Example true
createdAtstring (date-time)requiredExample 2026-08-19T04:21:07Z
updatedAtstring (date-time)requiredExample 2026-08-19T04:21:07Z
{
"type": "RchtCreateRspAttributes",
"created": {
"type": "RchtViewAttributes",
"reportChartId": "rcht_9f2Kd8QpLzXw",
"reportSpaceId": "rspc_9f2Kd8QpLzXw",
"title": "string",
"question": {
"type": "RqryCmdRun",
"reportDatasetId": "string",
"measures": [
"string"
],
"dimensions": [
"string"
],
"time": {
"type": "RqryTimeSliceAttributes",
"grain": "string",
"range": {
"type": "RqryRangeBetween",
"from": "2026-08-19",
"to": "2026-08-19"
},
"compare": "PreviousPeriod"
},
"filters": [
{
"type": "RqryFilterAbove",
"dimension": "string",
"value": "string"
}
],
"sort": [
{
"type": "RqrySortDimension",
"dimension": "string",
"ascending": true
}
],
"limit": 25,
"page": "string",
"segments": [
"string"
],
"measureFilters": [
{
"type": "RqryMeasureFilterAbove",
"measure": "string",
"value": "string"
}
],
"top": {
"type": "RqryTopAttributes",
"dimension": "string",
"count": 42,
"measure": "string"
},
"narrowTo": {
"type": "RqryNarrowCustomers",
"customerIds": [
"cust_9f2Kd8QpLzXw"
]
},
"asAt": "2026-08-19T04:21:07Z",
"pivot": {
"type": "RqryPivotAttributes",
"rows": [
"string"
],
"columns": [
"string"
],
"subtotals": true
},
"timezone": "string"
},
"presentation": {
"type": "RchtPresentationAttributes",
"chartType": "Auto",
"colours": {
"type": "RchtColoursAttributes",
"palette": "Categorical",
"overrides": [
{
"type": "RchtColourOverrideAttributes",
"series": "string",
"swatch": "string"
}
]
},
"description": "string",
"riseIs": "Good",
"stackTotal": "string",
"referenceLines": [
{
"type": "RchtReferenceLineConstant",
"label": "string",
"value": "string"
}
],
"table": {
"type": "RchtTableAttributes",
"rowLink": "string",
"statuses": [
{
"type": "RchtStatusColumnAttributes",
"column": "string",
"tones": [
{
"type": "RchtValueToneAttributes",
"value": "string",
"tone": "Danger"
}
]
}
]
}
},
"stale": "string",
"access": "Private",
"tenant": {
"type": "RspcTenantEnterprise",
"enterpriseId": "ent_9f2Kd8QpLzXw"
},
"ownedByCaller": true,
"editable": true,
"createdAt": "2026-08-19T04:21:07Z",
"updatedAt": "2026-08-19T04:21:07Z"
}
}Error responses
statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}statusCodeinteger (int32)requiredHTTP status code for this error
errorCodestringrequiredAn APG Pay code providing a brief explanation of the underlying error. Use this if you wish to provide custom behaviour based on the error type.
messagestringrequiredHuman readable description of the error
tracerstringAn unique identifier for the request. Provide this to the support team if you wish to query a particular error.
detailstringOptional additional details for the error.
errorTypeDescriptionstringA description of the category of errors for the given statusCode.
metadataobjectOptional key value list of metadata
{
"statusCode": 100,
"errorCode": "string",
"message": "string",
"tracer": "string",
"detail": "string",
"errorTypeDescription": "string"
}