openapi: 3.0.3
info:
  title: Prices API V3 - OpenAPI 3.0
  description: >
    API for retrieving commodity prices across multiple markets with support for

    currency conversion, unit of measure conversion, and dynamic filtering based
    on market configuration.


    ## Authentication

    All endpoints (except `/health`) require Bearer token authentication.


    ## Authorization

    - **Prices endpoints**: Require market-specific authorization



    ## Business Rules

    - **Payable Type Prices**: Are percentages, no currency/unit conversion
    applied

    - **Price Type Prices**: Are monetary values, support currency/unit
    conversion
  contact:
    email: api-support@benchmarkminerals.com
  version: 1.0.0
externalDocs:
  description: Find out more about Swagger
  url: https://swagger.io
servers:
  - url: https://api.benchmarkminerals.com/v3/prices
    description: Production server
tags:
  - name: Health
    description: Health check endpoints
  - name: Lithium
    description: Lithium market prices
  - name: Manganese
    description: Manganese market prices
  - name: Lithium Ion Battery
    description: Lithium Ion Battery market prices
  - name: Cobalt
    description: Cobalt market prices
  - name: Anodes
    description: Anodes market prices
  - name: Cathodes
    description: Cathodes market prices
  - name: Electrolyte
    description: Electrolyte market prices
  - name: Natural Graphite
    description: Natural Graphite market prices
  - name: Rare Earths
    description: Rare Earths market prices
  - name: Synthetic Graphite
    description: Synthetic Graphite market prices
  - name: Recycling
    description: Recycling market prices
  - name: Nickel
    description: Nickel market prices
  - name: Aluminium
    description: Aluminium market prices
  - name: Binders And Additives
    description: Binders and Additives market prices
  - name: Precursor
    description: Precursor market prices
  - name: Solvent
    description: Solvent market prices
  - name: Copper
    description: Copper market prices
