@apifreaks/openapi-specs 0.1.0 → 0.1.1

package/dist/specs/commodity/commodity-time-series.yaml

@@ -0,0 +1,238 @@
+openapi: 3.1.1
+info:
+  title: Commodities Time Series API
+  version: 1.0.0
+  description: Retrieve daily OHLC (open, high, low, close) price data for any supported commodity over a date range of up to 365 days. Accepts one or more comma-separated commodity symbols with a start and end date in YYYY-MM-DD format. Returns a date-indexed object where each date key maps to per-symbol OHLC data. Non-trading days are automatically excluded. Returns a 400 error for invalid dates or a range exceeding 365 days, and a 404 error for unsupported symbols or a date range with no available data.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Commodity Time Series API Server
+paths:
+  /commodity/time-series:
+    get:
+      tags:
+        - Commodity APIs
+      summary: Get commodity price time series
+      description: Returns day-by-day OHLC data for the requested commodity symbols within a date range.
+      operationId: getCommodityTimeSeries
+      parameters:
+        - name: format
+          in: query
+          required: false
+          description: Response format. Currently only `json` is supported.
+          schema:
+            type: string
+            default: json
+            enum:
+              - json
+        - name: symbols
+          in: query
+          required: true
+          description: Comma-separated list of commodity symbols.
+          schema:
+            type: string
+        - name: startDate
+          in: query
+          required: true
+          description: Start date in `YYYY-MM-DD` format.
+          schema:
+            type: string
+        - name: endDate
+          in: query
+          required: true
+          description: End date in `YYYY-MM-DD` format. Maximum range is 365 days.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CommodityTimeSeriesResponse'
+              examples:
+                success:
+                  summary: Successful response
+                  value:
+                    success: true
+                    startDate: '2025-01-06'
+                    endDate: '2025-01-08'
+                    rates:
+                      '2025-01-06':
+                        XAU:
+                          open: 2649.01
+                          high: 2651.33
+                          low: 2645.36
+                          close: 2646.91
+                      '2025-01-07':
+                        XAU:
+                          open: 2662.45
+                          high: 2663.06
+                          low: 2655.66
+                          close: 2658.9
+                      '2025-01-08':
+                        XAU:
+                          open: 2669.69
+                          high: 2674.68
+                          low: 2668.58
+                          close: 2671.8
+        '400':
+          description: Bad Request — Missing parameters, invalid dates, or date range exceeded
+          content:
+            application/json:
+              examples:
+                missingSymbols:
+                  summary: Missing required symbols parameter
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/commodity/time-series
+                    status: 400
+                    timestamp: '2026-07-27T11:38:40.063Z'
+                invalidDate:
+                  summary: Date does not exist on the calendar
+                  value:
+                    timestamp: '2026-07-27T11:38:41.234Z'
+                    path: /rates/time-series
+                    code: 400
+                    error: VALIDATION_ERROR
+                    message: 'Invalid Date: The provided start date or end date does not exist.'
+                startAfterEnd:
+                  summary: startDate is after endDate
+                  value:
+                    timestamp: '2026-07-27T11:38:41.234Z'
+                    path: /rates/time-series
+                    code: 400
+                    error: VALIDATION_ERROR
+                    message: start date cannot be after end date
+                dateRangeExceeded:
+                  summary: Date range exceeds 365 days
+                  value:
+                    timestamp: '2026-07-27T11:38:40.699Z'
+                    path: /rates/time-series
+                    code: 400
+                    error: VALIDATION_ERROR
+                    message: Date range exceeds the allowed limit.
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: Not found - Symbol or data not available
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                symbolNotFound:
+                  summary: Symbol Not Found
+                  value:
+                    timestamp: '2026-07-27T11:38:41.234Z'
+                    path: /rates/time-series
+                    code: 404
+                    error: SYMBOL_NOT_FOUND
+                    message: The symbol is not supported, please visit the documentation for a list of supported symbols
+                dataNotFound:
+                  summary: No data available for the given date range
+                  value:
+                    timestamp: '2026-07-27T11:38:41.234Z'
+                    path: /rates/time-series
+                    code: 404
+                    error: DATA_NOT_FOUND
+                    message: No data found for the specified date range
+components:
+  securitySchemes:
+    ApiKeyAuthHeader:
+      type: apiKey
+      in: header
+      name: X-apiKey
+      description: Pass your API key via the X-apiKey request header.
+    ApiKeyAuthQuery:
+      type: apiKey
+      in: query
+      name: apiKey
+      description: Pass your API key via the apiKey query parameter.
+  schemas:
+    CommodityTimeSeriesResponse:
+      type: object
+      required:
+        - success
+        - startDate
+        - endDate
+        - rates
+      properties:
+        success:
+          type: boolean
+          description: '`true` for successful requests.'
+        startDate:
+          type: string
+          description: Start date of the time series (YYYY-MM-DD).
+        endDate:
+          type: string
+          description: End date of the time series (YYYY-MM-DD).
+        rates:
+          $ref: '#/components/schemas/CommodityTimeSeriesRates'
+      description: Commodity time series response containing date-indexed OHLC data per symbol.
+    CommodityTimeSeriesRates:
+      type: object
+      description: Map of trading dates to per-symbol OHLC data. Each key is a trading date (YYYY-MM-DD); non-trading days are excluded.
+      additionalProperties:
+        title: CommodityTimeSeriesSymbolData
+        type: object
+        description: Map of commodity symbols to their OHLC data for a single trading date. Each key is a commodity symbol (e.g. XAU).
+        additionalProperties:
+          $ref: '#/components/schemas/CommodityOhlc'
+    CommodityOhlc:
+      type: object
+      description: OHLC price data for a single commodity on a single trading day.
+      required:
+        - open
+        - high
+        - low
+        - close
+      properties:
+        open:
+          type: number
+          format: float
+          description: Opening price on the given date.
+        high:
+          type: number
+          format: float
+          description: Highest price on the given date.
+        low:
+          type: number
+          format: float
+          description: Lowest price on the given date.
+        close:
+          type: number
+          format: float
+          description: Closing price on the given date.
+    ErrorResponse:
+      type: object
+      description: Standard error envelope returned by the API on failed requests. Gateway-level validation errors populate status; commodity-service errors (date/symbol/data validation) populate code instead — check whichever is present.
+      required:
+        - message
+      properties:
+        error:
+          type: string
+          description: Short error category or exception type (e.g., Invalid Param Exception, VALIDATION_ERROR, SYMBOL_NOT_FOUND, DATA_NOT_FOUND).
+        message:
+          type: string
+          description: Human-readable error message describing the failure.
+        path:
+          type: string
+          description: API endpoint path (gateway errors) or internal service path (commodity-service errors) that produced the error.
+        status:
+          type: integer
+          description: HTTP status code. Present on gateway-level errors.
+        code:
+          type: integer
+          description: HTTP status code. Present on commodity-service errors instead of status.
+        timestamp:
+          type: string
+          format: date-time
+          description: Timestamp when the error occurred (ISO 8601).
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []

