openapi: 3.1.0
info:
  description: >
    This API provides programmatic access to Kemiex's market intelligence data.
    Whether you're building internal dashboards, integrating with procurement
    systems, or developing custom market analysis tools, this API provides the
    structured data you need to leverage Kemiex's market intelligence.

    ## Response headers

    In addition to standard headers that you would expect, each response
    contains the following specific headers:


    | Header             |
    Description                                                                          
    |

    | ------------------ |
    -------------------------------------------------------------------------------------
    |

    | `X-Trace-Id`       | Trace identifier used to track each request against
    internal logs                     |

    | `X-Server-Version` | Version of the server that
    responded                                                  |


    When asking for support, please provide them as reference if possible.


    ## Error handling

    Kemiex uses conventional HTTP response codes to indicate the success or
    failure of an API request. In general: Codes in the `2xx` range indicate
    success. Codes in the `4xx` range indicate an error that failed given the
    information provided. Codes in the `5xx` range indicate an error with
    Kemiex’s servers.


    Unsuccessful responses contain 2 parts: an error code, and user-friendly
    message describing the issue. You can expect the following errors, though
    more may be added in the future:


    | <div style="min-width: 315px;">Error Code</div> |
    Description                                                                                                                        
    |

    | ---------------------------------------- |
    ------------------------------------------------------------------------------------------------------------------------------------------
    |

    | `BAD_REQUEST_RESOURCE_NOT_FOUND`         | Client-side error: the URL
    address is
    wrong                                                                                               
    |

    | `BAD_REQUEST_METHOD_NOT_SUPPORTED`       | Client-side error: the HTTP
    method used in the request is not supported by the
    endpoint                                                    |

    | `BAD_REQUEST_MISSING_REQUIRED_PARAMETER` | Client-side error: at least one
    of the required parameters is not
    provided                                                                 |

    | `BAD_REQUEST_PARAMETER_TYPE_MISMATCH`    | Client-side error: a parameter
    value does not match its expected
    type                                                                      |

    | `BAD_REQUEST_PARAMETER_VALUE_ILLEGAL`    | Client-side error: a parameter
    value is outside the range of values
    allowed                                                                |

    | `BAD_REQUEST`                            | General client-side error: The
    request cannot be processed. This is a catch-all error thrown when the
    errors above do not apply            |

    | `FORBIDDEN`                              | The API key is not provided, or
    the provided value is incorrect, or the associated account does not have
    access to the requested resource  |

    | `INTERNAL_SERVER_ERROR`                  | An unexpected condition was
    encountered on the
    server                                                                                     
    |


    ## Rate limits

    A rate limit of 100 quota units per minute is enforced. Exceeding this limit
    returns HTTP code 429. The table below lists the corresponding quota units
    consumed per api endpoint.

    | Endpoint           | Quota
    units                                                                          
    |

    | ------------------ |
    -------------------------------------------------------------------------------------
    |

    | `/price-benchmarks`| 1 unit |
  title: Market Radar API
  version: 1.0.0
servers:
  - url: https://api.kemiex.com
    description: Production API
tags:
  - name: Market News
    description: Operations related to market news
  - name: Price Benchmarks
    description: Operations related to reported prices