paths:
  /health:
    get:
      tags:
        - Health
      summary: Health check
      description: >-
        Returns the health status of the API. This endpoint does not require
        authentication.
      operationId: getHealth
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
              example:
                status: ok
  /lithium:
    post:
      tags:
        - Lithium
      summary: Get Lithium market prices
      description: >
        Retrieve prices for the Lithium market with dynamic filtering.


        **Available filters for Lithium:**

        - products, priceCategories, priceTypes (base filters)

        - purities, incoterms, countries, regions, tradeTypes, grades
        (market-specific)

        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getLithiumPrices
      security:
        - bearerAuth: []
          api_key:
            - prices:lithium
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LithiumPricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
                    includeSummary: false
              Filtered by date range:
                summary: Request with multiple filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - Lithium Carbonate
                      - Lithium Hydroxide
                    purities:
                      - 99.5%
                    incoterms:
                      - CIF
                    countries:
                      - China
                    regions:
                      - Asia
                    tradeTypes:
                      - Spot
                    grades:
                      - Battery Grade
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: EUR
                    unitOfMeasure: tonne
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - LI-0001
                      - LI-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              List available price series:
                summary: Get available prices (no series, no summary)
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: false
                    includeSummary: false
              Include summary statistics:
                summary: Request with summary statistics
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
                    includeSummary: true
      responses:
        '200':
          description: Successful response with Lithium prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
              examples:
                withSeries:
                  summary: Response with price series
                  value:
                    $metadata:
                      market: Lithium
                    data:
                      - code: LI-0001
                        name: >-
                          Lithium Carbonate, battery grade, CIF China, Japan &
                          Korea
                        shortName: Li2CO3 BG
                        specification:
                          - name: Grade
                            value: Battery Grade
                            order: 1
                          - name: Purity
                            value: 99.5% Li2CO3
                            order: 2
                        assessmentLaunchedAt: '2020-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440000
                          name: Lithium Carbonate
                          alias: Li2CO3
                          chemicalCode: Li2CO3
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440003
                          name: 99.5%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        tradeType:
                          id: 550e8400-e29b-41d4-a716-446655440007
                          name: Spot
                        grade: Battery Grade
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        series:
                          - date: '2024-12-15'
                            valueHigh: 12800
                            valueLow: 12200
                            valueMid: 12500
                          - date: '2024-12-08'
                            valueHigh: 12600
                            valueLow: 12000
                            valueMid: 12300
                withSummary:
                  summary: Response with series and summary statistics
                  value:
                    $metadata:
                      market: Lithium
                    data:
                      - code: LI-0001
                        name: >-
                          Lithium Carbonate, battery grade, CIF China, Japan &
                          Korea
                        shortName: Li2CO3 BG
                        specification:
                          - name: Grade
                            value: Battery Grade
                            order: 1
                          - name: Purity
                            value: 99.5% Li2CO3
                            order: 2
                        assessmentLaunchedAt: '2020-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440000
                          name: Lithium Carbonate
                          alias: Li2CO3
                          chemicalCode: Li2CO3
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440003
                          name: 99.5%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        tradeType:
                          id: 550e8400-e29b-41d4-a716-446655440007
                          name: Spot
                        grade: Battery Grade
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        summary:
                          latestPublication:
                            date: '2024-12-15'
                            valueHigh: 12800
                            valueLow: 12200
                            valueMid: 12500
                          previousPublication:
                            date: '2024-12-08'
                            valueHigh: 12600
                            valueLow: 12000
                            valueMid: 12300
                          changes:
                            unit: USD/kg
                            latest: 200
                            daily: 50
                            weekly: 200
                            biWeekly: 350
                            monthly: 500
                            quarterly: 1200
                            sixMonths: 2000
                            yearToDate: 3500
                            yearOnYear: 4000
                        series:
                          - date: '2024-12-15'
                            valueHigh: 12800
                            valueLow: 12200
                            valueMid: 12500
                          - date: '2024-12-08'
                            valueHigh: 12600
                            valueLow: 12000
                            valueMid: 12300
                availablePrices:
                  summary: Response with available prices only (no series, no summary)
                  value:
                    $metadata:
                      market: Lithium
                    data:
                      - code: LI-0001
                        name: >-
                          Lithium Carbonate, battery grade, CIF China, Japan &
                          Korea
                        shortName: Li2CO3 BG
                        specification:
                          - name: Grade
                            value: Battery Grade
                            order: 1
                          - name: Purity
                            value: 99.5% Li2CO3
                            order: 2
                        assessmentLaunchedAt: '2020-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440000
                          name: Lithium Carbonate
                          alias: Li2CO3
                          chemicalCode: Li2CO3
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440003
                          name: 99.5%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        tradeType:
                          id: 550e8400-e29b-41d4-a716-446655440007
                          name: Spot
                        grade: Battery Grade
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                      - code: LI-0002
                        name: >-
                          Lithium Hydroxide, battery grade, CIF China, Japan &
                          Korea
                        shortName: LiOH BG
                        specification:
                          - name: Grade
                            value: Battery Grade
                            order: 1
                          - name: Purity
                            value: 56.5% LiOH
                            order: 2
                        assessmentLaunchedAt: '2020-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440011
                          name: Lithium Hydroxide
                          alias: LiOH
                          chemicalCode: LiOH·H2O
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440012
                          name: 56.5%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        tradeType:
                          id: 550e8400-e29b-41d4-a716-446655440007
                          name: Spot
                        grade: Battery Grade
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /manganese:
    post:
      tags:
        - Manganese
      summary: Get Manganese market prices
      description: |
        Retrieve prices for the Manganese market with dynamic filtering.

        **Available filters for Manganese:**
        - products, priceCategories, priceTypes (base filters)
        - purities, incoterms, countries, regions, tradeTypes (market-specific)
        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getManganesePrices
      security:
        - bearerAuth: []
          api_key:
            - prices:manganese
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManganesePricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - Manganese Sulphate
                    purities:
                      - 99.5%
                    incoterms:
                      - FOB
                    countries:
                      - China
                    regions:
                      - Asia
                    tradeTypes:
                      - Contract
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - MN-0001
                      - MN-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              List available price series:
                summary: Get available prices (no series, no summary)
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: false
                    includeSummary: false
              Include summary statistics:
                summary: Request with summary statistics
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
                    includeSummary: true
      responses:
        '200':
          description: Successful response with Manganese prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
              examples:
                withSeries:
                  summary: Response with price series
                  value:
                    $metadata:
                      market: Manganese
                    data:
                      - code: MN-0001
                        name: >-
                          Manganese Sulphate Monohydrate, battery grade, FOB
                          China
                        shortName: MnSO4
                        specification:
                          - name: Grade
                            value: Battery Grade
                            order: 1
                          - name: Purity
                            value: 31.8% Mn
                            order: 2
                        assessmentLaunchedAt: '2021-03-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440020
                          name: Manganese Sulphate
                          alias: MnSO4
                          chemicalCode: MnSO4·H2O
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440021
                          name: 31.8% Mn
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        tradeType:
                          id: 550e8400-e29b-41d4-a716-446655440023
                          name: Contract
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        series:
                          - date: '2024-12-15'
                            valueHigh: 850
                            valueLow: 800
                            valueMid: 825
                          - date: '2024-12-08'
                            valueHigh: 840
                            valueLow: 790
                            valueMid: 815
                withSummary:
                  summary: Response with series and summary statistics
                  value:
                    $metadata:
                      market: Manganese
                    data:
                      - code: MN-0001
                        name: >-
                          Manganese Sulphate Monohydrate, battery grade, FOB
                          China
                        shortName: MnSO4
                        specification:
                          - name: Grade
                            value: Battery Grade
                            order: 1
                          - name: Purity
                            value: 31.8% Mn
                            order: 2
                        assessmentLaunchedAt: '2021-03-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440020
                          name: Manganese Sulphate
                          alias: MnSO4
                          chemicalCode: MnSO4·H2O
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440021
                          name: 31.8% Mn
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        tradeType:
                          id: 550e8400-e29b-41d4-a716-446655440023
                          name: Contract
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        summary:
                          latestPublication:
                            date: '2024-12-15'
                            valueHigh: 850
                            valueLow: 800
                            valueMid: 825
                          previousPublication:
                            date: '2024-12-08'
                            valueHigh: 840
                            valueLow: 790
                            valueMid: 815
                          changes:
                            unit: USD/kg
                            latest: 10
                            daily: 2.5
                            weekly: 10
                            biWeekly: 18
                            monthly: 35
                            quarterly: 85
                            sixMonths: 150
                            yearToDate: 280
                            yearOnYear: 320
                        series:
                          - date: '2024-12-15'
                            valueHigh: 850
                            valueLow: 800
                            valueMid: 825
                          - date: '2024-12-08'
                            valueHigh: 840
                            valueLow: 790
                            valueMid: 815
                availablePrices:
                  summary: Response with available prices only (no series, no summary)
                  value:
                    $metadata:
                      market: Manganese
                    data:
                      - code: MN-0001
                        name: >-
                          Manganese Sulphate Monohydrate, battery grade, FOB
                          China
                        shortName: MnSO4
                        specification:
                          - name: Grade
                            value: Battery Grade
                            order: 1
                          - name: Purity
                            value: 31.8% Mn
                            order: 2
                        assessmentLaunchedAt: '2021-03-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440020
                          name: Manganese Sulphate
                          alias: MnSO4
                          chemicalCode: MnSO4·H2O
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440021
                          name: 31.8% Mn
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        tradeType:
                          id: 550e8400-e29b-41d4-a716-446655440023
                          name: Contract
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                      - code: MN-0002
                        name: EMM, FOB China
                        shortName: EMM
                        specification:
                          - name: Grade
                            value: 99.7% Mn
                            order: 1
                        assessmentLaunchedAt: '2021-03-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440024
                          name: Electrolytic Manganese Metal
                          alias: EMM
                          chemicalCode: Mn
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440025
                          name: 99.7% Mn
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        tradeType:
                          id: 550e8400-e29b-41d4-a716-446655440023
                          name: Contract
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /lithium-ion-battery:
    post:
      tags:
        - Lithium Ion Battery
      summary: Get Lithium Ion Battery market prices
      description: >
        Retrieve prices for the Lithium Ion Battery market with dynamic
        filtering.


        **Available filters for Lithium Ion Battery:**

        - products, priceCategories, priceTypes (base filters)

        - capacities, cellFormats, incoterms, countries, regions, tradeTypes
        (market-specific)

        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getLithiumIonBatteryPrices
      security:
        - bearerAuth: []
          api_key:
            - prices:lithium-ion-battery
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatteryCellPricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - LFP Cell
                      - NMC Cell
                    capacities:
                      - 100Ah
                    cellFormats:
                      - Prismatic
                      - Cylindrical
                    incoterms:
                      - CIF
                    countries:
                      - China
                    regions:
                      - Asia
                    tradeTypes:
                      - Contract
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - BC-0001
                      - BC-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              List available price series:
                summary: Get available prices (no series, no summary)
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: false
                    includeSummary: false
              Include summary statistics:
                summary: Request with summary statistics
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
                    includeSummary: true
      responses:
        '200':
          description: Successful response with Lithium Ion Battery prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
              examples:
                withSeries:
                  summary: Response with price series
                  value:
                    $metadata:
                      market: Lithium Ion Battery
                    data:
                      - code: BC-0001
                        name: LFP Prismatic Cell, 100Ah, CIF Europe
                        shortName: LFP 100Ah
                    specification:
                      - name: Cell Format
                        value: Prismatic
                        order: 1
                      - name: Capacity
                        value: 100Ah
                        order: 2
                    assessmentLaunchedAt: '2022-01-15'
                    lastAssessedAt: '2024-12-15'
                    product:
                      id: 550e8400-e29b-41d4-a716-446655440030
                      name: LFP Cell
                      alias: LFP
                      chemicalCode: LiFePO4
                      isSustainable: true
                    priceCategory:
                      id: 550e8400-e29b-41d4-a716-446655440001
                      name: Spot
                    frequency:
                      id: 550e8400-e29b-41d4-a716-446655440002
                      name: Weekly
                      shortName: W
                    capacity:
                      id: 550e8400-e29b-41d4-a716-446655440031
                      name: 100Ah
                    cellFormat:
                      id: 550e8400-e29b-41d4-a716-446655440032
                      name: Prismatic
                    incoterm:
                      id: 550e8400-e29b-41d4-a716-446655440004
                      name: CIF
                    country:
                      id: 550e8400-e29b-41d4-a716-446655440033
                      name: Germany
                    region:
                      id: 550e8400-e29b-41d4-a716-446655440034
                      name: Europe
                    tradeType:
                      id: 550e8400-e29b-41d4-a716-446655440023
                      name: Contract
                    unitOfMeasure:
                      id: 550e8400-e29b-41d4-a716-446655440035
                      name: Kilowatt-hour
                      symbol: kWh
                    currency:
                      id: 550e8400-e29b-41d4-a716-446655440009
                      name: US Dollar
                      iso: USD
                      symbol: $
                    priceType:
                      id: 550e8400-e29b-41d4-a716-446655440010
                      name: Price
                    series:
                      - date: '2024-12-15'
                        valueHigh: 95
                        valueLow: 88
                        valueMid: 91.5
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /cobalt:
    post:
      tags:
        - Cobalt
      summary: Get Cobalt market prices
      description: |
        Retrieve prices for the Cobalt market with dynamic filtering.

        **Available filters for Cobalt:**
        - products, priceCategories, priceTypes (base filters)
        - purities, incoterms, countries, regions (market-specific)
        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getCobaltPrices
      security:
        - bearerAuth: []
          api_key:
            - prices:cobalt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CobaltPricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - Cobalt Sulphate
                    purities:
                      - 20.5% Co
                    incoterms:
                      - CIF
                    countries:
                      - China
                    regions:
                      - Asia
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - CO-0001
                      - CO-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              List available price series:
                summary: Get available prices (no series, no summary)
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: false
                    includeSummary: false
              Include summary statistics:
                summary: Request with summary statistics
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
                    includeSummary: true
      responses:
        '200':
          description: Successful response with Cobalt prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
              examples:
                withSeries:
                  summary: Response with price series
                  value:
                    $metadata:
                      market: Cobalt
                    data:
                      - code: CO-0001
                        name: Cobalt Sulphate, 20.5% Co, CIF China
                        shortName: CoSO4
                        specification: null
                      - name: Grade
                        value: Battery Grade
                        order: 1
                      - name: Purity
                        value: 20.5% Co
                        order: 2
                    assessmentLaunchedAt: '2019-06-01'
                    lastAssessedAt: '2024-12-15'
                    product:
                      id: 550e8400-e29b-41d4-a716-446655440040
                      name: Cobalt Sulphate
                      alias: CoSO4
                      chemicalCode: CoSO4
                      isSustainable: false
                    priceCategory:
                      id: 550e8400-e29b-41d4-a716-446655440001
                      name: Spot
                    frequency:
                      id: 550e8400-e29b-41d4-a716-446655440002
                      name: Weekly
                      shortName: W
                    purity:
                      id: 550e8400-e29b-41d4-a716-446655440041
                      name: 20.5% Co
                    incoterm:
                      id: 550e8400-e29b-41d4-a716-446655440004
                      name: CIF
                    country:
                      id: 550e8400-e29b-41d4-a716-446655440005
                      name: China
                    region:
                      id: 550e8400-e29b-41d4-a716-446655440006
                      name: Asia
                    unitOfMeasure:
                      id: 550e8400-e29b-41d4-a716-446655440008
                      name: Kilogram
                      symbol: kg
                    currency:
                      id: 550e8400-e29b-41d4-a716-446655440009
                      name: US Dollar
                      iso: USD
                      symbol: $
                    priceType:
                      id: 550e8400-e29b-41d4-a716-446655440010
                      name: Price
                    series:
                      - date: '2024-12-15'
                        valueHigh: 5200
                        valueLow: 4900
                        valueMid: 5050
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /anodes:
    post:
      tags:
        - Anodes
      summary: Get Anodes market prices
      description: |
        Retrieve prices for the Anodes market with dynamic filtering.

        **Available filters for Anodes:**
        - products, priceCategories, priceTypes (base filters)
        - capacities, purities, incoterms, countries, regions (market-specific)
        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getAnodesPrices
      security:
        - bearerAuth: []
          api_key:
            - prices:anodes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnodePricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
                    includeSummary: false
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - Synthetic Graphite Anode
                    capacities:
                      - 350mAh/g
                    purities:
                      - 99.95%
                    incoterms:
                      - FOB
                    countries:
                      - China
                    regions:
                      - Asia
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - AN-0001
                      - AN-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              List available price series:
                summary: Get available prices (no series, no summary)
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: false
                    includeSummary: false
              Include summary statistics:
                summary: Request with summary statistics
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
                    includeSummary: true
      responses:
        '200':
          description: Successful response with Anodes prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
              examples:
                withSeries:
                  summary: Response with price series
                  value:
                    $metadata:
                      market: Anodes
                    data:
                      - code: AN-0001
                        name: Synthetic Graphite Anode, 350mAh/g, FOB China
                        shortName: SG Anode
                        specification:
                          - name: Capacity
                            value: 350mAh/g
                            order: 1
                          - name: Purity
                            value: 99.95%
                            order: 2
                        assessmentLaunchedAt: '2021-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440050
                          name: Synthetic Graphite Anode
                          alias: SG Anode
                          chemicalCode: C
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        capacity:
                          id: 550e8400-e29b-41d4-a716-446655440051
                          name: 350mAh/g
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440052
                          name: 99.95%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        series:
                          - date: '2024-12-15'
                            valueHigh: 4500
                            valueLow: 4200
                            valueMid: 4350
                          - date: '2024-12-08'
                            valueHigh: 4400
                            valueLow: 4100
                            valueMid: 4250
                withSummary:
                  summary: Response with series and summary statistics
                  value:
                    $metadata:
                      market: Anode
                    data:
                      - code: AN-0001
                        name: Synthetic Graphite Anode, 350mAh/g, FOB China
                        shortName: SG Anode
                        specification:
                          - name: Capacity
                            value: 350mAh/g
                            order: 1
                          - name: Purity
                            value: 99.95%
                            order: 2
                        assessmentLaunchedAt: '2021-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440050
                          name: Synthetic Graphite Anode
                          alias: SG Anode
                          chemicalCode: C
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        capacity:
                          id: 550e8400-e29b-41d4-a716-446655440051
                          name: 350mAh/g
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440052
                          name: 99.95%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        summary:
                          latestPublication:
                            date: '2024-12-15'
                            valueHigh: 4500
                            valueLow: 4200
                            valueMid: 4350
                          previousPublication:
                            date: '2024-12-08'
                            valueHigh: 4400
                            valueLow: 4100
                            valueMid: 4250
                          changes:
                            unit: USD/kg
                            latest: 100
                            daily: 25
                            weekly: 100
                            biWeekly: 150
                            monthly: 200
                            quarterly: 400
                            sixMonths: 600
                            yearToDate: 800
                            yearOnYear: 1000
                        series:
                          - date: '2024-12-15'
                            valueHigh: 4500
                            valueLow: 4200
                            valueMid: 4350
                          - date: '2024-12-08'
                            valueHigh: 4400
                            valueLow: 4100
                            valueMid: 4250
                availablePrices:
                  summary: Response with available prices only (no series, no summary)
                  value:
                    $metadata:
                      market: Anode
                    data:
                      - code: AN-0001
                        name: Synthetic Graphite Anode, 350mAh/g, FOB China
                        shortName: SG Anode
                        specification:
                          - name: Capacity
                            value: 350mAh/g
                            order: 1
                          - name: Purity
                            value: 99.95%
                            order: 2
                        assessmentLaunchedAt: '2021-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440050
                          name: Synthetic Graphite Anode
                          alias: SG Anode
                          chemicalCode: C
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        capacity:
                          id: 550e8400-e29b-41d4-a716-446655440051
                          name: 350mAh/g
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440052
                          name: 99.95%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                      - code: AN-0002
                        name: Natural Graphite Anode, 340mAh/g, CIF Asia
                        shortName: NG Anode
                        specification:
                          - name: Capacity
                            value: 340mAh/g
                            order: 1
                          - name: Purity
                            value: 99.90%
                            order: 2
                        assessmentLaunchedAt: '2021-03-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440053
                          name: Natural Graphite Anode
                          alias: NG Anode
                          chemicalCode: C
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        capacity:
                          id: 550e8400-e29b-41d4-a716-446655440054
                          name: 340mAh/g
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440055
                          name: 99.90%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /cathodes:
    post:
      tags:
        - Cathodes
      summary: Get Cathodes market prices
      description: |
        Retrieve prices for the Cathodes market with dynamic filtering.

        **Available filters for Cathodes:**
        - products, priceCategories, priceTypes (base filters)
        - capacities, incoterms, countries, regions (market-specific)
        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getCathodesPrices
      security:
        - bearerAuth: []
          api_key:
            - prices:cathodes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CathodePricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - NMC 811
                      - LFP
                    capacities:
                      - 200mAh/g
                    incoterms:
                      - CIF
                    countries:
                      - South Korea
                    regions:
                      - Asia
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - CA-0001
                      - CA-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              List available price series:
                summary: Get available prices (no series, no summary)
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: false
                    includeSummary: false
              Include summary statistics:
                summary: Request with summary statistics
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
                    includeSummary: true
      responses:
        '200':
          description: Successful response with Cathodes prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
              examples:
                withSeries:
                  summary: Response with price series
                  value:
                    $metadata:
                      market: Cathodes
                    data:
                      - code: CA-0001
                        name: NMC 811 Cathode, CIF South Korea
                        shortName: NMC 811
                        specification:
                          - name: Capacity
                            value: 200mAh/g
                            order: 1
                        assessmentLaunchedAt: '2020-06-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440060
                          name: NMC 811
                          alias: NMC811
                          chemicalCode: LiNi0.8Mn0.1Co0.1O2
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        capacity:
                          id: 550e8400-e29b-41d4-a716-446655440061
                          name: 200mAh/g
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440062
                          name: South Korea
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        series:
                          - date: '2024-12-15'
                            valueHigh: 22000
                            valueLow: 20500
                            valueMid: 21250
                          - date: '2024-12-08'
                            valueHigh: 21800
                            valueLow: 20300
                            valueMid: 21050
                withSummary:
                  summary: Response with series and summary statistics
                  value:
                    $metadata:
                      market: Cathode
                    data:
                      - code: CA-0001
                        name: NMC 811 Cathode, CIF South Korea
                        shortName: NMC 811
                        specification:
                          - name: Capacity
                            value: 200mAh/g
                            order: 1
                        assessmentLaunchedAt: '2020-06-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440060
                          name: NMC 811
                          alias: NMC811
                          chemicalCode: LiNi0.8Mn0.1Co0.1O2
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        capacity:
                          id: 550e8400-e29b-41d4-a716-446655440061
                          name: 200mAh/g
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440062
                          name: South Korea
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        summary:
                          latestPublication:
                            date: '2024-12-15'
                            valueHigh: 22000
                            valueLow: 20500
                            valueMid: 21250
                          previousPublication:
                            date: '2024-12-08'
                            valueHigh: 21800
                            valueLow: 20300
                            valueMid: 21050
                          changes:
                            unit: USD/kg
                            latest: 200
                            daily: 50
                            weekly: 200
                            biWeekly: 350
                            monthly: 650
                            quarterly: 1500
                            sixMonths: 2800
                            yearToDate: 4500
                            yearOnYear: 5200
                        series:
                          - date: '2024-12-15'
                            valueHigh: 22000
                            valueLow: 20500
                            valueMid: 21250
                          - date: '2024-12-08'
                            valueHigh: 21800
                            valueLow: 20300
                            valueMid: 21050
                availablePrices:
                  summary: Response with available prices only (no series, no summary)
                  value:
                    $metadata:
                      market: Cathode
                    data:
                      - code: CA-0001
                        name: NMC 811 Cathode, CIF South Korea
                        shortName: NMC 811
                        specification:
                          - name: Capacity
                            value: 200mAh/g
                            order: 1
                        assessmentLaunchedAt: '2020-06-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440060
                          name: NMC 811
                          alias: NMC811
                          chemicalCode: LiNi0.8Mn0.1Co0.1O2
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        capacity:
                          id: 550e8400-e29b-41d4-a716-446655440061
                          name: 200mAh/g
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440062
                          name: South Korea
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                      - code: CA-0002
                        name: LFP Cathode, CIF China
                        shortName: LFP
                        specification:
                          - name: Capacity
                            value: 160mAh/g
                            order: 1
                        assessmentLaunchedAt: '2020-06-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440063
                          name: LFP
                          alias: LiFePO4
                          chemicalCode: LiFePO4
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        capacity:
                          id: 550e8400-e29b-41d4-a716-446655440064
                          name: 160mAh/g
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /electrolyte:
    post:
      tags:
        - Electrolyte
      summary: Get Electrolyte market prices
      description: |
        Retrieve prices for the Electrolyte market with dynamic filtering.

        **Available filters for Electrolyte:**
        - products, priceCategories, priceTypes (base filters)
        - purities, incoterms, countries, regions (market-specific)
        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getElectrolytePrices
      security:
        - bearerAuth: []
          api_key:
            - prices:electrolyte
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ElectrolytePricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - LiPF6
                    purities:
                      - 99.9%
                    incoterms:
                      - FOB
                    countries:
                      - China
                    regions:
                      - Asia
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - EL-0001
                      - EL-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              List available price series:
                summary: Get available prices (no series, no summary)
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: false
                    includeSummary: false
              Include summary statistics:
                summary: Request with summary statistics
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
                    includeSummary: true
      responses:
        '200':
          description: Successful response with Electrolyte prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
              examples:
                withSeries:
                  summary: Response with price series
                  value:
                    $metadata:
                      market: Electrolyte
                    data:
                      - code: EL-0001
                        name: LiPF6, 99.9%, FOB China
                        shortName: LiPF6
                        specification:
                          - name: Grade
                            value: Battery Grade
                            order: 1
                          - name: Purity
                            value: 99.9%
                            order: 2
                        assessmentLaunchedAt: '2021-03-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440070
                          name: LiPF6
                          alias: Lithium Hexafluorophosphate
                          chemicalCode: LiPF6
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440071
                          name: 99.9%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        series:
                          - date: '2024-12-15'
                            valueHigh: 12000
                            valueLow: 11000
                            valueMid: 11500
                          - date: '2024-12-08'
                            valueHigh: 11800
                            valueLow: 10800
                            valueMid: 11300
                withSummary:
                  summary: Response with series and summary statistics
                  value:
                    $metadata:
                      market: Electrolyte
                    data:
                      - code: EL-0001
                        name: LiPF6, 99.9%, FOB China
                        shortName: LiPF6
                        specification:
                          - name: Grade
                            value: Battery Grade
                            order: 1
                          - name: Purity
                            value: 99.9%
                            order: 2
                        assessmentLaunchedAt: '2021-03-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440070
                          name: LiPF6
                          alias: Lithium Hexafluorophosphate
                          chemicalCode: LiPF6
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440071
                          name: 99.9%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        summary:
                          latestPublication:
                            date: '2024-12-15'
                            valueHigh: 12000
                            valueLow: 11000
                            valueMid: 11500
                          previousPublication:
                            date: '2024-12-08'
                            valueHigh: 11800
                            valueLow: 10800
                            valueMid: 11300
                          changes:
                            unit: USD/kg
                            latest: 200
                            daily: 50
                            weekly: 200
                            biWeekly: 350
                            monthly: 600
                            quarterly: 1400
                            sixMonths: 2600
                            yearToDate: 4200
                            yearOnYear: 4800
                        series:
                          - date: '2024-12-15'
                            valueHigh: 12000
                            valueLow: 11000
                            valueMid: 11500
                          - date: '2024-12-08'
                            valueHigh: 11800
                            valueLow: 10800
                            valueMid: 11300
                availablePrices:
                  summary: Response with available prices only (no series, no summary)
                  value:
                    $metadata:
                      market: Electrolyte
                    data:
                      - code: EL-0001
                        name: LiPF6, 99.9%, FOB China
                        shortName: LiPF6
                        specification:
                          - name: Grade
                            value: Battery Grade
                            order: 1
                          - name: Purity
                            value: 99.9%
                            order: 2
                        assessmentLaunchedAt: '2021-03-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440070
                          name: LiPF6
                          alias: Lithium Hexafluorophosphate
                          chemicalCode: LiPF6
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440071
                          name: 99.9%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                      - code: EL-0002
                        name: EC/DMC Solvent, Battery Grade, FOB China
                        shortName: EC/DMC
                        specification:
                          - name: Grade
                            value: Battery Grade
                            order: 1
                        assessmentLaunchedAt: '2021-03-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440072
                          name: EC/DMC Solvent
                          alias: Electrolyte Solvent
                          chemicalCode: EC/DMC
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440073
                          name: 99.5%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /natural-graphite:
    post:
      tags:
        - Natural Graphite
      summary: Get Natural Graphite market prices
      description: |
        Retrieve prices for the Natural Graphite market with dynamic filtering.

        **Available filters for Natural Graphite:**
        - products, priceCategories, priceTypes (base filters)
        - meshSizes, purities, incoterms, countries, regions (market-specific)
        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getNaturalGraphitePrices
      security:
        - bearerAuth: []
          api_key:
            - prices:natural-graphite
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NaturalGraphitePricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - Flake Graphite
                    meshSizes:
                      - +100 mesh
                      - '-100 mesh'
                    purities:
                      - 94-95%
                    incoterms:
                      - FOB
                    countries:
                      - China
                    regions:
                      - Asia
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - NG-0001
                      - NG-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              List available price series:
                summary: Get available prices (no series, no summary)
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: false
                    includeSummary: false
              Include summary statistics:
                summary: Request with summary statistics
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
                    includeSummary: true
      responses:
        '200':
          description: Successful response with Natural Graphite prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
              examples:
                withSeries:
                  summary: Response with price series
                  value:
                    $metadata:
                      market: Natural Graphite
                    data:
                      - code: NG-0001
                        name: Flake Graphite, +100 mesh, 94-95%, FOB China
                        shortName: Flake +100
                        specification:
                          - name: Mesh Size
                            value: +100 mesh
                            order: 1
                          - name: Purity
                            value: 94-95% C
                            order: 2
                        assessmentLaunchedAt: '2019-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440080
                          name: Flake Graphite
                          alias: Flake
                          chemicalCode: C
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        meshSize:
                          id: 550e8400-e29b-41d4-a716-446655440081
                          name: +100 mesh
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440082
                          name: 94-95%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        series:
                          - date: '2024-12-15'
                            valueHigh: 750
                            valueLow: 680
                            valueMid: 715
                          - date: '2024-12-08'
                            valueHigh: 740
                            valueLow: 670
                            valueMid: 705
                withSummary:
                  summary: Response with series and summary statistics
                  value:
                    $metadata:
                      market: Natural Graphite
                    data:
                      - code: NG-0001
                        name: Flake Graphite, +100 mesh, 94-95%, FOB China
                        shortName: Flake +100
                        specification:
                          - name: Mesh Size
                            value: +100 mesh
                            order: 1
                          - name: Purity
                            value: 94-95% C
                            order: 2
                        assessmentLaunchedAt: '2019-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440080
                          name: Flake Graphite
                          alias: Flake
                          chemicalCode: C
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        meshSize:
                          id: 550e8400-e29b-41d4-a716-446655440081
                          name: +100 mesh
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440082
                          name: 94-95%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        summary:
                          latestPublication:
                            date: '2024-12-15'
                            valueHigh: 740
                            valueLow: 690
                            valueMid: 715
                          previousPublication:
                            date: '2024-12-08'
                            valueHigh: 730
                            valueLow: 680
                            valueMid: 705
                          changes:
                            unit: USD/kg
                            latest: 10
                            daily: 2.5
                            weekly: 10
                            biWeekly: 18
                            monthly: 35
                            quarterly: 85
                            sixMonths: 150
                            yearToDate: 280
                            yearOnYear: 320
                        series:
                          - date: '2024-12-15'
                            valueHigh: 750
                            valueLow: 680
                            valueMid: 715
                          - date: '2024-12-08'
                            valueHigh: 740
                            valueLow: 670
                            valueMid: 705
                availablePrices:
                  summary: Response with available prices only (no series, no summary)
                  value:
                    $metadata:
                      market: Natural Graphite
                    data:
                      - code: NG-0001
                        name: Flake Graphite, +100 mesh, 94-95%, FOB China
                        shortName: Flake +100
                        specification:
                          - name: Mesh Size
                            value: +100 mesh
                            order: 1
                          - name: Purity
                            value: 94-95% C
                            order: 2
                        assessmentLaunchedAt: '2019-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440080
                          name: Flake Graphite
                          alias: Flake
                          chemicalCode: C
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        meshSize:
                          id: 550e8400-e29b-41d4-a716-446655440081
                          name: +100 mesh
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440082
                          name: 94-95%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                      - code: NG-0002
                        name: Flake Graphite, -100 mesh, 94-95%, FOB China
                        shortName: Flake -100
                        specification:
                          - name: Mesh Size
                            value: '-100 mesh'
                            order: 1
                          - name: Purity
                            value: 94-95% C
                            order: 2
                        assessmentLaunchedAt: '2019-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440080
                          name: Flake Graphite
                          alias: Flake
                          chemicalCode: C
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        meshSize:
                          id: 550e8400-e29b-41d4-a716-446655440083
                          name: '-100 mesh'
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440082
                          name: 94-95%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /rare-earths:
    post:
      tags:
        - Rare Earths
      summary: Get Rare Earths market prices
      description: |
        Retrieve prices for the Rare Earths market with dynamic filtering.

        **Available filters for Rare Earths:**
        - products, priceCategories, priceTypes (base filters)
        - purities, incoterms, countries, regions (market-specific)
        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getRareEarthsPrices
      security:
        - bearerAuth: []
          api_key:
            - prices:rare-earths
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RareEarthsPricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - Neodymium Oxide
                      - Praseodymium Oxide
                    purities:
                      - 99.5%
                    incoterms:
                      - FOB
                    countries:
                      - China
                    regions:
                      - Asia
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - RE-0001
                      - RE-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              List available price series:
                summary: Get available prices (no series, no summary)
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: false
                    includeSummary: false
              Include summary statistics:
                summary: Request with summary statistics
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
                    includeSummary: true
      responses:
        '200':
          description: Successful response with Rare Earths prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
              examples:
                withSeries:
                  summary: Response with price series
                  value:
                    $metadata:
                      market: Rare Earths
                    data:
                      - code: RE-0001
                        name: Neodymium Oxide, 99.5%, FOB China
                        shortName: Nd2O3
                        specification:
                          - name: Purity
                            value: 99.5% Nd2O3
                            order: 1
                        assessmentLaunchedAt: '2020-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440090
                          name: Neodymium Oxide
                          alias: Nd2O3
                          chemicalCode: Nd2O3
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440091
                          name: 99.5%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        series:
                          - date: '2024-12-15'
                            valueHigh: 75000
                            valueLow: 70000
                            valueMid: 72500
                          - date: '2024-12-08'
                            valueHigh: 74000
                            valueLow: 69000
                            valueMid: 71500
                withSummary:
                  summary: Response with series and summary statistics
                  value:
                    $metadata:
                      market: Rare Earths
                    data:
                      - code: RE-0001
                        name: Neodymium Oxide, 99.5%, FOB China
                        shortName: Nd2O3
                        specification:
                          - name: Purity
                            value: 99.5% Nd2O3
                            order: 1
                        assessmentLaunchedAt: '2020-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440090
                          name: Neodymium Oxide
                          alias: Nd2O3
                          chemicalCode: Nd2O3
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440091
                          name: 99.5%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        summary:
                          latestPublication:
                            date: '2024-12-15'
                            valueHigh: 75000
                            valueLow: 70000
                            valueMid: 72500
                          previousPublication:
                            date: '2024-12-08'
                            valueHigh: 74000
                            valueLow: 69000
                            valueMid: 71500
                          changes:
                            unit: USD/kg
                            latest: 1000
                            daily: 250
                            weekly: 1000
                            biWeekly: 1800
                            monthly: 3500
                            quarterly: 8500
                            sixMonths: 15000
                            yearToDate: 28000
                            yearOnYear: 32000
                        series:
                          - date: '2024-12-15'
                            valueHigh: 75000
                            valueLow: 70000
                            valueMid: 72500
                          - date: '2024-12-08'
                            valueHigh: 74000
                            valueLow: 69000
                            valueMid: 71500
                availablePrices:
                  summary: Response with available prices only (no series, no summary)
                  value:
                    $metadata:
                      market: Rare Earths
                    data:
                      - code: RE-0001
                        name: Neodymium Oxide, 99.5%, FOB China
                        shortName: Nd2O3
                        specification:
                          - name: Purity
                            value: 99.5% Nd2O3
                            order: 1
                        assessmentLaunchedAt: '2020-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440090
                          name: Neodymium Oxide
                          alias: Nd2O3
                          chemicalCode: Nd2O3
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440091
                          name: 99.5%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                      - code: RE-0002
                        name: Praseodymium Oxide, 99.5%, FOB China
                        shortName: Pr6O11
                        specification:
                          - name: Purity
                            value: 99.5% Pr6O11
                            order: 1
                        assessmentLaunchedAt: '2020-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440092
                          name: Praseodymium Oxide
                          alias: Pr6O11
                          chemicalCode: Pr6O11
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440091
                          name: 99.5%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /synthetic-graphite:
    post:
      tags:
        - Synthetic Graphite
      summary: Get Synthetic Graphite market prices
      description: >
        Retrieve prices for the Synthetic Graphite market with dynamic
        filtering.


        **Available filters for Synthetic Graphite:**

        - products, priceCategories, priceTypes (base filters)

        - purities, incoterms, countries, regions, services (market-specific)

        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getSyntheticGraphitePrices
      security:
        - bearerAuth: []
          api_key:
            - prices:synthetic-graphite
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyntheticGraphitePricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - Synthetic Graphite
                    purities:
                      - 99.95%
                    incoterms:
                      - FOB
                    countries:
                      - China
                    regions:
                      - Asia
                    services:
                      - Graphitization
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - SG-0001
                      - SG-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              List available price series:
                summary: Get available prices (no series, no summary)
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: false
                    includeSummary: false
              Include summary statistics:
                summary: Request with summary statistics
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
                    includeSummary: true
      responses:
        '200':
          description: Successful response with Synthetic Graphite prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
              examples:
                withSeries:
                  summary: Response with price series
                  value:
                    $metadata:
                      market: Synthetic Graphite
                    data:
                      - code: SG-0001
                        name: Synthetic Graphite, 99.95%, FOB China
                        shortName: Syn Graphite
                        specification:
                          - name: Purity
                            value: 99.95% C
                            order: 1
                        assessmentLaunchedAt: '2021-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440100
                          name: Synthetic Graphite
                          alias: SG
                          chemicalCode: C
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440101
                          name: 99.95%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        service:
                          id: 550e8400-e29b-41d4-a716-446655440102
                          name: Graphitization
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        series:
                          - date: '2024-12-15'
                            valueHigh: 8500
                            valueLow: 8000
                            valueMid: 8250
                          - date: '2024-12-08'
                            valueHigh: 8400
                            valueLow: 7900
                            valueMid: 8150
                withSummary:
                  summary: Response with series and summary statistics
                  value:
                    $metadata:
                      market: Synthetic Graphite
                    data:
                      - code: SG-0001
                        name: Synthetic Graphite, 99.95%, FOB China
                        shortName: Syn Graphite
                        specification:
                          - name: Purity
                            value: 99.95% C
                            order: 1
                        assessmentLaunchedAt: '2021-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440100
                          name: Synthetic Graphite
                          alias: SG
                          chemicalCode: C
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440101
                          name: 99.95%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        service:
                          id: 550e8400-e29b-41d4-a716-446655440102
                          name: Graphitization
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        summary:
                          latestPublication:
                            date: '2024-12-15'
                            valueHigh: 8500
                            valueLow: 8000
                            valueMid: 8250
                          previousPublication:
                            date: '2024-12-08'
                            valueHigh: 8400
                            valueLow: 7900
                            valueMid: 8150
                          changes:
                            unit: USD/kg
                            latest: 100
                            daily: 25
                            weekly: 100
                            biWeekly: 175
                            monthly: 320
                            quarterly: 750
                            sixMonths: 1400
                            yearToDate: 2200
                            yearOnYear: 2600
                        series:
                          - date: '2024-12-15'
                            valueHigh: 8500
                            valueLow: 8000
                            valueMid: 8250
                          - date: '2024-12-08'
                            valueHigh: 8400
                            valueLow: 7900
                            valueMid: 8150
                availablePrices:
                  summary: Response with available prices only (no series, no summary)
                  value:
                    $metadata:
                      market: Synthetic Graphite
                    data:
                      - code: SG-0001
                        name: Synthetic Graphite, 99.95%, FOB China
                        shortName: Syn Graphite
                        specification:
                          - name: Purity
                            value: 99.95% C
                            order: 1
                        assessmentLaunchedAt: '2021-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440100
                          name: Synthetic Graphite
                          alias: SG
                          chemicalCode: C
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440101
                          name: 99.95%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        service:
                          id: 550e8400-e29b-41d4-a716-446655440102
                          name: Graphitization
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                      - code: SG-0002
                        name: Synthetic Graphite Anode, 99.9%, CIF Japan
                        shortName: SG Anode
                        specification:
                          - name: Purity
                            value: 99.9% C
                            order: 1
                        assessmentLaunchedAt: '2021-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440103
                          name: Synthetic Graphite Anode
                          alias: SGA
                          chemicalCode: C
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440104
                          name: 99.9%
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440105
                          name: Japan
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        service:
                          id: 550e8400-e29b-41d4-a716-446655440102
                          name: Graphitization
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /recycling:
    post:
      tags:
        - Recycling
      summary: Get Recycling market prices
      description: >
        Retrieve prices for the Recycling market with dynamic filtering.


        **Available filters for Recycling:**

        - products, priceCategories, priceTypes (base filters)

        - incoterms, countries, regions, subProducts, feedstocks
        (market-specific)

        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getRecyclingPrices
      security:
        - bearerAuth: []
          api_key:
            - prices:recycling
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecyclingPricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - Black Mass
                    subProducts:
                      - Lithium
                      - Cobalt
                    feedstocks:
                      - LFP Batteries
                      - NMC Batteries
                    incoterms:
                      - CIF
                    countries:
                      - China
                    regions:
                      - Asia
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - RC-0001
                      - RC-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              List available price series:
                summary: Get available prices (no series, no summary)
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: false
                    includeSummary: false
              Include summary statistics:
                summary: Request with summary statistics
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
                    includeSummary: true
      responses:
        '200':
          description: Successful response with Recycling prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
              examples:
                withSeries:
                  summary: Response with price series
                  value:
                    $metadata:
                      market: Recycling
                    data:
                      - code: RC-0001
                        name: Black Mass, Lithium content, CIF China
                        shortName: BM Li
                        specification:
                          - name: Feedstock
                            value: LFP Batteries
                            order: 1
                          - name: Sub Product
                            value: Lithium
                            order: 2
                        assessmentLaunchedAt: '2023-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440110
                          name: Black Mass
                          alias: BM
                          chemicalCode: null
                          isSustainable: true
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        subProduct:
                          id: 550e8400-e29b-41d4-a716-446655440111
                          name: Lithium
                        feedstock:
                          id: 550e8400-e29b-41d4-a716-446655440112
                          name: LFP Batteries
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        series:
                          - date: '2024-12-15'
                            valueHigh: 2500
                            valueLow: 2200
                            valueMid: 2350
                          - date: '2024-12-08'
                            valueHigh: 2450
                            valueLow: 2150
                            valueMid: 2300
                withSummary:
                  summary: Response with series and summary statistics
                  value:
                    $metadata:
                      market: Recycling
                    data:
                      - code: RC-0001
                        name: Black Mass, Lithium content, CIF China
                        shortName: BM Li
                        specification:
                          - name: Feedstock
                            value: LFP Batteries
                            order: 1
                          - name: Sub Product
                            value: Lithium
                            order: 2
                        assessmentLaunchedAt: '2023-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440110
                          name: Black Mass
                          alias: BM
                          chemicalCode: null
                          isSustainable: true
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        subProduct:
                          id: 550e8400-e29b-41d4-a716-446655440111
                          name: Lithium
                        feedstock:
                          id: 550e8400-e29b-41d4-a716-446655440112
                          name: LFP Batteries
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        summary:
                          latestPublication:
                            date: '2024-12-15'
                            valueHigh: 2450
                            valueLow: 2250
                            valueMid: 2350
                          previousPublication:
                            date: '2024-12-08'
                            valueHigh: 2400
                            valueLow: 2200
                            valueMid: 2300
                          changes:
                            unit: USD/kg
                            latest: 50
                            daily: 12.5
                            weekly: 50
                            biWeekly: 85
                            monthly: 150
                            quarterly: 350
                            sixMonths: 650
                            yearToDate: 1100
                            yearOnYear: 1250
                        series:
                          - date: '2024-12-15'
                            valueHigh: 2500
                            valueLow: 2200
                            valueMid: 2350
                          - date: '2024-12-08'
                            valueHigh: 2450
                            valueLow: 2150
                            valueMid: 2300
                availablePrices:
                  summary: Response with available prices only (no series, no summary)
                  value:
                    $metadata:
                      market: Recycling
                    data:
                      - code: RC-0001
                        name: Black Mass, Lithium content, CIF China
                        shortName: BM Li
                        specification:
                          - name: Feedstock
                            value: LFP Batteries
                            order: 1
                          - name: Sub Product
                            value: Lithium
                            order: 2
                        assessmentLaunchedAt: '2023-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440110
                          name: Black Mass
                          alias: BM
                          chemicalCode: null
                          isSustainable: true
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        subProduct:
                          id: 550e8400-e29b-41d4-a716-446655440111
                          name: Lithium
                        feedstock:
                          id: 550e8400-e29b-41d4-a716-446655440112
                          name: LFP Batteries
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                      - code: RC-0002
                        name: Black Mass, Cobalt content, FOB Europe
                        shortName: BM Co
                        specification:
                          - name: Feedstock
                            value: NMC Batteries
                            order: 1
                          - name: Sub Product
                            value: Cobalt
                            order: 2
                        assessmentLaunchedAt: '2023-01-15'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440110
                          name: Black Mass
                          alias: BM
                          chemicalCode: null
                          isSustainable: true
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        subProduct:
                          id: 550e8400-e29b-41d4-a716-446655440113
                          name: Cobalt
                        feedstock:
                          id: 550e8400-e29b-41d4-a716-446655440114
                          name: NMC Batteries
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440022
                          name: FOB
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440115
                          name: Germany
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440116
                          name: Europe
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /nickel:
    post:
      tags:
        - Nickel
      summary: Get Nickel market prices
      description: |
        Retrieve prices for the Nickel market with dynamic filtering.

        **Available filters for Nickel:**
        - products, priceCategories, priceTypes (base filters)
        - purities, incoterms, countries, regions, services (market-specific)
        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getNickelPrices
      security:
        - bearerAuth: []
          api_key:
            - prices:nickel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NickelPricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - Nickel Sulphate
                      - MHP
                    purities:
                      - 22% Ni
                    incoterms:
                      - CIF
                    countries:
                      - Indonesia
                    regions:
                      - Asia
                    services:
                      - Conversion
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - NI-0001
                      - NI-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              List available price series:
                summary: Get available prices (no series, no summary)
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: false
                    includeSummary: false
              Include summary statistics:
                summary: Request with summary statistics
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
                    includeSummary: true
      responses:
        '200':
          description: Successful response with Nickel prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
              examples:
                withSeries:
                  summary: Response with price series
                  value:
                    $metadata:
                      market: Nickel
                    data:
                      - code: NI-0001
                    name: Nickel Sulphate, 22% Ni, CIF China
                    shortName: NiSO4
                    specification:
                      - name: Purity
                        value: 22% Ni
                        order: 1
                      - name: Grade
                        value: Battery Grade
                        order: 2
                    assessmentLaunchedAt: '2021-06-01'
                    lastAssessedAt: '2024-12-15'
                    product:
                      id: 550e8400-e29b-41d4-a716-446655440120
                      name: Nickel Sulphate
                      alias: NiSO4
                      chemicalCode: NiSO4·6H2O
                      isSustainable: false
                    priceCategory:
                      id: 550e8400-e29b-41d4-a716-446655440001
                      name: Spot
                    frequency:
                      id: 550e8400-e29b-41d4-a716-446655440002
                      name: Weekly
                      shortName: W
                    purity:
                      id: 550e8400-e29b-41d4-a716-446655440121
                      name: 22% Ni
                    incoterm:
                      id: 550e8400-e29b-41d4-a716-446655440004
                      name: CIF
                    country:
                      id: 550e8400-e29b-41d4-a716-446655440005
                      name: China
                    region:
                      id: 550e8400-e29b-41d4-a716-446655440006
                      name: Asia
                    service:
                      id: 550e8400-e29b-41d4-a716-446655440122
                      name: Conversion
                    unitOfMeasure:
                      id: 550e8400-e29b-41d4-a716-446655440008
                      name: Kilogram
                      symbol: kg
                    currency:
                      id: 550e8400-e29b-41d4-a716-446655440009
                      name: US Dollar
                      iso: USD
                      symbol: $
                    priceType:
                      id: 550e8400-e29b-41d4-a716-446655440010
                      name: Price
                    series:
                      - date: '2024-12-15'
                        valueHigh: 4200
                        valueLow: 3900
                        valueMid: 4050
                      - date: '2024-12-08'
                        valueHigh: 4150
                        valueLow: 3850
                        valueMid: 4000
                withSummary:
                  summary: Response with series and summary statistics
                  value:
                    $metadata:
                      market: Nickel
                    data:
                      - code: NI-0001
                        name: Nickel Sulphate, 22% Ni, CIF China
                        shortName: NiSO4
                        specification:
                          - name: Purity
                            value: 22% Ni
                            order: 1
                          - name: Grade
                            value: Battery Grade
                            order: 2
                        assessmentLaunchedAt: '2021-06-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440120
                          name: Nickel Sulphate
                          alias: NiSO4
                          chemicalCode: NiSO4·6H2O
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440121
                          name: 22% Ni
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        service:
                          id: 550e8400-e29b-41d4-a716-446655440122
                          name: Conversion
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                        summary:
                          latestPublication:
                            date: '2024-12-15'
                            valueHigh: 4200
                            valueLow: 3900
                            valueMid: 4050
                          previousPublication:
                            date: '2024-12-08'
                            valueHigh: 4150
                            valueLow: 3850
                            valueMid: 4000
                          changes:
                            unit: USD/kg
                            latest: 50
                            daily: 12.5
                            weekly: 50
                            biWeekly: 85
                            monthly: 150
                            quarterly: 380
                            sixMonths: 650
                            yearToDate: 1100
                            yearOnYear: 1250
                        series:
                          - date: '2024-12-15'
                            valueHigh: 4200
                            valueLow: 3900
                            valueMid: 4050
                          - date: '2024-12-08'
                            valueHigh: 4150
                            valueLow: 3850
                            valueMid: 4000
                availablePrices:
                  summary: Response with available prices only (no series, no summary)
                  value:
                    $metadata:
                      market: Nickel
                    data:
                      - code: NI-0001
                        name: Nickel Sulphate, 22% Ni, CIF China
                        shortName: NiSO4
                        specification:
                          - name: Purity
                            value: 22% Ni
                            order: 1
                          - name: Grade
                            value: Battery Grade
                            order: 2
                        assessmentLaunchedAt: '2021-06-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440120
                          name: Nickel Sulphate
                          alias: NiSO4
                          chemicalCode: NiSO4·6H2O
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440121
                          name: 22% Ni
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        service:
                          id: 550e8400-e29b-41d4-a716-446655440122
                          name: Conversion
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
                      - code: NI-0002
                        name: MHP, 35% Ni, CIF China
                        shortName: MHP
                        specification:
                          - name: Purity
                            value: 35% Ni
                            order: 1
                        assessmentLaunchedAt: '2021-06-01'
                        lastAssessedAt: '2024-12-15'
                        product:
                          id: 550e8400-e29b-41d4-a716-446655440123
                          name: Mixed Hydroxide Precipitate
                          alias: MHP
                          chemicalCode: Ni(OH)2
                          isSustainable: false
                        priceCategory:
                          id: 550e8400-e29b-41d4-a716-446655440001
                          name: Spot
                        frequency:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Weekly
                          shortName: W
                        purity:
                          id: 550e8400-e29b-41d4-a716-446655440124
                          name: 35% Ni
                        incoterm:
                          id: 550e8400-e29b-41d4-a716-446655440004
                          name: CIF
                        country:
                          id: 550e8400-e29b-41d4-a716-446655440005
                          name: China
                        region:
                          id: 550e8400-e29b-41d4-a716-446655440006
                          name: Asia
                        service:
                          id: 550e8400-e29b-41d4-a716-446655440125
                          name: Processing
                        unitOfMeasure:
                          id: 550e8400-e29b-41d4-a716-446655440008
                          name: Kilogram
                          symbol: kg
                        currency:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          name: US Dollar
                          iso: USD
                          symbol: $
                        priceType:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          name: Price
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /aluminium:
    post:
      tags:
        - Aluminium
      summary: Get Aluminium market prices
      description: |
        Retrieve prices for the Aluminium market with dynamic filtering.

        **Available filters for Aluminium:**
        - products, priceCategories, priceTypes (base filters)
        - incoterms, countries, regions (market-specific)
        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getAluminiumPrices
      security:
        - bearerAuth: []
          api_key:
            - prices:aluminium
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AluminiumPricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - Aluminium
                    incoterms:
                      - CIF
                    countries:
                      - China
                    regions:
                      - Asia
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - AL-0001
                      - AL-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
      responses:
        '200':
          description: Successful response with Aluminium prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /binders-and-additives:
    post:
      tags:
        - Binders And Additives
      summary: Get Binders and Additives market prices
      description: >
        Retrieve prices for the Binders and Additives market with dynamic
        filtering.


        **Available filters for Binders and Additives:**

        - products, priceCategories, priceTypes (base filters)

        - incoterms, countries, regions (market-specific)

        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getBindersAndAdditivesPrices
      security:
        - bearerAuth: []
          api_key:
            - prices:binders-and-additives
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindersAndAdditivesPricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - PVDF
                      - CMC
                    incoterms:
                      - CIF
                    countries:
                      - China
                    regions:
                      - Asia
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - BA-0001
                      - BA-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
      responses:
        '200':
          description: Successful response with Binders and Additives prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /precursor:
    post:
      tags:
        - Precursor
      summary: Get Precursor market prices
      description: |
        Retrieve prices for the Precursor market with dynamic filtering.

        **Available filters for Precursor:**
        - products, priceCategories, priceTypes (base filters)
        - incoterms, countries, regions (market-specific)
        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getPrecursorPrices
      security:
        - bearerAuth: []
          api_key:
            - prices:precursor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrecursorPricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - pCAM
                    incoterms:
                      - CIF
                    countries:
                      - China
                    regions:
                      - Asia
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - PC-0001
                      - PC-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
      responses:
        '200':
          description: Successful response with Precursor prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /solvent:
    post:
      tags:
        - Solvent
      summary: Get Solvent market prices
      description: |
        Retrieve prices for the Solvent market with dynamic filtering.

        **Available filters for Solvent:**
        - products, priceCategories, priceTypes (base filters)
        - incoterms, countries, regions (market-specific)
        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getSolventPrices
      security:
        - bearerAuth: []
          api_key:
            - prices:solvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SolventPricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - EC/DMC Solvent
                    incoterms:
                      - FOB
                    countries:
                      - China
                    regions:
                      - Asia
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - SV-0001
                      - SV-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
      responses:
        '200':
          description: Successful response with Solvent prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /copper:
    post:
      tags:
        - Copper
      summary: Get Copper market prices
      description: |
        Retrieve prices for the Copper market with dynamic filtering.

        **Available filters for Copper:**
        - products, priceCategories, priceTypes (base filters)
        - incoterms, countries, regions (market-specific)
        - codes (exclusive filter - when used, only dateFrom/dateTo allowed)
      operationId: getCopperPrices
      security:
        - bearerAuth: []
          api_key:
            - prices:copper
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CopperPricesRequest'
            examples:
              Basic request:
                summary: Basic request with date range
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
              Filtered by date range:
                summary: Request with filters
                value:
                  filters:
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                    products:
                      - Copper Foil
                    incoterms:
                      - CIF
                    countries:
                      - China
                    regions:
                      - Asia
                  options:
                    includeSeries: true
                    includeSummary: true
                    currency: USD
              Filter by product codes:
                summary: Request by specific codes
                value:
                  filters:
                    codes:
                      - CU-0001
                      - CU-0002
                    dateFrom: '2024-01-01'
                    dateTo: '2024-12-31'
                  options:
                    includeSeries: true
      responses:
        '200':
          description: Successful response with Copper prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleMarketPricesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    BaseFilters:
      type: object
      properties:
        codes:
          type: array
          items:
            type: string
          description: >
            Exclusive filter - when provided, only dateFrom and dateTo are
            allowed.

            Filter by specific price codes.
          example:
            - LI-0001
            - LI-0002
        dateFrom:
          type: string
          format: date
          description: Start date for price series (YYYY-MM-DD)
          example: '2024-01-01'
        dateTo:
          type: string
          format: date
          description: End date for price series (YYYY-MM-DD)
          example: '2024-12-31'
        products:
          type: array
          items:
            type: string
          description: Filter by product names
          example:
            - Lithium Carbonate
        priceCategories:
          type: array
          items:
            type: string
          description: Filter by price categories
          example:
            - Spot
            - Contract
        priceTypes:
          type: array
          items:
            type: string
          description: Filter by price types
          example:
            - Payable
            - Price
    PriceOptions:
      type: object
      properties:
        includeSeries:
          type: boolean
          default: true
          description: Include price series data
        includeSummary:
          type: boolean
          default: false
          description: Include summary statistics
        currency:
          type: string
          minLength: 3
          maxLength: 3
          description: ISO 4217 currency code for conversion
          example: USD
        unitOfMeasure:
          type: string
          description: Unit of measure for conversion
          example: tonne
    LithiumPricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                purities:
                  type: array
                  items:
                    type: string
                  example:
                    - 99.5%
                incoterms:
                  type: array
                  items:
                    type: string
                  example:
                    - CIF
                    - FOB
                countries:
                  type: array
                  items:
                    type: string
                  example:
                    - China
                regions:
                  type: array
                  items:
                    type: string
                  example:
                    - Asia
                tradeTypes:
                  type: array
                  items:
                    type: string
                  example:
                    - Spot
                    - Contract
                grades:
                  type: array
                  items:
                    type: string
                  example:
                    - Battery Grade
                    - Technical Grade
        options:
          $ref: '#/components/schemas/PriceOptions'
    ManganesePricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                purities:
                  type: array
                  items:
                    type: string
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
                tradeTypes:
                  type: array
                  items:
                    type: string
        options:
          $ref: '#/components/schemas/PriceOptions'
    BatteryCellPricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                capacities:
                  type: array
                  items:
                    type: string
                  example:
                    - 100Ah
                cellFormats:
                  type: array
                  items:
                    type: string
                  example:
                    - Prismatic
                    - Cylindrical
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
                tradeTypes:
                  type: array
                  items:
                    type: string
        options:
          $ref: '#/components/schemas/PriceOptions'
    CobaltPricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                purities:
                  type: array
                  items:
                    type: string
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
        options:
          $ref: '#/components/schemas/PriceOptions'
    AnodePricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                capacities:
                  type: array
                  items:
                    type: string
                purities:
                  type: array
                  items:
                    type: string
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
        options:
          $ref: '#/components/schemas/PriceOptions'
    CathodePricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                capacities:
                  type: array
                  items:
                    type: string
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
        options:
          $ref: '#/components/schemas/PriceOptions'
    ElectrolytePricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                purities:
                  type: array
                  items:
                    type: string
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
        options:
          $ref: '#/components/schemas/PriceOptions'
    NaturalGraphitePricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                meshSizes:
                  type: array
                  items:
                    type: string
                  example:
                    - +100 mesh
                    - '-100 mesh'
                purities:
                  type: array
                  items:
                    type: string
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
        options:
          $ref: '#/components/schemas/PriceOptions'
    RareEarthsPricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                purities:
                  type: array
                  items:
                    type: string
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
        options:
          $ref: '#/components/schemas/PriceOptions'
    SyntheticGraphitePricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                purities:
                  type: array
                  items:
                    type: string
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
                services:
                  type: array
                  items:
                    type: string
                  example:
                    - Graphitization
        options:
          $ref: '#/components/schemas/PriceOptions'
    RecyclingPricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
                subProducts:
                  type: array
                  items:
                    type: string
                  description: Filter by sub-product types
                  example:
                    - Lithium
                    - Cobalt
                    - Nickel
                feedstocks:
                  type: array
                  items:
                    type: string
                  description: Filter by feedstock types
                  example:
                    - LFP Batteries
                    - NMC Batteries
        options:
          $ref: '#/components/schemas/PriceOptions'
    NickelPricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                purities:
                  type: array
                  items:
                    type: string
                  example:
                    - 22% Ni
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
                services:
                  type: array
                  items:
                    type: string
                  example:
                    - Conversion
        options:
          $ref: '#/components/schemas/PriceOptions'
    AluminiumPricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
        options:
          $ref: '#/components/schemas/PriceOptions'
    BindersAndAdditivesPricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
        options:
          $ref: '#/components/schemas/PriceOptions'
    PrecursorPricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
        options:
          $ref: '#/components/schemas/PriceOptions'
    SolventPricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
        options:
          $ref: '#/components/schemas/PriceOptions'
    CopperPricesRequest:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BaseFilters'
            - type: object
              properties:
                incoterms:
                  type: array
                  items:
                    type: string
                countries:
                  type: array
                  items:
                    type: string
                regions:
                  type: array
                  items:
                    type: string
        options:
          $ref: '#/components/schemas/PriceOptions'
    SingleMarketPricesResponse:
      type: object
      properties:
        $metadata:
          type: object
          properties:
            market:
              type: string
              description: Market name
        data:
          type: array
          items:
            $ref: '#/components/schemas/PriceRecord'
    PriceRecord:
      type: object
      properties:
        code:
          type: string
          description: Unique price code
        name:
          type: string
          description: Full price name
        shortName:
          type: string
          description: Short name
        specification:
          type: array
          description: Price specification items with structured data
          items:
            $ref: '#/components/schemas/SpecificationItem'
        assessmentLaunchedAt:
          type: string
          format: date
          description: Date when assessment was launched
        lastAssessedAt:
          type: string
          format: date
          description: Date of last assessment
        product:
          $ref: '#/components/schemas/Product'
        priceCategory:
          $ref: '#/components/schemas/IdName'
        frequency:
          $ref: '#/components/schemas/Frequency'
        purity:
          $ref: '#/components/schemas/IdName'
        incoterm:
          $ref: '#/components/schemas/IdName'
        country:
          $ref: '#/components/schemas/IdName'
        region:
          $ref: '#/components/schemas/IdName'
        tradeType:
          $ref: '#/components/schemas/IdName'
        grade:
          type: string
        capacity:
          $ref: '#/components/schemas/IdName'
        thickness:
          $ref: '#/components/schemas/IdName'
        cellFormat:
          $ref: '#/components/schemas/IdName'
        meshSize:
          $ref: '#/components/schemas/IdName'
        service:
          $ref: '#/components/schemas/IdName'
        subProduct:
          $ref: '#/components/schemas/SubProduct'
        feedstock:
          $ref: '#/components/schemas/IdName'
        sulphur:
          $ref: '#/components/schemas/IdName'
        unitOfMeasure:
          $ref: '#/components/schemas/UnitOfMeasure'
        currency:
          $ref: '#/components/schemas/Currency'
        priceType:
          $ref: '#/components/schemas/IdName'
        isIoscoAssured:
          type: boolean
          description: Indicates if the grade is IOSCO assured
        summary:
          $ref: '#/components/schemas/PriceSummary'
        series:
          type: array
          items:
            $ref: '#/components/schemas/PriceSeries'
    Product:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        alias:
          type: string
        chemicalCode:
          type: string
        isSustainable:
          type: boolean
    SubProduct:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        chemicalCode:
          type: string
    IdName:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
    Frequency:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        shortName:
          type: string
    UnitOfMeasure:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        symbol:
          type: string
    Currency:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        iso:
          type: string
        symbol:
          type: string
    PriceSummary:
      type: object
      properties:
        latestPublication:
          type: object
          properties:
            date:
              type: string
              format: date
            valueHigh:
              type: number
              nullable: true
            valueLow:
              type: number
              nullable: true
            valueMid:
              type: number
        previousPublication:
          type: object
          properties:
            date:
              type: string
              format: date
            valueHigh:
              type: number
              nullable: true
            valueLow:
              type: number
              nullable: true
            valueMid:
              type: number
        changes:
          type: object
          properties:
            unit:
              type: string
            latest:
              type: number
            daily:
              type: number
            weekly:
              type: number
            biWeekly:
              type: number
            monthly:
              type: number
            quarterly:
              type: number
            sixMonths:
              type: number
            yearToDate:
              type: number
            yearOnYear:
              type: number
    PriceSeries:
      type: object
      properties:
        date:
          type: string
          format: date
        valueHigh:
          type: number
        valueLow:
          type: number
        valueMid:
          type: number
    SpecificationItem:
      type: object
      description: A single specification item with name-value pair
      properties:
        name:
          type: string
          description: Specification attribute name
          example: Purity
        value:
          type: string
          description: Specification attribute value
          example: 99.5%
        order:
          type: integer
          description: Display order for the specification
          example: 1
  responses:
    BadRequest:
      description: Bad Request - Validation errors
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    location:
                      type: string
                      example: body
                    code:
                      type: string
                      example: invalid_type
                    property:
                      type: string
                      example: filters.dateFrom
                    message:
                      type: string
                      example: Expected string, received array
              message:
                type: string
                example: Invalid request parameters
          examples:
            validationError:
              summary: Validation error
              value:
                errors:
                  - location: body
                    code: invalid_type
                    property: filters.dateFrom
                    message: Invalid date format. Expected YYYY-MM-DD
                message: Invalid request parameters
            codesExclusivityError:
              summary: Codes filter exclusivity error
              value:
                errors:
                  - location: body
                    code: invalid_request
                    property: filters
                    message: >-
                      When 'codes' filter is provided, only 'dateFrom' and
                      'dateTo' filters are allowed
                message: Invalid request parameters
    Unauthorized:
      description: Unauthorized - Missing or invalid authentication
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
                example: AUTH-0001
              message:
                type: string
                example: Token expired
          example:
            code: AUTH-0001
            message: Token expired
    Forbidden:
      description: Forbidden - Insufficient permissions
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
                example: AUTH-0010
              message:
                type: string
                example: Forbidden
          example:
            code: AUTH-0010
            message: Forbidden - ADMIN role required
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
                example: RES-0001
              message:
                type: string
                example: Resource not found
          example:
            code: RES-0001
            message: Resource not found
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
                example: SRV-0001
              message:
                type: string
                example: Internal server error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token authentication
    api_key:
      type: apiKey
      name: x-api-key
      in: header
      description: >
        API Key authentication with scope-based authorization.


        Available scopes:

        - prices:lithium - Access to Lithium market prices

        - prices:manganese - Access to Manganese market prices

        - prices:lithium-ion-battery - Access to Lithium Ion Battery market
        prices

        - prices:cobalt - Access to Cobalt market prices

        - prices:anodes - Access to Anodes market prices

        - prices:cathodes - Access to Cathodes market prices

        - prices:electrolyte - Access to Electrolyte market prices

        - prices:natural-graphite - Access to Natural Graphite market prices

        - prices:rare-earths - Access to Rare Earths market prices

        - prices:synthetic-graphite - Access to Synthetic Graphite market prices

        - prices:recycling - Access to Recycling market prices

        - prices:nickel - Access to Nickel market prices

        - prices:aluminium - Access to Aluminium market prices

        - prices:binders-and-additives - Access to Binders and Additives market
        prices

        - prices:precursor - Access to Precursor market prices

        - prices:solvent - Access to Solvent market prices

        - prices:copper - Access to Copper market prices
