{
  "openapi": "3.0.3",
  "info": {
    "title": "Unit Converter API",
    "version": "1.5.1",
    "description": "Convert 14 categories and over 130 units (length, weight, temperature, volume, area, speed, pressure, energy, power, time, data transfer, angle, fuel economy, cooking), plus file size, Roman numerals and recipe scaling. Convert between over 130 units in 14 categories (length, weight, temperature, volume, area, speed, pressure, energy, power, time, data transfer rate, angle, fuel economy and cooking measures) with exact, cited factors and a unit list per category (US, imperial and metric units are tagged; US and metric kitchen measures differ and the unit id says which is used), convert file sizes between B and PB, convert numbers to and from Roman numerals (with bars above 3,999) and scale a recipe's ingredients to a new serving count. Nothing you send is stored. One X-API-Key header authenticates every call, and the same key works across every FreeDailyPro API. Every 4xx response is documented and none of them is billed.",
    "contact": {
      "name": "FreeDailyPro",
      "url": "https://www.freedailypro.com/developers",
      "email": "support@freedailypro.com"
    },
    "termsOfService": "https://www.freedailypro.com/terms",
    "x-logo": {
      "url": "https://www.freedailypro.com/favicon.ico"
    }
  },
  "servers": [
    {
      "url": "https://api.freedailypro.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer hub, plans and MCP setup",
    "url": "https://www.freedailypro.com/developers"
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "tags": [
    {
      "name": "Unit Conversion",
      "description": "Convert 14 categories and over 130 units (length, weight, temperature, volume, area, speed, pressure, energy, power, time, data transfer, angle, fuel economy, cooking), plus file size, Roman numerals and recipe scaling."
    }
  ],
  "paths": {
    "/v1/converters/length": {
      "post": {
        "summary": "Convert a length between metres, kilometres, inches, feet, yards and miles",
        "operationId": "convertersLength",
        "description": "Convert a length between metres, kilometres, inches, feet, yards and miles. Send JSON with value, from, to (required). Returns JSON with the answer as a number in result. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Unit Conversion"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "number"
                  },
                  "from": {
                    "type": "string",
                    "enum": [
                      "m",
                      "cm",
                      "mm",
                      "km",
                      "in",
                      "ft",
                      "yd",
                      "mi"
                    ]
                  },
                  "to": {
                    "type": "string",
                    "enum": [
                      "m",
                      "cm",
                      "mm",
                      "km",
                      "in",
                      "ft",
                      "yd",
                      "mi"
                    ]
                  }
                },
                "required": [
                  "value",
                  "from",
                  "to"
                ],
                "additionalProperties": false
              },
              "example": {
                "value": 5,
                "from": "mi",
                "to": "km"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Unit converter (length) client and server side from freedailypro",
                  "result": 8.04672
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input; the body explains what to fix Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/weight": {
      "post": {
        "summary": "Convert a weight between kilograms, grams, pounds and ounces",
        "operationId": "convertersWeight",
        "description": "Convert a weight between kilograms, grams, pounds and ounces. Send JSON with value, from, to (required). Returns JSON with the answer as a number in result. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Unit Conversion"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "number"
                  },
                  "from": {
                    "type": "string",
                    "enum": [
                      "kg",
                      "g",
                      "mg",
                      "lb",
                      "oz"
                    ]
                  },
                  "to": {
                    "type": "string",
                    "enum": [
                      "kg",
                      "g",
                      "mg",
                      "lb",
                      "oz"
                    ]
                  }
                },
                "required": [
                  "value",
                  "from",
                  "to"
                ],
                "additionalProperties": false
              },
              "example": {
                "value": 150,
                "from": "lb",
                "to": "kg"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Unit converter (weight) client and server side from freedailypro",
                  "result": 68.0388555
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input; the body explains what to fix Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/temperature": {
      "post": {
        "summary": "Convert a temperature between Celsius, Fahrenheit and Kelvin",
        "operationId": "convertersTemperature",
        "description": "Convert a temperature between Celsius, Fahrenheit and Kelvin. Send JSON with value, from, to (required). Returns JSON with the answer as a number in result. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Unit Conversion"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "number"
                  },
                  "from": {
                    "type": "string",
                    "enum": [
                      "C",
                      "F",
                      "K"
                    ]
                  },
                  "to": {
                    "type": "string",
                    "enum": [
                      "C",
                      "F",
                      "K"
                    ]
                  }
                },
                "required": [
                  "value",
                  "from",
                  "to"
                ],
                "additionalProperties": false
              },
              "example": {
                "value": 72,
                "from": "F",
                "to": "C"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Unit converter (temperature) client and server side from freedailypro",
                  "result": 22.22222222222222
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input; the body explains what to fix Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/recipe-scale": {
      "post": {
        "summary": "Scale recipe ingredient amounts from one serving count to another",
        "operationId": "convertersRecipeScale",
        "description": "Scale recipe ingredient amounts from one serving count to another. Send JSON with ingredients, originalServings, targetServings (required). Returns JSON: a list. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Unit Conversion"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ingredients": {
                    "minItems": 1,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "amount": {
                          "type": "number"
                        },
                        "unit": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "name",
                        "amount"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "originalServings": {
                    "type": "number",
                    "minimum": 0
                  },
                  "targetServings": {
                    "type": "number",
                    "minimum": 0
                  }
                },
                "required": [
                  "ingredients",
                  "originalServings",
                  "targetServings"
                ],
                "additionalProperties": false
              },
              "example": {
                "ingredients": [
                  {
                    "name": "flour",
                    "amount": 250,
                    "unit": "g"
                  },
                  {
                    "name": "eggs",
                    "amount": 2
                  },
                  {
                    "name": "milk",
                    "amount": 300,
                    "unit": "ml"
                  }
                ],
                "originalServings": 4,
                "targetServings": 10
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Recipe scaler client and server side from freedailypro",
                  "result": [
                    {
                      "name": "flour",
                      "amount": 625,
                      "unit": "g",
                      "originalAmount": 250
                    },
                    {
                      "name": "eggs",
                      "amount": 5,
                      "originalAmount": 2
                    },
                    {
                      "name": "milk",
                      "amount": 750,
                      "unit": "ml",
                      "originalAmount": 300
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input; the body explains what to fix Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/roman": {
      "post": {
        "summary": "Convert numbers to Roman numerals and back",
        "operationId": "convertersRoman",
        "description": "Send 'direction' (toRoman or fromRoman) and 'value'. toRoman takes a whole number from 1 to 3,999,999. Up to 3,999 the 'result' is the plain numeral it always was (1994 gives MCMXCIV). Above 3,999 the thousands are written with a bar over every letter, as the Unicode combining overline U+0305 after each letter (5000 is V followed by U+0305; 4000 is I and V, each followed by U+0305), and 'vinculum' is true; before this change those numbers were a 400. The response also adds 'breakdown' (the pieces joined with plus signs, such as M + CM + XC + IV) and 'steps', an ordered list of { label, formula, inputs, result } that ends on the numeral. fromRoman reads plain numerals with the strict rule it always had (IIII and other non-standard forms are rejected here; the website page accepts IIII as the clock-face 4 with a note), and now also barred numerals: type the bar as U+0305 or write the barred group in brackets, so (V) is 5,000 and (XII)CCCXLV is 12,345. The barred group is read as a numeral from 1 to 3,999 and multiplied by 1,000; the plain letters after it must be below 1,000 and written without M. Who calls it: school and homework tools, certificate and document generators, tattoo and wedding-invitation date designers, film and event copyright-year footers, and MCP agents. Worked example: {\"direction\":\"toRoman\",\"value\":1994000} returns the barred form of MCMXCIV with vinculum true and breakdown M + CM + XC + IV (each piece barred). Integration scenario: a certificate builder prints the issue year in numerals and uses the barred form for large counts such as a 1,994,000-copy print run. There is no zero and no negative number in Roman numerals. The bar is a typographic convention and some fonts place the combining overline slightly off, so draw it with CSS overline if the look matters. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Unit Conversion"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "direction": {
                    "type": "string",
                    "enum": [
                      "toRoman",
                      "fromRoman"
                    ]
                  },
                  "value": {
                    "anyOf": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "description": "toRoman: a whole number from 1 to 3,999,999 (above 3,999 the thousands get a bar over every letter, written with the Unicode combining overline U+0305). fromRoman: a numeral; barred letters may be typed with U+0305 or as a bracketed group such as (V) for 5,000."
                  }
                },
                "required": [
                  "direction",
                  "value"
                ],
                "additionalProperties": false
              },
              "example": {
                "direction": "toRoman",
                "value": 1994
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Roman numeral converter client and server side from freedailypro",
                  "result": "MCMXCIV"
                }
              }
            }
          },
          "400": {
            "description": "A value that is not a whole number from 1 to 3,999,999 (including 0, negatives and decimals) for toRoman; for fromRoman, letters other than I V X L C D M, a numeral not written in the standard form, barred letters that do not form a numeral from I to MMMCMXCIX, plain letters after a bar that are 1,000 or more, or barred letters after plain ones; the body says which Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/units": {
      "post": {
        "summary": "Convert between units in 14 categories (length, weight, temperature, volume, area, speed, pressure, energy, power, time, data transfer, angle, fuel economy, cooking)",
        "operationId": "convertersUnits",
        "description": "Send 'category', 'value', 'from' and 'to' (unit ids). Returns 'result', the unit names, the 'factor' (one 'from' in 'to', for categories where that is a single number), and for volume, cooking and fuel economy a 'note' when a US or imperial unit is involved. Categories: length, weight (alias mass), temperature (C, F, K, R), volume, area, speed, pressure, energy, power, time, data_transfer, angle, fuel_economy and cooking. Over 130 units; POST /v1/converters/units-list returns every id, symbol, alias and a us, imperial or metric tag. Ids and aliases are case-insensitive (gal_us, GAL, kph, km/h). Exact factors: US customary and metric units use the exact international definitions (1 in = 0.0254 m, 1 lb = 0.45359237 kg, 1 US gallon = 3.785411784 L, 1 imperial gallon = 4.54609 L, 1 atm = 101325 Pa, 1 kcal = 4184 J, 1 Btu(IT) = 1055.05585262 J); each factor is cited in the source (NIST SP 811 and Handbook 44). Results are rounded to 12 significant digits to remove floating-point noise. US vs metric: US gallons, pints, cups and fluid ounces differ from imperial (UK) ones and from metric kitchen measures (a US cup is 236.588 mL, a metric cup 250 mL, a US tablespoon 14.787 mL, a metric one 15 mL, an Australian one 20 mL); the unit id says which one is used. Limits: cooking converts volume only (cups to grams depends on the ingredient and is not offered); time months and years are calendar averages (Gregorian year = 365.2425 days); Mach is not offered because it depends on temperature; temperatures below absolute zero and fuel economy values of 0 or less are refused; the older /length, /weight and /temperature endpoints still work and return a bare number. Pure arithmetic from the request: nothing is stored. Stateless: the request is processed in memory and nothing is stored. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached.",
        "tags": [
          "Unit Conversion"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "category": {
                    "type": "string",
                    "description": "length, weight, temperature, volume, area, speed, pressure, energy, power, time, data_transfer, angle, fuel_economy or cooking. List the units of each with /v1/converters/units-list."
                  },
                  "value": {
                    "type": "number",
                    "description": "The number to convert."
                  },
                  "from": {
                    "type": "string",
                    "description": "Unit id to convert from, for example gal_us, km_h, psi, kwh (see units-list for the ids and aliases)."
                  },
                  "to": {
                    "type": "string",
                    "description": "Unit id to convert to."
                  }
                },
                "required": [
                  "category",
                  "value",
                  "from",
                  "to"
                ],
                "additionalProperties": false
              },
              "example": {
                "category": "volume",
                "value": 2,
                "from": "gal_us",
                "to": "l"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Unit converter: 14 categories and over 130 units with exact factors",
                  "result": {
                    "category": "volume",
                    "value": 2,
                    "from": "gal_us",
                    "fromName": "US gallon",
                    "to": "l",
                    "toName": "Litre",
                    "result": 7.570823568,
                    "factor": 3.785411784,
                    "categoryNote": "US and imperial (UK) gallons, pints and fluid ounces differ: 1 US gallon is 3.785411784 L, 1 imperial gallon is 4.54609 L. Units are tagged us, imperial or metric.",
                    "note": "US customary and imperial (UK) units share names but not sizes (US gallon 3.785411784 L, imperial gallon 4.54609 L); the unit id says which one was used."
                  }
                }
              }
            }
          },
          "400": {
            "description": "An unknown category or unit id (the message lists the valid ones), a missing or non-numeric value, a temperature below absolute zero, or a fuel economy value of 0 or less Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/units-list": {
      "post": {
        "summary": "List the units of each category with ids, symbols, aliases and a US, imperial or metric tag",
        "operationId": "convertersUnitsList",
        "description": "Returns every category with its base unit, notes and units; each unit has an 'id' to send to /v1/converters/units, a name, a symbol, optional aliases and a 'system' tag (us, imperial or metric) where that applies. Send 'category' to list just one. Use it to build a unit picker or to let an agent look up the valid ids before converting. Static reference data: nothing is stored. Stateless: the request is processed in memory and nothing is stored. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached.",
        "tags": [
          "Unit Conversion"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "category": {
                    "description": "Only this category (for example volume). Leave out for every category.",
                    "type": "string"
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "category": "speed"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Unit converter: the units of each category, with ids, symbols, aliases and a US, imperial or metric tag",
                  "result": {
                    "categoryCount": 1,
                    "unitCount": 5,
                    "categories": [
                      {
                        "category": "speed",
                        "name": "Speed",
                        "baseUnit": "m_s",
                        "note": "Mach is not offered: it depends on air temperature.",
                        "units": [
                          {
                            "id": "m_s",
                            "name": "Metre per second",
                            "symbol": "m/s",
                            "system": "metric",
                            "aliases": [
                              "m/s",
                              "mps"
                            ]
                          },
                          {
                            "id": "km_h",
                            "name": "Kilometre per hour",
                            "symbol": "km/h",
                            "system": "metric",
                            "aliases": [
                              "km/h",
                              "kph",
                              "kmh"
                            ]
                          },
                          {
                            "id": "mph",
                            "name": "Mile per hour",
                            "symbol": "mph",
                            "system": "us",
                            "aliases": [
                              "mi/h"
                            ]
                          },
                          "..."
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "The category is not one of the 14 supported categories; the message lists them Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/file-size": {
      "post": {
        "summary": "Convert a file size between bytes, KB, MB, GB, TB and PB",
        "operationId": "convertersFileSize",
        "description": "Convert a file size between bytes, KB, MB, GB, TB and PB. Send JSON with value, from, to (required). Returns JSON with bytes, converted, from, to, formatted (inside result). Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Unit Conversion"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "number"
                  },
                  "from": {
                    "type": "string",
                    "enum": [
                      "B",
                      "KB",
                      "MB",
                      "GB",
                      "TB",
                      "PB"
                    ]
                  },
                  "to": {
                    "type": "string",
                    "enum": [
                      "B",
                      "KB",
                      "MB",
                      "GB",
                      "TB",
                      "PB"
                    ]
                  }
                },
                "required": [
                  "value",
                  "from",
                  "to"
                ],
                "additionalProperties": false
              },
              "example": {
                "value": 1.5,
                "from": "GB",
                "to": "MB"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "File size converter client and server side from freedailypro",
                  "result": {
                    "bytes": 1610612736,
                    "converted": 1536,
                    "from": "GB",
                    "to": "MB",
                    "formatted": "1536.00 MB"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input; the body explains what to fix Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    }
  }
}