package/dist/specs/commodity/historical-commodity-prices.yaml

@@ -0,0 +1,208 @@
+openapi: 3.1.1
+info:
+  title: Historical Commodity Prices, Delivered Simply.
+  version: 1.0.0
+  description: Retrieve OHLC (open, high, low, close) price data for any supported commodity on a specific date. Data is available from January 1990 onwards for 130+ commodities. Accepts one or more comma-separated commodity symbols and a date in YYYY-MM-DD format. The response contains the opening, high, low, and closing price for each symbol on the given date. Returns a 400 error for invalid dates and a 404 error for unsupported symbols or missing rates.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Historical Commodity Prices API Server
+paths:
+  /commodity/rates/historical:
+    get:
+      tags:
+        - Commodity APIs
+      summary: Get historical commodity prices
+      description: Returns OHLC price data for the requested commodity symbols on a specific date.
+      operationId: getHistoricalCommodityPrices
+      parameters:
+        - name: format
+          in: query
+          required: false
+          description: Response format. Currently only `json` is supported.
+          schema:
+            type: string
+            default: json
+            enum:
+              - json
+        - name: symbols
+          in: query
+          required: true
+          description: Comma-separated list of commodity symbols.
+          schema:
+            type: string
+        - name: date
+          in: query
+          required: true
+          description: Date in `YYYY-MM-DD` format. Data available from 1990 onwards.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HistoricalCommodityPricesResponse'
+              examples:
+                success:
+                  summary: Successful response
+                  value:
+                    success: true
+                    date: '2025-01-10'
+                    rates:
+                      WTIOIL-SPOT:
+                        date: '2025-01-10'
+                        open: 73.77
+                        high: 77.16
+                        low: 73.55
+                        close: 75.97
+                      XAU:
+                        date: '2025-01-10'
+                        open: 2669.93
+                        high: 2697.85
+                        low: 2663.61
+                        close: 2689.44
+        '400':
+          description: Bad request - Invalid date format
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                invalidDateFormat:
+                  summary: Invalid date format
+                  value:
+                    timestamp: 1781792620618
+                    status: 400
+                    error: VALIDATION_ERROR
+                    message: Invalid Date Format (YYYY-MM-DD).
+                    path: /v1.0/commodity/rates/historical
+                dateNotExist:
+                  summary: Date does not exist
+                  value:
+                    timestamp: 1781792620618
+                    status: 400
+                    error: VALIDATION_ERROR
+                    message: 'Invalid Date: The provided date does not exist.'
+                    path: /v1.0/commodity/rates/historical
+        '404':
+          description: Not found - Symbol or rate not available
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                symbolNotFound:
+                  summary: Symbol Not Found
+                  value:
+                    timestamp: 1781792620618
+                    status: 404
+                    error: SYMBOL_NOT_FOUND
+                    message: The symbol is not supported, please visit the documentation for a list of supported symbols
+                    path: /v1.0/commodity/rates/historical
+                rateNotFound:
+                  summary: Rate Not Found
+                  value:
+                    timestamp: 1781792620618
+                    status: 404
+                    error: RATE_NOT_FOUND
+                    message: no rates found for the specified date
+                    path: /v1.0/commodity/rates/historical
+components:
+  securitySchemes:
+    ApiKeyAuthHeader:
+      type: apiKey
+      in: header
+      name: X-apiKey
+      description: Pass your API key via the X-apiKey request header.
+    ApiKeyAuthQuery:
+      type: apiKey
+      in: query
+      name: apiKey
+      description: Pass your API key via the apiKey query parameter.
+  schemas:
+    HistoricalCommodityPricesResponse:
+      type: object
+      required:
+        - success
+        - date
+        - rates
+      properties:
+        success:
+          type: boolean
+          description: '`true` for successful requests.'
+        date:
+          type: string
+          description: Date for which prices were fetched (YYYY-MM-DD).
+        rates:
+          $ref: '#/components/schemas/HistoricalCommodityRates'
+      description: Historical commodity prices response containing success status, date, and OHLC rate data.
+    HistoricalCommodityRates:
+      type: object
+      description: Object of commodity symbols to their OHLC price data. Each key is a commodity symbol and the value contains date, open, high, low, and close prices.
+      properties:
+        symbol:
+          $ref: '#/components/schemas/HistoricalCommodityRate'
+      required:
+        - symbol
+    HistoricalCommodityRate:
+      type: object
+      description: OHLC price data for a single commodity on a specific date.
+      required:
+        - date
+        - open
+        - high
+        - low
+        - close
+      properties:
+        date:
+          type: string
+          description: Date for which prices were fetched (YYYY-MM-DD).
+        open:
+          type: number
+          format: float
+          description: Opening price on the given date.
+        high:
+          type: number
+          format: float
+          description: Highest price recorded on the given date.
+        low:
+          type: number
+          format: float
+          description: Lowest price recorded on the given date.
+        close:
+          type: number
+          format: float
+          description: Closing price on the given date.
+    ErrorResponse:
+      type: object
+      required:
+        - timestamp
+        - status
+        - error
+        - message
+        - path
+      properties:
+        timestamp:
+          type: integer
+          description: Unix timestamp in milliseconds when the error occurred.
+        status:
+          type: integer
+          description: HTTP status code returned with the error.
+        error:
+          type: string
+          description: Specific error type (e.g., SYMBOL_NOT_FOUND, VALIDATION_ERROR).
+        message:
+          type: string
+          description: Human-readable error message describing the failure.
+        path:
+          type: string
+          description: API endpoint path that produced the error.
+      description: Standard error envelope returned by the API on failed requests.
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []

