Pigment Export API

openapi: 3.0.4
info:
  title: Pigment External ApplicationApi Export API
  version: v1-external
security:
- ApiKey: []
tags:
- name: Export
paths:
  /api/export/view/{viewId}:
    get:
      tags:
      - Export
      description: Exports the data of a specific view and returns a CSV file containing the exported data
      parameters:
      - name: viewId
        in: path
        description: The ID of the view to export
        required: true
        schema:
          type: string
          format: uuid
      - name: dateFormat
        in: query
        description: The format to use for dates. Defaults to Legacy.
        schema:
          allOf:
          - $ref: '#/components/schemas/ExportDateFormat'
      - name: fieldDelimiter
        in: query
        description: The field delimiter to use in csv exports. Defaults to semicolon (;).
        schema:
          allOf:
          - $ref: '#/components/schemas/ExportCsvDelimiter'
      responses:
        '200':
          description: View export successfully started
          content:
            text/csv:
              schema:
                type: string
            text/plain:
              schema:
                type: string
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: View with the specified ID was not found
        '413':
          description: View is too big to be exported. Use block export API instead.
        '422':
          description: The view underlying type is not list, metric or table
  /api/export/list/{listId}:
    post:
      tags:
      - Export
      description: Exports the data of a specific list and returns a CSV file containing the exported data
      parameters:
      - name: listId
        in: path
        description: The ID of the list to export
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ListRequest'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ListRequest'
          text/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ListRequest'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ListRequest'
      responses:
        '200':
          description: List export successfully started
          content:
            text/csv:
              schema:
                type: string
            text/plain:
              schema:
                type: string
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: List with the specified ID was not found
  /api/export/metric/{metricId}:
    post:
      tags:
      - Export
      description: Exports the data of a specific metric and returns a CSV file containing the exported data
      parameters:
      - name: metricId
        in: path
        description: The ID of the metric to export
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/MetricRequest'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/MetricRequest'
          text/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/MetricRequest'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/MetricRequest'
      responses:
        '200':
          description: Metric export successfully started
          content:
            text/csv:
              schema:
                type: string
            text/plain:
              schema:
                type: string
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Metric with the specified ID was not found
  /api/export/table/{tableId}:
    post:
      tags:
      - Export
      description: Exports the data of a specific table and returns a CSV file containing the exported data
      parameters:
      - name: tableId
        in: path
        description: The ID of the table to export
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/TableRequest'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/TableRequest'
          text/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/TableRequest'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/TableRequest'
      responses:
        '200':
          description: Table export successfully started
          content:
            text/csv:
              schema:
                type: string
            text/plain:
              schema:
                type: string
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Table with the specified ID was not found
components:
  schemas:
    FilterConditionType:
      enum:
      - LessThan
      - LessThanOrEqual
      - Equal
      - NotEqual
      - GreaterThan
      - GreaterThanOrEqual
      - IsNotBlank
      type: string
    ExportFileEncoding:
      enum:
      - Utf8WithBom
      - Utf8WithoutBom
      type: string
    ExportCsvDelimiter:
      enum:
      - Semicolon
      - Comma
      type: string
    ExportFilter:
      required:
      - type
      type: object
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/ExportFilterType'
          description: Discriminator for the filter type. Must be set, along with the corresponding field
        and:
          type: array
          items:
            $ref: '#/components/schemas/ExportFilter'
          description: List of filters to combine with an AND. Must be set if Type is And. Should not be empty if not null - empty behaviour is undefined.
          nullable: true
        or:
          type: array
          items:
            $ref: '#/components/schemas/ExportFilter'
          description: List of filters to combine with an OR. Must be set if Type is Or. Should not be empty if not null - empty behaviour is undefined.
          nullable: true
        dimension:
          allOf:
          - $ref: '#/components/schemas/DimensionFilter'
          description: Filter on a dimension. Only rows where the target dimension is defined will be filtered by this.
          nullable: true
        value:
          allOf:
          - $ref: '#/components/schemas/ValueFilter'
          description: Filter on a metric value. Only rows where that metric could be defined (i.e. all of the metric's dimensions are defined) will be filtered by an instance of this.
          nullable: true
      additionalProperties: false
      description: Recursive filter object which supports combining dimension and value filters
    ExportDecimalSeparator:
      enum:
      - Comma
      - Dot
      type: string
    FilterCondition:
      required:
      - type
      type: object
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/FilterConditionType'
        value:
          oneOf:
          - type: string
          - type: number
          - type: integer
          - type: boolean
          description: Value to compare to. Must be the same type as the property being filtered.
      additionalProperties: false
      description: 'Filter condition for export filtering.


        Important: The ''value'' field is:

        - Required for types: LessThan, LessThanOrEqual, Equal, NotEqual, GreaterThan, GreaterThanOrEqual

        - Must be omitted for type: IsNotBlank'
      example:
        type: GreaterThan
        value: 10
    ExportFieldType:
      enum:
      - DimensionField
      - ScenarioField
      - ValueField
      type: string
    DimensionFilter:
      required:
      - dimensionId
      - modalityIds
      type: object
      properties:
        dimensionId:
          type: string
          format: uuid
        modalityIds:
          type: array
          items:
            type: string
            format: uuid
          description: Modalities of the dimension to filter in. Behaviour when empty is undefined - omit the filter instead to allow all values.
      additionalProperties: false
      description: Filter on a dimension. Only rows where the target dimension is defined will be filtered by this.
    TableRequest:
      type: object
      properties:
        metrics:
          type: array
          items:
            type: string
            format: uuid
          nullable: true
        scenarios:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of scenarios to be exported. If null or empty, only the default scenario will be exported and the export won't have a scenario column.
          nullable: true
        filters:
          type: array
          items:
            $ref: '#/components/schemas/DimensionFilter'
          description: Deprecated - use the ExportFilter field instead. If both this and ExportFilter are not null, they are combined with an implicit AND. Empty filters are treated as including all values.
          nullable: true
        exportFilter:
          allOf:
          - $ref: '#/components/schemas/ExportFilter'
          description: Recursive filter object which supports combining dimension and value filters
          nullable: true
        friendlyHeaders:
          type: boolean
          description: If true, the exported CSV header will display metric friendly names. If null or not provided, it will display technical names.
          nullable: true
        dateFormat:
          allOf:
          - $ref: '#/components/schemas/ExportDateFormat'
          description: Defines how Date values in the response should be formatted. In legacy endpoints, defaults to Legacy if not provided. In the /v1/ endpoints defaults to Iso8601 if not provided.
          nullable: true
        fieldDelimiter:
          allOf:
          - $ref: '#/components/schemas/ExportCsvDelimiter'
          description: The field delimiter to use in the csv export. Defaults to semicolon (;).
          nullable: true
        decimalSeparator:
          allOf:
          - $ref: '#/components/schemas/ExportDecimalSeparator'
          description: The decimal separator to use in the csv export. Defaults to dot (.).
          nullable: true
        fields:
          type: array
          items:
            $ref: '#/components/schemas/ExportField'
          description: List of fields to be included in the output csv, each as a single column. When not provided, one column for each metric and one column for each metric dimension is generated, in a fixed order.
          nullable: true
        encoding:
          allOf:
          - $ref: '#/components/schemas/ExportFileEncoding'
          nullable: true
      additionalProperties: false
    ListRequest:
      type: object
      properties:
        propertyTechnicalNames:
          type: array
          items:
            type: string
          description: List of the property technical to be exported. The properties will be exported in that order. If null, all properties of the list will be exported ordered by their technical name.
          nullable: true
        listFilter:
          type: array
          items:
            type: string
            format: uuid
          description: List of modalities of the list to filter in. Empty or null means all.
          nullable: true
        propertyFilters:
          type: array
          items:
            $ref: '#/components/schemas/PropertyFilter'
          description: List of property filters.
          nullable: true
        friendlyHeaders:
          type: boolean
          description: If true, the exported CSV header will display list and properties friendly names. If null or false, it will display technical names.
          nullable: true
        dateFormat:
          allOf:
          - $ref: '#/components/schemas/ExportDateFormat'
          description: Defines how Date values in the response should be formatted. In the /v1/ endpoints will default to Iso8601 if not provided.
          nullable: true
        fieldDelimiter:
          allOf:
          - $ref: '#/components/schemas/ExportCsvDelimiter'
          description: Field separator, defaults to semicolon (;)
          nullable: true
        decimalSeparator:
          allOf:
          - $ref: '#/components/schemas/ExportDecimalSeparator'
          description: The decimal separator to use in the csv export. Defaults to dot (.).
          nullable: true
        encoding:
          allOf:
          - $ref: '#/components/schemas/ExportFileEncoding'
          nullable: true
      additionalProperties: false
    ExportField:
      required:
      - sourceId
      - type
      type: object
      properties:
        sourceId:
          type: string
          description: 'MetricId if Type = Value, DimensionId if Type = DimensionPivot, null if Type = ScenarioPivot.


            If the value is a MetricId, it should be the id of the metric in the live application (i.e. not an id from a snapshot, even if only

            snapshot scenarios are included in this export request)'
          format: uuid
          nullable: true
        type:
          allOf:
          - $ref: '#/components/schemas/ExportFieldType'
          description: Defines the type of field.
        displayName:
          type: string
          description: Optional display name override for the field. When set will be placed in the csv headers.
          nullable: true
      additionalProperties: false
    ExportDateFormat:
      enum:
      - Legacy
      - Iso8601
      type: string
      description: Defines how Date values in the response should be formatted. Usage of the 'Legacy' option is not recommended, the format will either be '01/21/2054', in other cases '10/12/2024 00:00:00 +00:00'. 'Iso8601' will format dates like '2054-01-21'.
    ExportFilterType:
      enum:
      - And
      - Or
      - Dimension
      - Value
      type: string
    ValueFilter:
      required:
      - condition
      - metricId
      type: object
      properties:
        metricId:
          type: string
          format: uuid
        condition:
          allOf:
          - $ref: '#/components/schemas/FilterCondition'
      additionalProperties: false
      description: Filter on a metric value. Only rows where that metric could be defined (i.e. all of the metric's dimensions are defined) will be filtered by an instance of this.
    PropertyFilter:
      required:
      - modalityIds
      - propertyTechnicalName
      type: object
      properties:
        propertyTechnicalName:
          type: string
        modalityIds:
          type: array
          items:
            type: string
            format: uuid
      additionalProperties: false
    MetricRequest:
      type: object
      properties:
        scenarios:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of scenarios to be exported. If null or empty, only the default scenario will be exported and the export won"t have a scenario column.
          nullable: true
        filters:
          type: array
          items:
            $ref: '#/components/schemas/DimensionFilter'
          description: Deprecated - use the ExportFilter field instead. If both this and ExportFilter are not null, they are combined with an implicit AND. Empty filters are treated as including all values.
          nullable: true
        exportFilter:
          allOf:
          - $ref: '#/components/schemas/ExportFilter'
          description: Recursive filter object which supports combining dimension and value filters
          nullable: true
        friendlyHeaders:
          type: boolean
          description: If true, the exported CSV header will display metric friendly names. If null or not provided, it will display technical names.
          nullable: true
        dateFormat:
          allOf:
          - $ref: '#/components/schemas/ExportDateFormat'
          description: Defines how Date values in the response should be formatted. In legacy endpoints, defaults to Legacy if not provided. In the /v1/ endpoints defaults to Iso8601 if not provided.
          nullable: true
        fieldDelimiter:
          allOf:
          - $ref: '#/components/schemas/ExportCsvDelimiter'
          description: The field delimiter to use in the csv export. Defaults to semicolon (;).
          nullable: true
        decimalSeparator:
          allOf:
          - $ref: '#/components/schemas/ExportDecimalSeparator'
          description: The decimal separator to use in the csv export. Defaults to dot (.).
          nullable: true
        encoding:
          allOf:
          - $ref: '#/components/schemas/ExportFileEncoding'
          nullable: true
      additionalProperties: false
  securitySchemes:
    ApiKey:
      type: http
      description: API Key Authorization header using the Bearer scheme.
      scheme: bearer
      bearerFormat: ApiKey