{
  "openapi": "3.1.0",
  "info": {
    "title": "AllUnits Conversion API",
    "version": "1.0.0",
    "summary": "Unit conversion with the exact factors published on allunits.org.",
    "description": "30 conversion pairs across length, weight, temperature, pressure, data size, volume, speed, time and area. Every response carries the stored factor, the offset, the display precision and the documentation page, so a caller can reproduce the number instead of trusting it.\n\nFree without a key: 100 requests per IP per day. Keys raise the daily cap.",
    "contact": {
      "url": "https://allunits.org/about/"
    },
    "license": {
      "name": "CC BY 4.0 (data) — attribution required unless commercially licensed",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://api.allunits.org",
      "description": "Production"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "Convert"
    },
    {
      "name": "Dataset"
    },
    {
      "name": "Account"
    }
  ],
  "paths": {
    "/v1/health": {
      "get": {
        "tags": [
          "Dataset"
        ],
        "summary": "Liveness and dataset version",
        "responses": {
          "200": {
            "description": "Service is up",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          }
        }
      }
    },
    "/v1/pairs": {
      "get": {
        "tags": [
          "Dataset"
        ],
        "summary": "List the supported conversion pairs",
        "security": [
          {},
          {
            "ApiKey": []
          },
          {
            "Bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "All pairs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PairList"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/factors": {
      "get": {
        "tags": [
          "Dataset"
        ],
        "summary": "Full dataset including factor, offset, decimals and formula",
        "security": [
          {},
          {
            "ApiKey": []
          },
          {
            "Bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Full dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FactorsResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/convert": {
      "get": {
        "tags": [
          "Convert"
        ],
        "summary": "Convert one value",
        "security": [
          {},
          {
            "ApiKey": []
          },
          {
            "Bearer": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "km"
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "mi"
          },
          {
            "name": "value",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "example": 10
          },
          {
            "name": "decimals",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 12
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Conversion result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Conversion"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Convert"
        ],
        "summary": "Convert one value or a batch of up to 100",
        "security": [
          {},
          {
            "ApiKey": []
          },
          {
            "Bearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/ConvertRequest"
                  },
                  {
                    "$ref": "#/components/schemas/BatchRequest"
                  }
                ]
              },
              "examples": {
                "single": {
                  "value": {
                    "from": "kg",
                    "to": "lb",
                    "value": 2.5
                  }
                },
                "batch": {
                  "value": {
                    "batch": [
                      {
                        "from": "kg",
                        "to": "lb",
                        "value": 2.5
                      },
                      {
                        "from": "psi",
                        "to": "bar",
                        "value": 35
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result, or per-item results for a batch",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Conversion"
                    },
                    {
                      "$ref": "#/components/schemas/BatchResult"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Quota for the calling key or IP",
        "security": [
          {},
          {
            "ApiKey": []
          },
          {
            "Bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current usage",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Usage"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "Bearer": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid input",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unknown or inactive key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Daily quota exhausted",
        "headers": {
          "X-RateLimit-Limit": {
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Remaining": {
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Reset": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the daily quota resets"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Health": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "status": {
            "type": "string",
            "const": "up"
          },
          "version": {
            "type": "string"
          },
          "dataset_updated": {
            "type": "string",
            "format": "date"
          },
          "pairs": {
            "type": "integer"
          }
        }
      },
      "Pair": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "example": "km-to-miles"
          },
          "category": {
            "type": "string",
            "example": "length"
          },
          "from": {
            "type": "string",
            "example": "km"
          },
          "to": {
            "type": "string",
            "example": "mi"
          },
          "from_name": {
            "type": "string"
          },
          "to_name": {
            "type": "string"
          },
          "decimals": {
            "type": "integer"
          },
          "page": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "PairList": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "count": {
            "type": "integer",
            "example": 30
          },
          "pairs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Pair"
            }
          }
        }
      },
      "FactorsResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "meta": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "site": {
                "type": "string",
                "format": "uri"
              },
              "updated": {
                "type": "string",
                "format": "date"
              },
              "license": {
                "type": "string",
                "example": "CC BY 4.0"
              },
              "attribution": {
                "type": "string"
              },
              "precision_note": {
                "type": "string"
              },
              "version": {
                "type": "string"
              }
            }
          },
          "conversions": {
            "type": "array",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Pair"
                },
                {
                  "type": "object",
                  "properties": {
                    "factor": {
                      "type": "number",
                      "example": 0.6213711922
                    },
                    "offset": {
                      "type": "number",
                      "example": 0
                    },
                    "formula": {
                      "type": "string",
                      "example": "mi = km x 0.621371"
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "ConvertRequest": {
        "type": "object",
        "required": [
          "from",
          "to",
          "value"
        ],
        "properties": {
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          },
          "value": {
            "type": "number"
          },
          "decimals": {
            "type": "integer",
            "minimum": 0,
            "maximum": 12
          }
        }
      },
      "BatchRequest": {
        "type": "object",
        "required": [
          "batch"
        ],
        "properties": {
          "batch": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ConvertRequest"
            }
          }
        }
      },
      "Conversion": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "input": {
            "type": "object",
            "properties": {
              "value": {
                "type": "number"
              },
              "from": {
                "type": "string"
              }
            }
          },
          "output": {
            "type": "object",
            "properties": {
              "value": {
                "type": "number"
              },
              "unit": {
                "type": "string"
              }
            }
          },
          "pair": {
            "type": "string"
          },
          "direction": {
            "type": "string",
            "example": "km → mi"
          },
          "factor": {
            "type": "number"
          },
          "offset": {
            "type": "number"
          },
          "decimals": {
            "type": "integer"
          },
          "unrounded": {
            "type": "number"
          },
          "formula": {
            "type": "string"
          },
          "definition_page": {
            "type": "string",
            "format": "uri"
          },
          "category": {
            "type": "string"
          },
          "attribution": {
            "type": "string"
          },
          "quota": {
            "type": "object",
            "properties": {
              "plan": {
                "type": "string"
              },
              "remaining_today": {
                "type": "integer"
              }
            }
          }
        }
      },
      "BatchResult": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "count": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "ok": {
                  "type": "boolean"
                },
                "output": {
                  "type": "object"
                },
                "error": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "plan": {
            "type": "string",
            "example": "anonymous"
          },
          "limit_per_day": {
            "type": "integer"
          },
          "used_today": {
            "type": "integer"
          },
          "remaining_today": {
            "type": "integer"
          },
          "resets_in_seconds": {
            "type": "integer"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "missing_units",
                  "missing_value",
                  "invalid_value",
                  "value_too_large",
                  "unknown_pair",
                  "invalid_json",
                  "empty_batch",
                  "batch_too_large",
                  "rate_limited",
                  "invalid_key",
                  "license_inactive",
                  "not_found",
                  "method_not_allowed"
                ]
              },
              "message": {
                "type": "string"
              },
              "available_pairs_from_source": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}