{
  "openapi": "3.1.0",
  "info": {
    "title": "UseCalculator public compute",
    "version": "uctool/1",
    "description": "Free deterministic computation. No account mutations, paid API credentials, or service-level promise. Cross-origin browser requests are denied. All limits and semantic validation remain applicable."
  },
  "servers": [
    {
      "url": "https://usecalculator.app"
    }
  ],
  "security": [],
  "paths": {
    "/api/tools/": {
      "get": {
        "operationId": "listTools",
        "summary": "Discover calculator fields, formulas and example defaults",
        "responses": {
          "200": {
            "description": "Tool directory and request schema.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "429": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/calculate/": {
      "post": {
        "operationId": "calculate",
        "summary": "Run a calculator with explicit inputs",
        "requestBody": {
          "required": true,
          "description": "Maximum 24,000 UTF-8 bytes and 32 scalar inputs. Required fields and domain constraints depend on toolId.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ToolRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result with normalized inputs, engine, formula and assumptions.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "protocol",
                    "engine",
                    "toolId",
                    "inputs",
                    "result",
                    "formula",
                    "assumptions"
                  ],
                  "properties": {
                    "protocol": {
                      "const": "uctool/1"
                    },
                    "engine": {
                      "type": "string"
                    },
                    "toolId": {
                      "type": "string"
                    },
                    "inputs": {
                      "type": "object"
                    },
                    "result": {
                      "type": "object",
                      "required": [
                        "primary",
                        "metrics",
                        "steps"
                      ]
                    },
                    "formula": {
                      "type": "string"
                    },
                    "assumptions": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/fx/": {
      "get": {
        "operationId": "referenceRate",
        "summary": "Get a dated ECB-derived informational reference, not a transaction quote",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{3}$"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{3}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Reference rate, direction, publication date, fetch time, source and precision.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "from",
                    "to",
                    "rate",
                    "asOf",
                    "source",
                    "sourceUrl",
                    "purpose"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "A bounded request, domain, origin, rate, or availability error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ToolRequest": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "protocol": {
            "type": "string",
            "const": "uctool/1"
          },
          "toolId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "inputs": {
            "type": "object",
            "propertyNames": {
              "type": "string",
              "maxLength": 80
            },
            "additionalProperties": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 10000
                },
                {
                  "type": "number"
                }
              ]
            },
            "maxProperties": 32
          }
        },
        "required": [
          "protocol",
          "toolId",
          "inputs"
        ],
        "additionalProperties": false
      }
    }
  },
  "externalDocs": {
    "description": "MCP, custom language and deployment limits",
    "url": "https://usecalculator.app/developers/"
  }
}