package/dist/specs/currency/currency-converter.yaml

@@ -0,0 +1,193 @@
+openapi: 3.1.1
+info:
+  title: Currency Converter API - Convert 970+ Fiat & Crypto Currencies at Live or Historical Rates
+  version: 1.0.0
+  description: Convert an amount from one currency to another using the latest exchange rates. Supports fiat, crypto, and metals. Specify source currency, target currency, and amount to receive the current rate and converted amount with timestamp. All parameters are case-insensitive for both fiat/currency codes and crypto/symbols.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Currency Converter API Server
+paths:
+  /currency/converter/latest/prices:
+    get:
+      tags:
+        - Currency APIs
+      summary: Convert currency with latest rates
+      description: Converts an amount from one currency to another using the latest exchange rates.
+      operationId: convertLatest
+      parameters:
+        - name: format
+          in: query
+          required: false
+          description: 'Response format: `json` (default) or `xml`.'
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+        - name: from
+          in: query
+          required: true
+          description: Source currency code.
+          schema:
+            type: string
+        - name: to
+          in: query
+          required: true
+          description: Target currency code.
+          schema:
+            type: string
+        - name: amount
+          in: query
+          required: false
+          description: Amount to convert, as a decimal. Defaults to `1`. Must be numeric — non-numeric values return a 400 (negative values are accepted despite the error message's wording).
+          schema:
+            type: string
+            default: '1'
+        - name: updates
+          in: query
+          required: false
+          description: 'Update frequency: `1m` (default), `10m`, `1h`, or `1d`.'
+          schema:
+            type: string
+            enum:
+              - 1m
+              - 10m
+              - 1h
+              - 1d
+            default: 1m
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LatestCurrencyConverterResponse'
+              examples:
+                success:
+                  summary: Successful response
+                  value:
+                    date: '2026-07-27 12:05:00+00'
+                    from: USD
+                    to: EUR
+                    rate: '0.87800'
+                    givenAmount: '100.0'
+                    convertedAmount: '87.800'
+        '400':
+          description: Bad request - Invalid amount or updates parameter
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                missingParams:
+                  summary: Missing required from/to parameter
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/currency/converter/latest/prices
+                    status: 400
+                    timestamp: '2026-07-27T12:05:29.609Z'
+                invalidAmount:
+                  summary: amount is not numeric
+                  value:
+                    timestamp: 1785153941995
+                    status: 400
+                    error: Method Argument Type Mismatch
+                    message: Invalid Amount. Please provide amount in decimal format and greater than 0!
+                    path: /v2.0/convert/latest
+                invalidUpdates:
+                  summary: updates is not one of 1m/10m/1h/1d
+                  value:
+                    timestamp: 1785153942533
+                    status: 400
+                    error: Invalid Param Exception
+                    message: Please provide valid updates parameter (1d,1h,10m,1m)
+                    path: /v2.0/convert/latest
+        '404':
+          description: Not found - Currency not available
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                invalidBase:
+                  summary: from currency not supported
+                  value:
+                    timestamp: 1785153930704
+                    status: 404
+                    error: Not Found Exception
+                    message: Rates of provided currency ZZZ are not available in our database!
+                    path: /v2.0/convert/latest
+components:
+  securitySchemes:
+    ApiKeyAuthHeader:
+      type: apiKey
+      in: header
+      name: X-apiKey
+      description: Pass your API key via the X-apiKey request header.
+    ApiKeyAuthQuery:
+      type: apiKey
+      in: query
+      name: apiKey
+      description: Pass your API key via the apiKey query parameter.
+  schemas:
+    LatestCurrencyConverterResponse:
+      type: object
+      required:
+        - date
+        - from
+        - to
+        - rate
+        - givenAmount
+        - convertedAmount
+      properties:
+        date:
+          type: string
+          description: Date and time with timezone (UTC) when the rate was recorded.
+        from:
+          type: string
+          description: Source currency code.
+        to:
+          type: string
+          description: Target currency code.
+        rate:
+          type: string
+          description: Conversion rate from source to target currency.
+        givenAmount:
+          type: string
+          description: The amount provided for conversion.
+        convertedAmount:
+          type: string
+          description: The converted amount in the target currency.
+      description: Currency conversion response containing the exchange rate and converted amount.
+    ErrorResponse:
+      type: object
+      description: Standard error envelope returned by the API on failed requests. Gateway-level validation errors use an ISO 8601 timestamp and the public endpoint path; currency-service errors use a Unix millisecond timestamp and an internal service path instead.
+      required:
+        - message
+      properties:
+        timestamp:
+          type:
+            - string
+            - integer
+          description: Timestamp when the error occurred — ISO 8601 string for gateway errors, Unix milliseconds integer for currency-service errors.
+        status:
+          type: integer
+          description: HTTP status code returned with the error.
+        error:
+          type: string
+          description: Specific error type (e.g., Invalid Param Exception, Method Argument Type Mismatch, Not Found Exception).
+        message:
+          type: string
+          description: Human-readable error message describing the failure.
+        path:
+          type: string
+          description: API endpoint path (gateway errors) or internal service path (currency-service errors) that produced the error.
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []