{"openapi":"3.0.0","paths":{"/exports":{"post":{"operationId":"createRequest","summary":"Create export request","description":"Create export request.\n\nRequired Permission:\n\n - Resource: ```exporter:exports```\n\n - Action: ```exporter:exports:create```","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExportRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadExportRequestDto"}}}},"400":{"description":"Missing user identity id"},"429":{"description":"Maximum number of queued exports reached"}},"tags":["Exports"],"security":[{"chx_auth_session":[]},{"bearer":[]}]},"get":{"operationId":"list","summary":"List exports","description":"List exports.\n\nRequired Permission:\n\n - Resource: ```exporter:exports```\n\n - Action: ```exporter:exports:list```","parameters":[{"name":"ids","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"status","required":false,"in":"query","schema":{"type":"array","items":{"type":"string","enum":["notProcessed","inProgress","failed","done","expired"]}}},{"name":"type","required":false,"in":"query","schema":{"enum":["recurring","oneTime"],"type":"string"}},{"name":"tagLabels","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"tagLabelValues","required":false,"in":"query","schema":{"type":"array","items":{"type":"string"}}},{"name":"from","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"to","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":0,"default":0,"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"minimum":0,"default":1000,"type":"number"}},{"name":"sort","required":false,"in":"query","schema":{"pattern":"sortingStringRegex","default":"createdAt:desc","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PagedExportRequestsDto"}}}},"400":{"description":"Missing user identity id"}},"tags":["Exports"],"security":[{"chx_auth_session":[]},{"bearer":[]}]}},"/exports/{id}/download":{"get":{"operationId":"download","summary":"Download export","description":"Download export.\n\nRequired Permission:\n\n - Resource: ```exporter:exports:{id}```\n\n - Action: ```exporter:exports:download```","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"400":{"description":"Missing user identity id"},"401":{"description":""},"403":{"description":""},"404":{"description":""}},"tags":["Exports"],"security":[{"chx_auth_session":[]},{"bearer":[]}]}},"/exports/{id}":{"delete":{"operationId":"delete","summary":"Delete export request","description":"Delete export request.\n\nRequired Permission:\n\n - Resource: ```exporter:exports:{id}```\n\n - Action: ```exporter:exports:delete```","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""},"400":{"description":"Missing user identity id"},"404":{"description":""}},"tags":["Exports"],"security":[{"chx_auth_session":[]},{"bearer":[]}]}},"/exports/{id}/status":{"get":{"operationId":"getStatus","summary":"Get export status","description":"Get export status.\n\nRequired Permission:\n\n - Resource: ```exporter:exports:{id}```\n\n - Action: ```exporter:exports:get```","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"400":{"description":"Missing user identity id"},"404":{"description":""}},"tags":["Exports"],"security":[{"chx_auth_session":[]},{"bearer":[]}]}}},"info":{"title":"connhex-exporter","description":"","version":"1.5.0","contact":{}},"tags":[],"servers":[{"url":"https://apis.<domain>"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"},"chx_auth_session":{"type":"apiKey","in":"cookie","name":"chx_auth_session"}},"schemas":{"ColumnDto":{"type":"object","properties":{"id":{"type":"string","description":"Column `id`.\n\nWhen exporting resource items it must be formatted as: `<type>.<attribute>`.","examples":["device.serial_number","unit"]},"label":{"type":"string","description":"Column label","examples":["serial number","unit of measure"]}},"required":["id","label"]},"ExportFormatDto":{"type":"object","properties":{"filename":{"type":"string"},"extension":{"type":"string","enum":["csv","xlsx","pdf"]},"columns":{"description":"Define how exported data fields are mapped to the output file.\n\nFor **resource exports**, each column `id` must follow the pattern `<resource-type>.<attribute>`,\nusing the **singular** resource type as prefix (e.g. `device.serial`, `installation.name`).\nTo reference an included related resource, use its own singular type as prefix\n(e.g. `installation.name` when `include=installation` is set on the export item).\n\nFor **message exports**, column `id` maps directly to message fields\n(e.g. `time`, `name`, `value`, `unit`).","type":"array","items":{"$ref":"#/components/schemas/ColumnDto"}},"timezone":{"type":"string","description":"Target timezone: all data field will be remapped to this timezone","default":"utc"},"template":{"type":"string","description":"PDF layout template. Only applies to resource exports (`pdf` extension).\nIgnored for message exports and report exports.\n\n- `tabular` (default): all resources are rendered in a single table, one row per resource.\n- `expanded`: each resource is rendered as its own card with one row per field.\nUseful when resources have many attributes that would make a wide table unreadable.","default":"tabular","enum":["tabular","expanded"]},"csvDelimiter":{"type":"string"}},"required":["extension"]},"TargetDto":{"type":"object","properties":{"value":{"type":"string","description":"Identifier of the resource the be exported: typically a URN.\nIt is possible to export multiple resources by providing a comma separated list of values.","examples":["urn:cpt:smartdevice:nid:D0CF5EFFFE26FDAB1:onoff","urn:cpt:smartdevice:nid:D0CF5EFFFE26FDAB1:onoff, urn:cpt:smartdevice:nid:D0CF5EFFFE26FDAB1:temperature"]},"label":{"type":"string","description":"Label that will replace the target `value`.\nIf multiple `values` are provided, you can can pass a comma separated list of labels. The number of labels must match the number of `values`.","examples":["onoff","onoff, temperature"]}},"required":["value"]},"DecimationDto":{"type":"object","properties":{"ds":{"type":"object","description":"Decimation granularity. Only supports positive integer.","example":"15m"},"dsf":{"type":"string","description":"Aggregation algotithm","enum":["avg","max","min","sum","stddev","variance"]}},"required":["ds","dsf"]},"MessageExportItemParamsDto":{"type":"object","properties":{"target":{"$ref":"#/components/schemas/TargetDto"},"channelId":{"type":"string","example":"0115c85d-ef3e-4de9-9732-d0c5c4f2c482"},"subtopic":{"type":"string","description":"Subtopic from which to retrieve data for export","example":"events.data"},"from":{"type":"number","description":"Unix timestamp: number of seconds since 1970 UTC"},"to":{"type":"number","description":"Unix timestamp: number of seconds since 1970 UTC"},"period":{"type":"string","description":"ISO8601 Duration: https://en.wikipedia.org/wiki/ISO_8601#Durations","example":"P1Y6M4DT12H30M5S","pattern":"durationRegExp"},"decimation":{"$ref":"#/components/schemas/DecimationDto"},"transform":{"type":"string","enum":["delta"]},"outputFormat":{"type":"string","description":"Determines how exported data will be formatted in the output file.\nCheck the following link for more info: https://en.wikipedia.org/wiki/Wide_and_narrow_data\n\nIn the `long` format exported variables are spread across multiple rows.\nIn the `wide` format exported variables are spread across multiple columns, and each row represents a different timestamp.\n\nIf `wide` format is selected, `request.colums` must be provided.","default":"long","enum":["long","wide"]}},"required":["target","channelId","subtopic","outputFormat"]},"PageDto":{"type":"object","properties":{"limit":{"type":"number","minimum":0},"offset":{"type":"number","minimum":0}}},"ResourceExportItemParamsDto":{"type":"object","properties":{"type":{"type":"string","description":"Resource type in singular form (e.g. `device`, `installation`).\nThis value is also used as the prefix for column IDs in `format.columns`\n(e.g. `device.serial`, `device.notes`)."},"ids":{"description":"IDs of the resources to be exported","type":"array","items":{"type":"string"}},"include":{"type":"string","description":"Comma-separated list of related resource types to include (singular form).\nIncluded resources are merged into each row for tabular exports, or rendered\nas separate items for expanded PDF exports.\nTheir fields are addressable in `format.columns` using the included type as prefix\n(e.g. `include=installation` → column id `installation.name`).","examples":["installation","installation,tag"]},"sort":{"type":"string"},"filter":{"type":"object"},"page":{"$ref":"#/components/schemas/PageDto"}},"required":["type"]},"ProcessingFunctionDto":{"type":"object","properties":{"fn":{"type":"string","enum":["max","min","add","cumSum","mult","avg"]},"key":{"type":"string","description":"Defines the key of the object whose value will be processed by the function"},"params":{"type":"object","description":"Function parameters. Not all processing functions require additional parameters.","example":"For `add` or `mult`: {k: 1}\", \"For `avg`: {k: 1.5, decimals: 3}"}},"required":["fn","key"]},"ReportElementDataSourceDto":{"type":"object","properties":{"params":{"description":"The parameters associated to the service request","oneOf":[{"$ref":"#/components/schemas/MessageExportItemParamsDto"},{"$ref":"#/components/schemas/ResourceExportItemParamsDto"}]},"service":{"type":"string","description":"The service from which to fetch the data","enum":["messages","resources"]},"postProc":{"description":"The post-processing function(s) to apply to the retrieved data","type":"array","items":{"$ref":"#/components/schemas/ProcessingFunctionDto"}}},"required":["params","service"]},"ReportElementFormatTextDto":{"type":"object","properties":{"key":{"type":"string","description":"Defines the key of the object whose value will be displayed in the report","example":"value"},"unitKey":{"type":"string","description":"Defines the key of the object whose value will be displayed as unit of measurement","example":"unit"}},"required":["key"]},"ChartXAxisOptionsDto":{"type":"object","properties":{"type":{"type":"string","enum":["string","datetime"]},"format":{"type":"string","description":"Formatting string. If X axis represents time, this will be used to format the date."}},"required":["type"]},"ChartXAxisDto":{"type":"object","properties":{"key":{"type":"string","description":"Defines the key of the object whose value will be plotted in the X axis"},"options":{"$ref":"#/components/schemas/ChartXAxisOptionsDto"}},"required":["key","options"]},"ChartYAxisDto":{"type":"object","properties":{"key":{"type":"string","description":"Defines the key of the object whose value will be plotted in the Y axis"}},"required":["key"]},"ChartCanvasDto":{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"}},"required":["width","height"]},"ReportElementFormatChartDto":{"type":"object","properties":{"type":{"type":"string","enum":["bar","line"]},"xAxis":{"description":"X axis chart parameters","allOf":[{"$ref":"#/components/schemas/ChartXAxisDto"}]},"yAxis":{"description":"Y axis chart parameters","allOf":[{"$ref":"#/components/schemas/ChartYAxisDto"}]},"label":{"type":"string","description":"Chart label"},"color":{"type":"string","description":"Hexadecimal color string"},"canvas":{"$ref":"#/components/schemas/ChartCanvasDto"}},"required":["type","xAxis","yAxis"]},"ReportElementFormatTableDto":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/ColumnDto"}}},"required":["columns"]},"ReportElementFormatDto":{"type":"object","properties":{"text":{"description":"The formatting parameters for elements of type \"Text\"","allOf":[{"$ref":"#/components/schemas/ReportElementFormatTextDto"}]},"chart":{"description":"The formatting parameters for elements of type \"Chart\"","allOf":[{"$ref":"#/components/schemas/ReportElementFormatChartDto"}]},"table":{"description":"The formatting parameters for elements of type \"Table\"","allOf":[{"$ref":"#/components/schemas/ReportElementFormatTableDto"}]}}},"ReportElementDto":{"type":"object","properties":{"templateFieldId":{"type":"string","description":"Identifier of the placeholder associated with this report element.\nFor standard reports, this value must match the placeholder name used in the markdown template,\nfor example `{{energy_chart}}` or `{{total_consumption}}`.\nFor LLM-generated reports, elements with the same `templateFieldId` are grouped together\nand exposed to the model as a single logical section of the report.","example":"text0"},"type":{"type":"string","enum":["text","chart","table"]},"sources":{"description":"Defines the parameters needed to retrieve the data that will be used to fill the template element.\nTypically, sources has 1 element. However, if you want a chart with multiple plots, you can specify multiple source elements.","type":"array","items":{"$ref":"#/components/schemas/ReportElementDataSourceDto"}},"formats":{"description":"Defines the formatting parameters of the template element.\nFor example, for elements of type `Chart`: the chart type, the chart color, etc.\nIf multiple `sources` elements have been specified, you must define a `formats` element for each source. So, it must be: `len(formats) == len(sources)`.","type":"array","items":{"$ref":"#/components/schemas/ReportElementFormatDto"}}},"required":["templateFieldId","type","sources","formats"]},"LlmReportItemParamsDto":{"type":"object","properties":{"template":{"type":"string","description":"Instructions for the LLM on how to structure and write the report.\n\nThe following parameters are supported for report metadata hydration: `{{report.period.start}}`, `{{report.period.end}}`, `{{report.length}}`.","example":"The report must include an initial section with the following items:\n- [h1] Title: test\nAfter this, it must contain different sections. Each one must include:\n- [h2] A section title: generate it properly, based on the data you're provided.\n- A chart\n- Some additional statistics (min, max, average, total). You need to format these into a a table.\n- Below the table, add a brief paragraph that provides a commentary on the data\nImportant: The entire report must written in the Italian language."},"reportMode":{"type":"string","description":"Report mode.","enum":["llm"]},"elements":{"type":"array","items":{"$ref":"#/components/schemas/ReportElementDto"}}},"required":["template","reportMode","elements"]},"StandardReportItemParamsDto":{"type":"object","properties":{"reportMode":{"type":"string","description":"Report mode.","enum":["standard"]},"template":{"type":"string","description":"Markdown template with `{{<fieldId>}}` placeholders.\nPlaceholders are replaced with the rendered element:\n- chart: embedded PNG image\n- table: GFM table\n- text: plain value string\n\nThe following parameters are supported for report metadata hydration: `{{report.period.start}}`, `{{report.period.end}}`, `{{report.length}}`.","example":"# Report {{report.period.start}} – {{report.period.end}}\\n\\n## Energy\\n{{energy_chart}}\\n\\n### Readings\\n{{energy_table}}\\n\\n### Total\\n{{energy_total}}"},"elements":{"type":"array","items":{"$ref":"#/components/schemas/ReportElementDto"}}},"required":["reportMode","template","elements"]},"CreateExportItemDto":{"type":"object","properties":{"params":{"oneOf":[{"$ref":"#/components/schemas/MessageExportItemParamsDto"},{"$ref":"#/components/schemas/ResourceExportItemParamsDto"},{"$ref":"#/components/schemas/LlmReportItemParamsDto"},{"$ref":"#/components/schemas/StandardReportItemParamsDto"}]},"filename":{"type":"string","description":"Name of the output file (without extension)"}},"required":["params"]},"NotificationMessageDto":{"type":"object","properties":{"target":{"type":"string","description":"Notification target, whose format depends on the selected `medium`.\nIf not specified, the notification is sent to the user who created the rule.\n\nSupported formats:\n- `email`: email address\n- `sms`: E.164 phone number (e.g. \"+391234567890\")\n- `telegram`: username (\"@user\")\n- `slack` / `discord` / `msteams`: webhook URL\n- `fcm`: device registration token\n\nThe value must match the expected format for the chosen medium. Invalid or\nincompatible values may result in notification delivery failure."},"policy":{"type":"string","description":"The notification policy: whether it is associated with a success event (export delivered),\nor a failure event (export failed)","enum":["onSuccess","onFailure"]},"medium":{"type":"string","enum":["email","telegram","sms","slack","discord","fcm","msteams"]},"title":{"type":"string"},"text":{"type":"string"}},"required":["policy","medium","title","text"]},"NotificationDto":{"type":"object","properties":{"messages":{"description":"Notification messages. For each notification, there must be exactly two notification\nmessages with the two different policies (`onSuccess`, `onFailure`)","type":"array","items":{"$ref":"#/components/schemas/NotificationMessageDto"}}},"required":["messages"]},"CreateTagDto":{"type":"object","properties":{"label":{"type":"string"},"labelValue":{"type":"string"},"metadata":{"type":"object","description":"Other custom properties associated to the tag"}},"required":["label","labelValue"]},"CreateExportRequestDto":{"type":"object","properties":{"format":{"$ref":"#/components/schemas/ExportFormatDto"},"type":{"type":"string","enum":["recurring","oneTime"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateExportItemDto"}},"periodicity":{"type":"string","description":"ISO8601 Duration: https://en.wikipedia.org/wiki/ISO_8601#Durations","example":"P1Y6M4DT12H30M5S","pattern":"durationRegExp"},"periodStart":{"type":"number","description":"Period start expressed in Unix timestamp.\nIf not specified, the creation date of the request will be used."},"notification":{"$ref":"#/components/schemas/NotificationDto"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/CreateTagDto"}}},"required":["format","type","items"]},"ReadExportRequestDto":{"type":"object","properties":{"format":{"$ref":"#/components/schemas/ExportFormatDto"},"type":{"enum":["recurring","oneTime"],"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateExportItemDto"}},"periodicity":{"type":"string","description":"ISO8601 Duration: https://en.wikipedia.org/wiki/ISO_8601#Durations","example":"P1Y6M4DT12H30M5S","pattern":"durationRegExp"},"periodStart":{"type":"number","description":"Period start expressed in Unix timestamp.\nIf not specified, the creation date of the request will be used."},"notification":{"$ref":"#/components/schemas/NotificationDto"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/CreateTagDto"}},"id":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"deletedAt":{"format":"date-time","type":"string"}},"required":["format","type","items","id","createdAt","updatedAt","deletedAt"]},"PagedExportRequestsDto":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ReadExportRequestDto"}},"total":{"type":"number"}},"required":["results","total"]}}}}