paths:
  /mr/v1/price-benchmarks:
    get:
      tags:
        - Price Benchmarks
      summary: Retrieve price points
      description: >-
        Returns weekly price points that include average, minimum, maximum, and
        own company submission values for the specified products and date range.
        Price Benchmark data is published every Wednesday.
      operationId: getPriceBenchmarks
      parameters:
        - name: products
          in: query
          description: |+
            A comma-separated list of product-region codes to query.


            ## Available products:

            | Code | Product |
            |------|-------------|
            | BIO  | Biotin (2%) |
            | DLM  | Dl-Methionine (99%) |
            | LYH  | L-Lysine Hcl (98%) |
            | LYS  | L-Lysine Sulfate (70%) |
            | THR  | L-Threonine |
            | TRP  | L-Tryptophan |
            | VAL  | L-Valine |
            | VTA  | Vitamin A (1'000) |
            | V12  | Vitamin B12 (1% HPLC) |
            | VB1  | Vitamin B1 (Mono) |
            | VB2  | Vitamin B2 (80%) |
            | VB3  | Vitamin B3 |
            | VB5  | Vitamin B5 (Calcium Pantothenate) |
            | VB6  | Vitamin B6 Hcl |
            | VB9  | Vitamin B9 (>96%) |
            | VTC  | Vitamin C (99% powder) |
            | VCP  | Vitamin C phosphate 35% |
            | VTD  | Vitamin D3 (500) |
            | VTE  | Vitamin E (50% Feed) |
            | VTK  | Vitamin K3 MNB |

            ## Available regions:

            | Code | Region |
            |------|-------------|
            | CN   | FOB China   |
            | EU   | FCA Europe  |
            | USE  | CFR US East |
            | USW  | CFR US West |

          required: true
          schema:
            type: array
            items:
              type: string
        - name: startDate
          in: query
          description: The start date for the price points series
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceBenchmarksResponse'
        '400':
          description: Bad Request
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad Request Example:
                  summary: Example of a 400 Bad Request error
                  description: Bad Request Example
                  value:
                    errorCode: BAD_REQUEST_MISSING_REQUIRED_PARAMETER
                    errorMessage: >-
                      Required request parameter 'startDate' for method
                      parameter type String is not present
        '403':
          description: Forbidden
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Forbidden Example:
                  summary: Example of a 403 Forbidden response
                  description: Forbidden Example
                  value:
                    errorCode: FORBIDDEN
                    errorMessage: >-
                      Access denied. Please ensure your API key is correctly
                      provided and that your account has access to the requested
                      resource.
        '404':
          description: Not Found
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
        '500':
          description: Internal Server Error
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Internal Server Error Example:
                  summary: Example of a 500 Internal Server Error
                  description: Internal Server Error Example
                  value:
                    errorCode: INTERNAL_SERVER_ERROR
                    errorMessage: An unexpected error occurred.
      security:
        - bearerAuth: []
  /mr/v1/market-news:
    get:
      tags:
        - Market News
      summary: Retrieve Market News
      description: >-
        Returns Market News that were published in the specified time interval
        and matching optional search criteria. The time interval boundaries are
        inclusive.
      operationId: findMarketNews
      parameters:
        - name: publishFrom
          in: query
          description: >-
            The published start date in <tt>ISO 8601-1:2019</tt> combined date
            and time standard
          required: true
          schema:
            type: string
            format: date-time
          examples:
            Value of a date in UTC/Zulu timezone:
              description: Specify the timestamp directly in Zulu timezone
              value: '2024-11-23T20:15:30Z'
            Direct value of a date in an offset timezone:
              description: >-
                In some cases, if the + sign is being used, it will be encoded
                as a space, but the server will put back the + instead of space.
                It is a convenient way to specify the desired timestamp in a
                local timezone, however, the timestamps in the results will be
                in Zulu timezone
              value: '2024-11-23T21:15:30+01:00'
            Encoded value of a date in an offset timezone:
              description: >-
                Explicitly encode the + sign. It is a convenient way to specify
                the desired timestamp in a local timezone, however, the
                timestamps in the results will be in Zulu timezone
              value: 2024-11-23T21:15:30%2B01:00
        - name: publishTo
          in: query
          description: >-
            The published end date in <tt>ISO 8601-1:2019</tt> combined date and
            time standard. If it is not provided, it is automatically set to the
            current date time
          required: false
          schema:
            type: string
            format: date-time
          examples:
            Value of a date in UTC/Zulu timezone:
              description: Specify the timestamp directly in Zulu timezone
              value: '2024-11-23T20:15:30Z'
            Direct value of a date in an offset timezone:
              description: >-
                In some cases, if the + sign is being used, it will be encoded
                as a space, but the server will put back the + instead of space.
                It is a convenient way to specify the desired timestamp in a
                local timezone, however, the timestamps in the results will be
                in Zulu timezone
              value: '2024-11-23T21:15:30+01:00'
            Encoded value of a date in an offset timezone:
              description: >-
                Explicitly encode the + sign. It is a convenient way to specify
                the desired timestamp in a local timezone, however, the
                timestamps in the results will be in Zulu timezone
              value: 2024-11-23T21:15:30%2B01:00
        - name: categories
          in: query
          description: >-
            An additional filter for searching market news related only to
            specific categories. In case multiple values are provided, we
            consider an AND operation between them (market news that have all
            values from the given list as categories will be considered
            matched).
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - Accident
                - Agriculture
                - Americas
                - Amino acids
                - Analysis
                - APIs
                - Asia
                - Commentary
                - Company news
                - Europe
                - Expansion
                - Featured
                - Feed additives
                - Financial reports
                - Food additives
                - Kemiex report
                - Legal and compliance
                - Logistics
                - Strategic transactions
                - Vitamins
        - name: textSearch
          in: query
          description: >-
            An additional filter for searching market news with title or summary
            complying the given full text search criteria. It can be constructed
            using the rules of websearch_to_tsquery postgresql function, in
            English language
          required: false
          schema:
            type: string
          examples:
            Phrase search:
              description: >-
                By specifying quotes around words, phrase search is being
                triggered. As before, the last word in the phrase will be
                considered a search prefix
              value: United States
            Not containing word search:
              description: >-
                Just put a dash in front of the word to mark the negation. Since
                it is a single word in this example, it will be considered as a
                search prefix (in this example, search criteria is 'NOT grow*',
                thus market news with title or summary containing also words
                'growth', 'growing' or other derivative words will be excluded
                from search results)
              value: '-grow'
            Single word search:
              description: >-
                This is the simplest case, just provide the searched word. Note
                that in this case the given word will be considered as a search
                prefix (thus in this example, 'growth', 'growing' or other
                derivative words will be matched)
              value: grow
            One of two words search:
              description: >-
                It is easy to search for one word or another, by specifying the
                'or' between them. Again, the last word will be considered as a
                search prefix (in this example, search criteria is 'grow OR
                pharma*', thus 'pharmaceutical' will also be a match. Same as
                before, if we change the order of the words the search results
                may be different)
              value: grow or pharma
            Two words search:
              description: >-
                When two or multiple regular words are provided, AND between
                them is considered implicitly. Note that in this case the last
                word will be considered as a search prefix (in this example,
                search criteria is 'grow AND pharma*', thus 'pharmaceutical'
                will also be a match. But if we change the order of the words
                the search results may be different)
              value: grow pharma
            Complex search:
              description: >-
                AND, OR, NOT and phrase searches can be combined, in order to
                create powerful search criteria
              value: '"United States" or (grow -pharma)'
        - name: page
          in: query
          description: List results on a specific page. Starting page is 1
          required: false
          schema:
            type: integer
            format: int32
            default: 1
            minimum: 1
          example: 1
        - name: pageSize
          in: query
          description: >-
            Maximum number of results that should be returned per page. Please
            keep it constant for requests across multiple pages, in order to
            correctly receive all results.
          required: false
          schema:
            type: integer
            format: int32
            default: 50
            maximum: 100
            minimum: 1
          example: 50
      responses:
        '200':
          description: OK
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageMarketNewsListingResponse'
        '400':
          description: Bad Request
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad Request Example:
                  summary: Example of a 400 Bad Request error
                  description: Bad Request Example
                  value:
                    errorCode: BAD_REQUEST_MISSING_REQUIRED_PARAMETER
                    errorMessage: >-
                      Required request parameter 'publishFrom' for method
                      parameter type OffsetDateTime is not present
        '403':
          description: Forbidden
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Forbidden Example:
                  summary: Example of a 403 Forbidden response
                  description: Forbidden Example
                  value:
                    errorCode: FORBIDDEN
                    errorMessage: >-
                      Access denied. Please ensure your API key is correctly
                      provided and that your account has access to the requested
                      resource.
        '404':
          description: Not Found
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
        '500':
          description: Internal Server Error
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Internal Server Error Example:
                  summary: Example of a 500 Internal Server Error
                  description: Internal Server Error Example
                  value:
                    errorCode: INTERNAL_SERVER_ERROR
                    errorMessage: An unexpected error occurred.
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: >-
            A predefined code representing the error encountered by the server
            while processing the request
          enum:
            - BAD_REQUEST
            - BAD_REQUEST_RESOURCE_NOT_FOUND
            - BAD_REQUEST_METHOD_NOT_SUPPORTED
            - BAD_REQUEST_MISSING_REQUIRED_PARAMETER
            - BAD_REQUEST_PARAMETER_TYPE_MISMATCH
            - BAD_REQUEST_PARAMETER_VALUE_ILLEGAL
            - FORBIDDEN
            - INTERNAL_SERVER_ERROR
        errorMessage:
          type: string
          description: A detailed, human-readable description of the error, in English
    PriceBenchmarksResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PricePoint'
    PricePoint:
      type: object
      properties:
        productCode:
          type: string
          description: The 3 letter product code
          example: VB1
        productName:
          type: string
          description: The main name of the product.
          example: Vitamin B1 (Mono)
        regionCode:
          type: string
          description: The region code.
          example: EU
        regionName:
          type: string
          description: The region name.
          example: FCA Europe
        week:
          type: string
          description: >-
            The Thursday date of the week for the price point. Even though data
            may be published on a different date, we list it on a Thursday,
            representing the corresponding week number according to ISO 8601.
          example: '2024-01-04'
        currency:
          type: string
          description: Currency of the price point
          example: USD
        unit:
          type: string
          description: Unit of measure of the price point
          example: MT
        average:
          type: number
          description: The average price for the week
          example: 15.75
        minimum:
          type: number
          description: The minimum price for the week
          example: 14.5
        maximum:
          type: number
          description: The maximum price for the week
          example: 16.25
        ownCompanySubmission:
          type: number
          description: The price submitted by own company for the week
          example: 15
    MarketNewsListingResponse:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          description: >-
            A unique identifier for the market news entry, ensuring each piece
            of news can be distinctly referenced.
          example: b43dd825-8a99-4676-aae7-9b91817c2c3c
        published:
          type: string
          format: date-time
          description: >-
            The date and time when the market news was published, in ISO 8601
            format (UTC/Zulu timezone).
          example: '2025-03-25T10:00:00Z'
        title:
          type: string
          description: The title of the market news article.
        summary:
          type: string
          description: >-
            A brief summary of the market news. This field may contain HTML
            tags. Consumers should properly handle or sanitize HTML before
            displaying.
        categories:
          type: array
          description: A list of categories associated with this market news.
          example:
            - Europe
            - Asia
            - Vitamins
            - Feed additives
            - Food additives
          items:
            type: string
            enum:
              - Accident
              - Agriculture
              - Americas
              - Amino acids
              - Analysis
              - APIs
              - Asia
              - Commentary
              - Company news
              - Europe
              - Expansion
              - Featured
              - Feed additives
              - Financial reports
              - Food additives
              - Kemiex report
              - Legal and compliance
              - Logistics
              - Strategic transactions
              - Vitamins
        url:
          type: string
          description: >-
            The URL of this market news, in the Kemiex platform or private
            portal.
          example: >-
            https://app.kemiex.com/market-news/share/b43dd825-8a99-4676-aae7-9b91817c2c3c
    PageMarketNewsListingResponse:
      type: object
      properties:
        results:
          type: array
          description: The list of results on this page
          items:
            $ref: '#/components/schemas/MarketNewsListingResponse'
        pageNumber:
          type: integer
          format: int32
          description: >-
            The current page number of the results. It will be 1 for the first
            page
          example: 3
          minimum: 1
        pageSize:
          type: integer
          format: int32
          description: The number of results on this page
          example: 40
          minimum: 0
        totalResults:
          type: integer
          format: int64
          description: >-
            The total number of results available on server, taking into account
            the applied filters
          example: 193
          minimum: 0
        totalPages:
          type: integer
          format: int64
          description: >-
            The total number of pages necessary to display all results available
            on server, taking into account the desired number of results per
            page
          example: 5
          minimum: 0
