{"openapi":"3.1.0","info":{"title":"Roman Numeral API","version":"1.0.0","description":"Roman numeral conversion as an API, computed locally and deterministically. The encode endpoint turns an integer from 1 to 3999 into its Roman numeral using standard subtractive notation, so 1994 becomes MCMXCIV and 2024 becomes MMXXIV. The decode endpoint turns a Roman numeral back into an integer with strict validation — it rejects malformed forms such as IIII or VV and also returns the canonical way to write the same value, accepting any letter case. The arithmetic endpoint adds, subtracts or multiplies two values given as either integers or Roman numerals and returns the result as a Roman numeral and as an integer, provided the result stays within the classic 1–3999 range. The standard subtractive pairs are IV, IX, XL, XC, CD and CM. Everything is computed locally and deterministically, so it is instant and private. Ideal for typesetting, publishing, education, clock-face, game and document-processing app developers, numbering and chapter tools, and history teaching. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is Roman numeral conversion; for binary, octal and hexadecimal number-base conversion use a base-conversion API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/roman-api","description":"oanor gateway"}],"tags":[{"name":"Roman"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/arithmetic":{"get":{"operationId":"get_v1_arithmetic","tags":["Roman"],"summary":"Roman arithmetic","description":"","parameters":[{"name":"a","in":"query","required":true,"description":"First operand (integer or Roman)","schema":{"type":"string"},"example":"XIV"},{"name":"b","in":"query","required":true,"description":"Second operand (integer or Roman)","schema":{"type":"string"},"example":"VI"},{"name":"operation","in":"query","required":false,"description":"add, subtract or multiply","schema":{"type":"string"},"example":"add"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Operands may be given as integers or Roman numerals. The result must stay within 1–3999 to be expressible in standard Roman notation.","inputs":{"a":14,"b":6,"operation":"add"},"result_roman":"XX","result_value":20,"operands_roman":{"a":"XIV","b":"VI"}},"meta":{"timestamp":"2026-06-05T11:30:34.630Z","request_id":"df39ed36-664a-43c3-8d4e-e0d4d78f2e34"},"status":"ok","message":"Roman arithmetic","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/decode":{"get":{"operationId":"get_v1_decode","tags":["Roman"],"summary":"Roman to integer","description":"","parameters":[{"name":"roman","in":"query","required":true,"description":"Roman numeral","schema":{"type":"string"},"example":"MCMXCIV"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Decoded with strict validation (rejects forms like IIII or VV). The canonical form is the standard way to write the same value.","value":1994,"inputs":{"roman":"MCMXCIV"},"canonical":"MCMXCIV"},"meta":{"timestamp":"2026-06-05T11:30:34.765Z","request_id":"6f73852a-7d5e-44f7-b907-7f6b87fc42f4"},"status":"ok","message":"Roman to integer","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/encode":{"get":{"operationId":"get_v1_encode","tags":["Roman"],"summary":"Integer to Roman","description":"","parameters":[{"name":"number","in":"query","required":true,"description":"Integer 1–3999","schema":{"type":"string"},"example":"1994"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Standard subtractive Roman notation for 1–3999 (e.g. 1994 → MCMXCIV). Values above 3999 need a vinculum (overline) which is outside the classic range.","roman":"MCMXCIV","inputs":{"number":1994}},"meta":{"timestamp":"2026-06-05T11:30:34.844Z","request_id":"4b2f355a-66bb-42f2-90c3-75c376be0c85"},"status":"ok","message":"Integer to Roman","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Spec","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"notes":"Classic range 1–3999 with standard subtractive notation (IV, IX, XL, XC, CD, CM). Decode rejects non-canonical forms like IIII or VV.","service":"roman-api","endpoints":{"GET /v1/meta":"This document.","GET /v1/decode":"Roman numeral to an integer, with validation and canonical form.","GET /v1/encode":"Integer (1–3999) to a Roman numeral.","GET /v1/arithmetic":"Add, subtract or multiply two Roman numerals or integers, result in Roman."},"description":"Roman numeral converter: encode an integer to a Roman numeral, decode a Roman numeral to an integer with strict validation, and do arithmetic (add, subtract, multiply) on Roman numerals."},"meta":{"timestamp":"2026-06-05T11:30:34.938Z","request_id":"848396cb-fc32-4e1f-b932-4b45dad2966d"},"status":"ok","message":"Meta","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":5000,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":500,"monthly_call_quota":47000,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":1300,"monthly_call_quota":225000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":4100,"monthly_call_quota":1320000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/roman-api"}