@apifreaks/openapi-specs 0.1.0

package/specs/commodity/commodity-prices.json

@@ -0,0 +1,317 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Live Commodity Prices API - Real Time Market Insights",
+    "version": "1.0.0",
+    "description": "Get real-time prices for 130+ commodities in a single request. Returns current market prices for each requested symbol plus unit and quote currency metadata. Supports an optional quote parameter to convert prices into a desired currency, defaulting to each commodity's native market currency. Accepts 1-minute or 10-minute update frequencies for price freshness. An unsupported symbol or quote currency returns a 404.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Live Commodity Prices API Server"
+    }
+  ],
+  "paths": {
+    "/commodity/rates/latest": {
+      "get": {
+        "tags": ["Commodity APIs"],
+        "summary": "Get latest commodity prices",
+        "description": "Returns the current live price for the requested commodity symbols.",
+        "operationId": "getLatestCommodityPrices",
+        "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 (e.g., `XAU`, `WTIOIL-SPOT`).",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "updates",
+            "in": "query",
+            "required": true,
+            "description": "Update frequency. Accepted values: `1m` (default), `10m`.",
+            "schema": {
+              "type": "string",
+              "enum": ["1m", "10m"],
+              "default": "1m"
+            }
+          },
+          {
+            "name": "quote",
+            "in": "query",
+            "required": false,
+            "description": "Target currency for the exchange rate. Defaults to the market currency of each commodity.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/LiveCommodityPricesResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "Successful response",
+                    "value": {
+                      "success": true,
+                      "timestamp": 1785152172,
+                      "rates": {
+                        "XAU": 4099.1,
+                        "WTIOIL-SPOT": 81.88
+                      },
+                      "metadata": {
+                        "XAU": {
+                          "unit": "T.oz",
+                          "quote": "USD"
+                        },
+                        "WTIOIL-SPOT": {
+                          "unit": "Bbl",
+                          "quote": "USD"
+                        }
+                      }
+                    }
+                  },
+                  "withQuoteConversion": {
+                    "summary": "Price converted to a target quote currency",
+                    "value": {
+                      "success": true,
+                      "timestamp": 1785152172,
+                      "rates": {
+                        "XAU": 3597.734
+                      },
+                      "metadata": {
+                        "XAU": {
+                          "unit": "T.oz",
+                          "quote": "EUR"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request — Missing or invalid query parameters",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "missingSymbols": {
+                    "summary": "Missing required symbols parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/commodity/rates/latest",
+                      "status": 400,
+                      "timestamp": "2026-07-27T11:36:13.312Z"
+                    }
+                  },
+                  "invalidUpdates": {
+                    "summary": "updates is not 1m or 10m",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/commodity/rates/latest",
+                      "status": 400,
+                      "timestamp": "2026-07-27T11:36:35.755Z"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found - Symbol or quote currency not available",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CommodityNotFoundError"
+                },
+                "examples": {
+                  "symbolNotFound": {
+                    "summary": "Symbol Not Found",
+                    "value": {
+                      "timestamp": 1781792620618,
+                      "path": "/rates/latestRates",
+                      "code": 404,
+                      "error": "SYMBOL_NOT_FOUND",
+                      "message": "The symbol is not supported, please visit the documentation for a list of supported symbols"
+                    }
+                  },
+                  "quoteNotFound": {
+                    "summary": "Quote Currency Not Found",
+                    "value": {
+                      "timestamp": 1781792620618,
+                      "path": "/rates/latestRates",
+                      "code": 404,
+                      "error": "QUOTE_NOT_FOUND",
+                      "message": "The quote currency is invalid, please visit the documentation for a list of valid quote currencies"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "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": {
+      "LiveCommodityPricesResponse": {
+        "type": "object",
+        "required": ["success", "timestamp", "rates", "metadata"],
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "`true` for successful requests."
+          },
+          "timestamp": {
+            "type": "integer",
+            "description": "Unix timestamp (seconds) indicating when the response was generated."
+          },
+          "rates": {
+            "$ref": "#/components/schemas/CommodityRates"
+          },
+          "metadata": {
+            "$ref": "#/components/schemas/CommodityMetadata"
+          }
+        },
+        "description": "Live commodity prices response containing success status, timestamp, rates, and metadata."
+      },
+      "CommodityRates": {
+        "type": "object",
+        "description": "Map of requested commodity symbols to their current live price. Each key is a commodity symbol (e.g. XAU); the value is the current price.",
+        "additionalProperties": {
+          "title": "CommodityPrice",
+          "type": "number",
+          "description": "Current live price for this commodity symbol."
+        }
+      },
+      "CommodityMetadata": {
+        "type": "object",
+        "description": "Map of requested commodity symbols to their unit and quote currency metadata. Each key is a commodity symbol (e.g. XAU).",
+        "additionalProperties": {
+          "title": "CommodityMetadataItem",
+          "type": "object",
+          "description": "Unit and currency metadata for a single commodity.",
+          "required": ["unit", "quote"],
+          "properties": {
+            "unit": {
+              "type": "string",
+              "description": "Unit of measurement for the commodity (e.g., Bbl, T.oz)."
+            },
+            "quote": {
+              "type": "string",
+              "description": "Quote currency used for this commodity's price."
+            }
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests.",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        }
+      },
+      "CommodityNotFoundError": {
+        "type": "object",
+        "description": "Error envelope returned by the commodity pricing service specifically for unresolvable symbol/quote errors. Uses `code` instead of `status` and a Unix millisecond `timestamp`, unlike the standard ErrorResponse.",
+        "required": ["code", "error", "message"],
+        "properties": {
+          "timestamp": {
+            "type": "integer",
+            "description": "Unix timestamp in milliseconds when the error occurred."
+          },
+          "path": {
+            "type": "string",
+            "description": "Internal service path that produced the error."
+          },
+          "code": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "error": {
+            "type": "string",
+            "description": "Specific error type (e.g., SYMBOL_NOT_FOUND, QUOTE_NOT_FOUND)."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}

package/specs/commodity/commodity-symbols.json

@@ -0,0 +1,215 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Commodity Symbols API Reference",
+    "version": "1.0.0",
+    "description": "List all supported commodity symbols available in the APIFreaks Commodity API. Returns an array of commodity objects with symbol, name, category, pricing currency, unit of measurement, status, and update interval. Supports metals, energy, agriculture, and livestock categories.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Commodity Symbols API Server"
+    }
+  ],
+  "paths": {
+    "/commodity/symbols": {
+      "get": {
+        "tags": ["Commodity APIs"],
+        "summary": "Get all supported commodity symbols",
+        "description": "Returns the list of supported commodity symbols with metadata.",
+        "operationId": "getCommoditySymbols",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "description": "Response format. Accepted values: `json` (default) or `xml`.",
+            "schema": {
+              "type": "string",
+              "enum": ["json"],
+              "default": "json"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CommoditySymbolsResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "Successful response",
+                    "value": {
+                      "success": true,
+                      "symbols": [
+                        {
+                          "symbol": "XAU",
+                          "name": "Gold",
+                          "category": "Metals",
+                          "status": "active",
+                          "updateInterval": "PER_SECOND",
+                          "currency": {
+                            "code": "USD",
+                            "name": "US Dollar",
+                            "symbol": "$"
+                          },
+                          "unit": {
+                            "symbol": "T.oz",
+                            "name": "Troy Ounce"
+                          }
+                        },
+                        {
+                          "symbol": "NG-FUT",
+                          "name": "Natural Gas Futures",
+                          "category": "Energy",
+                          "status": "active",
+                          "updateInterval": "PER_MINUTE",
+                          "currency": {
+                            "code": "USD",
+                            "name": "US Dollar",
+                            "symbol": "$"
+                          },
+                          "unit": {
+                            "symbol": "MMBtu",
+                            "name": "Million British Thermal Units"
+                          }
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "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": {
+      "CommoditySymbolsResponse": {
+        "type": "object",
+        "required": ["success", "symbols"],
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Indicates whether the API request was successful."
+          },
+          "symbols": {
+            "type": "array",
+            "description": "Array of commodity symbol objects with metadata.",
+            "items": {
+              "$ref": "#/components/schemas/CommoditySymbolItem"
+            }
+          }
+        },
+        "description": "Commodity symbols response containing an array of supported commodity symbol objects."
+      },
+      "CommoditySymbolItem": {
+        "type": "object",
+        "description": "A single commodity symbol with metadata.",
+        "required": [
+          "symbol",
+          "name",
+          "category",
+          "status",
+          "updateInterval",
+          "currency",
+          "unit"
+        ],
+        "properties": {
+          "symbol": {
+            "type": "string",
+            "description": "Unique identifier/ticker symbol for the commodity (e.g., XAU, NG-FUT)."
+          },
+          "name": {
+            "type": "string",
+            "description": "Full name of the commodity (e.g., Gold, Natural Gas Futures)."
+          },
+          "category": {
+            "type": "string",
+            "description": "Category the commodity belongs to (e.g., Metals, Energy)."
+          },
+          "status": {
+            "type": "string",
+            "description": "Current status of the commodity. Value: active."
+          },
+          "updateInterval": {
+            "type": "string",
+            "description": "Rate at which the price is updated. Values: PER_SECOND, PER_MINUTE."
+          },
+          "currency": {
+            "$ref": "#/components/schemas/CommodityCurrency"
+          },
+          "unit": {
+            "$ref": "#/components/schemas/CommodityUnit"
+          }
+        }
+      },
+      "CommodityCurrency": {
+        "type": "object",
+        "description": "Currency information for a commodity.",
+        "required": ["code", "name", "symbol"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "ISO 4217 currency code."
+          },
+          "name": {
+            "type": "string",
+            "description": "Full name of the currency."
+          },
+          "symbol": {
+            "type": "string",
+            "description": "Symbol of the currency (e.g., $)."
+          }
+        }
+      },
+      "CommodityUnit": {
+        "type": "object",
+        "description": "Unit of measurement for a commodity.",
+        "required": ["symbol", "name"],
+        "properties": {
+          "symbol": {
+            "type": "string",
+            "description": "Abbreviated unit symbol (e.g., T.oz, MMBtu)."
+          },
+          "name": {
+            "type": "string",
+            "description": "Full name of the unit of measurement (e.g., Troy Ounce)."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}