Pigment Export API

openapi: 3.2.0
info:
  title: Pigment External ApplicationApi Export API
  version: v1-external
servers:
- url: https://pigment.app/api
  description: Base URL declared by the provider in apis.yml (roadmap#122).
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:
    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'.
    ExportDecimalSeparator:
      enum:
      - Comma
      - Dot
      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
          - 'null'
          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.
        or:
          type:
          - array
          - 'null'
          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.
        dimension:
          allOf:
          - $ref: '#/components/schemas/DimensionFilter'
          description: Filter on a dimension. Only rows where the target dimension is defined will be filtered by this.
        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.
      additionalProperties: false
      description: Recursive filter object which supports combining dimension and value filters
    FilterConditionType:
      enum:
      - LessThan
      - LessThanOrEqual
      - Equal
      - NotEqual
      - GreaterThan
      - GreaterThanOrEqual
      - IsNotBlank
      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.
    ExportField:
      required:
      - sourceId
      - type
      type: object
      properties:
        sourceId:
          type:
          - string
          - 'null'
          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
        type:
          allOf:
          - $ref: '#/components/schemas/ExportFieldType'
          description: Defines the type of field.
        displayName:
          type:
          - string
          - 'null'
          description: Optional display name override for the field. When set will be placed in the csv headers.
      additionalProperties: false
    ExportFilterType:
      enum:
      - And
      - Or
      - Dimension
      - Value
      type: string
    ExportFieldType:
      enum:
      - DimensionField
      - ScenarioField
      - ValueField
      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.
    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
    ListRequest:
      type: object
      properties:
        propertyTechnicalNames:
          type:
          - array
          - 'null'
          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.
        listFilter:
          type:
          - array
          - 'null'
          items:
            type: string
            format: uuid
          description: List of modalities of the list to filter in. Empty or null means all.
        propertyFilters:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PropertyFilter'
          description: List of property filters.
        friendlyHeaders:
          type:
          - boolean
          - 'null'
          description: If true, the exported CSV header will display list and properties friendly names. If null or false, it will display technical names.
        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.
        fieldDelimiter:
          allOf:
          - $ref: '#/components/schemas/ExportCsvDelimiter'
          description: Field separator, defaults to semicolon (;)
        decimalSeparator:
          allOf:
          - $ref: '#/components/schemas/ExportDecimalSeparator'
          description: The decimal separator to use in the csv export. Defaults to dot (.).
        encoding:
          allOf:
          - $ref: '#/components/schemas/ExportFileEncoding'
      additionalProperties: false
    MetricRequest:
      type: object
      properties:
        scenarios:
          type:
          - array
          - 'null'
          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.
        filters:
          type:
          - array
          - 'null'
          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.
        exportFilter:
          allOf:
          - $ref: '#/components/schemas/ExportFilter'
          description: Recursive filter object which supports combining dimension and value filters
        friendlyHeaders:
          type:
          - boolean
          - 'null'
          description: If true, the exported CSV header will display metric friendly names. If null or not provided, it will display technical names.
        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.
        fieldDelimiter:
          allOf:
          - $ref: '#/components/schemas/ExportCsvDelimiter'
          description: The field delimiter to use in the csv export. Defaults to semicolon (;).
        decimalSeparator:
          allOf:
          - $ref: '#/components/schemas/ExportDecimalSeparator'
          description: The decimal separator to use in the csv export. Defaults to dot (.).
        encoding:
          allOf:
          - $ref: '#/components/schemas/ExportFileEncoding'
      additionalProperties: false
    PropertyFilter:
      required:
      - modalityIds
      - propertyTechnicalName
      type: object
      properties:
        propertyTechnicalName:
          type: string
        modalityIds:
          type: array
          items:
            type: string
            format: uuid
      additionalProperties: false
    ExportCsvDelimiter:
      enum:
      - Semicolon
      - Comma
      type: string
    ExportFileEncoding:
      enum:
      - Utf8WithBom
      - Utf8WithoutBom
      type: string
    TableRequest:
      type: object
      properties:
        metrics:
          type:
          - array
          - 'null'
          items:
            type: string
            format: uuid
        scenarios:
          type:
          - array
          - 'null'
          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.
        filters:
          type:
          - array
          - 'null'
          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.
        exportFilter:
          allOf:
          - $ref: '#/components/schemas/ExportFilter'
          description: Recursive filter object which supports combining dimension and value filters
        friendlyHeaders:
          type:
          - boolean
          - 'null'
          description: If true, the exported CSV header will display metric friendly names. If null or not provided, it will display technical names.
        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.
        fieldDelimiter:
          allOf:
          - $ref: '#/components/schemas/ExportCsvDelimiter'
          description: The field delimiter to use in the csv export. Defaults to semicolon (;).
        decimalSeparator:
          allOf:
          - $ref: '#/components/schemas/ExportDecimalSeparator'
          description: The decimal separator to use in the csv export. Defaults to dot (.).
        fields:
          type:
          - array
          - 'null'
          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.
        encoding:
          allOf:
          - $ref: '#/components/schemas/ExportFileEncoding'
      additionalProperties: false
  securitySchemes:
    ApiKey:
      type: http
      description: API Key Authorization header using the Bearer scheme.
      scheme: bearer
      bearerFormat: ApiKey