{ "openapi": "3.1.0", "info": { "title": "HowToRomania API", "version": "0.5.0", "description": "Romanian official data for AI agents. €5 = 1,000 credits (€0.005/credit) · €20 = 5,000 · €100 = 30,000. 100 free credits per key. Errors and not-found are never billed. Demo key: htr_demo (20 calls/day per IP; company.lookup, court.case, efactura.validate, efactura.parse, legislation.search, legislation.article, legislation.new).", "contact": { "email": "hello@howtoromania.io", "url": "https://howtoromania.io" } }, "servers": [ { "url": "https://api.howtoromania.io" } ], "security": [ { "apiKey": [] }, { "bearer": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" }, "bearer": { "type": "http", "scheme": "bearer" } } }, "externalDocs": { "url": "https://api.howtoromania.io/docs" }, "x-mcp": { "url": "https://api.howtoromania.io/mcp", "transport": "streamable-http" }, "paths": { "/v1/company/{cui}": { "get": { "operationId": "lookup_company", "summary": "Company lookup (1 credit)", "description": "ANAF registry data by CUI/VAT id: name, address, status, VAT, e-Factura, BNR EUR/RON", "tags": [ "Companies" ], "x-credits": 1, "responses": { "200": { "description": "OK", "headers": { "x-credits-used": { "schema": { "type": "integer" } }, "x-credits-remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid input (not billed)" }, "401": { "description": "Missing/invalid key" }, "402": { "description": "Out of credits; credit packs open soon" }, "403": { "description": "Endpoint not in demo key" }, "404": { "description": "Not found (not billed)" }, "429": { "description": "Demo limit reached" }, "502": { "description": "Upstream error (not billed)" } }, "parameters": [ { "name": "cui", "in": "path", "required": true, "schema": { "type": "string" }, "example": "14399840", "description": "Romanian CUI/CIF, optional RO prefix" }, { "name": "fx", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include BNR EUR/RON (default true)" } ] } }, "/v1/company/{cui}/financials": { "get": { "operationId": "get_company_financials", "summary": "Financial statements (5 credits)", "description": "Up to 5 years of filed accounts + ratios (RON)", "tags": [ "Companies" ], "x-credits": 5, "responses": { "200": { "description": "OK", "headers": { "x-credits-used": { "schema": { "type": "integer" } }, "x-credits-remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid input (not billed)" }, "401": { "description": "Missing/invalid key" }, "402": { "description": "Out of credits; credit packs open soon" }, "403": { "description": "Endpoint not in demo key" }, "404": { "description": "Not found (not billed)" }, "429": { "description": "Demo limit reached" }, "502": { "description": "Upstream error (not billed)" } }, "parameters": [ { "name": "cui", "in": "path", "required": true, "schema": { "type": "string" }, "example": "14399840", "description": "Romanian CUI/CIF, optional RO prefix" }, { "name": "years", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1..5, default 3" } ] } }, "/v1/company/{cui}/representatives": { "get": { "operationId": "get_company_representatives", "summary": "Legal representatives (ONRC) (2 credits)", "description": "Trade-register status, CAEN codes, representatives (name, role)", "tags": [ "Companies" ], "x-credits": 2, "responses": { "200": { "description": "OK", "headers": { "x-credits-used": { "schema": { "type": "integer" } }, "x-credits-remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid input (not billed)" }, "401": { "description": "Missing/invalid key" }, "402": { "description": "Out of credits; credit packs open soon" }, "403": { "description": "Endpoint not in demo key" }, "404": { "description": "Not found (not billed)" }, "429": { "description": "Demo limit reached" }, "502": { "description": "Upstream error (not billed)" } }, "parameters": [ { "name": "cui", "in": "path", "required": true, "schema": { "type": "string" }, "example": "14399840", "description": "Romanian CUI/CIF, optional RO prefix" } ] } }, "/v1/company/{cui}/risk-report": { "get": { "operationId": "get_company_risk_report", "summary": "Risk report (KYB) (8 credits)", "description": "Status + financials + court cases + registry, score 0-100 with explained flags", "tags": [ "Companies" ], "x-credits": 8, "responses": { "200": { "description": "OK", "headers": { "x-credits-used": { "schema": { "type": "integer" } }, "x-credits-remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid input (not billed)" }, "401": { "description": "Missing/invalid key" }, "402": { "description": "Out of credits; credit packs open soon" }, "403": { "description": "Endpoint not in demo key" }, "404": { "description": "Not found (not billed)" }, "429": { "description": "Demo limit reached" }, "502": { "description": "Upstream error (not billed)" } }, "parameters": [ { "name": "cui", "in": "path", "required": true, "schema": { "type": "string" }, "example": "14399840", "description": "Romanian CUI/CIF, optional RO prefix" } ] } }, "/v1/company/{cui}/court-cases": { "get": { "operationId": "get_company_court_cases", "summary": "Company court cases (3 credits)", "description": "Cases where the company is a party (portal.just.ro), summary + list", "tags": [ "Courts" ], "x-credits": 3, "responses": { "200": { "description": "OK", "headers": { "x-credits-used": { "schema": { "type": "integer" } }, "x-credits-remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid input (not billed)" }, "401": { "description": "Missing/invalid key" }, "402": { "description": "Out of credits; credit packs open soon" }, "403": { "description": "Endpoint not in demo key" }, "404": { "description": "Not found (not billed)" }, "429": { "description": "Demo limit reached" }, "502": { "description": "Upstream error (not billed)" } }, "parameters": [ { "name": "cui", "in": "path", "required": true, "schema": { "type": "string" }, "example": "14399840", "description": "Romanian CUI/CIF, optional RO prefix" }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "YYYY-MM-DD" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1..200" } ] } }, "/v1/court-cases/{caseNumber}": { "get": { "operationId": "get_court_case", "summary": "Court case by number (1 credit)", "description": "Parties, hearings, outcomes, appeals", "tags": [ "Courts" ], "x-credits": 1, "responses": { "200": { "description": "OK", "headers": { "x-credits-used": { "schema": { "type": "integer" } }, "x-credits-remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid input (not billed)" }, "401": { "description": "Missing/invalid key" }, "402": { "description": "Out of credits; credit packs open soon" }, "403": { "description": "Endpoint not in demo key" }, "404": { "description": "Not found (not billed)" }, "429": { "description": "Demo limit reached" }, "502": { "description": "Upstream error (not billed)" } }, "parameters": [ { "name": "caseNumber", "in": "path", "required": true, "schema": { "type": "string" }, "example": "9430%2F271%2F2025", "description": "URL-encoded case number" } ] } }, "/v1/efactura/validate": { "post": { "operationId": "validate_efactura", "summary": "Validate invoice XML (1 credit)", "description": "ANAF official validator (CIUS-RO) + local checks, rule codes", "tags": [ "e-Factura" ], "x-credits": 1, "responses": { "200": { "description": "OK", "headers": { "x-credits-used": { "schema": { "type": "integer" } }, "x-credits-remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid input (not billed)" }, "401": { "description": "Missing/invalid key" }, "402": { "description": "Out of credits; credit packs open soon" }, "403": { "description": "Endpoint not in demo key" }, "404": { "description": "Not found (not billed)" }, "429": { "description": "Demo limit reached" }, "502": { "description": "Upstream error (not billed)" } }, "requestBody": { "required": true, "content": { "application/xml": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "properties": { "xml": { "type": "string" } }, "required": [ "xml" ] } } } } } }, "/v1/efactura/generate": { "post": { "operationId": "generate_efactura", "summary": "Generate invoice XML (2 credits)", "description": "CIUS-RO UBL from simple JSON; parties auto-filled from CUI; ANAF-validated", "tags": [ "e-Factura" ], "x-credits": 2, "responses": { "200": { "description": "OK", "headers": { "x-credits-used": { "schema": { "type": "integer" } }, "x-credits-remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid input (not billed)" }, "401": { "description": "Missing/invalid key" }, "402": { "description": "Out of credits; credit packs open soon" }, "403": { "description": "Endpoint not in demo key" }, "404": { "description": "Not found (not billed)" }, "429": { "description": "Demo limit reached" }, "502": { "description": "Upstream error (not billed)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "number", "seller", "buyer", "lines" ], "properties": { "number": { "type": "string" }, "issueDate": { "type": "string" }, "dueDate": { "type": "string" }, "currency": { "type": "string" }, "vatToRonRate": { "type": "number" }, "seller": { "type": "object" }, "buyer": { "type": "object" }, "lines": { "type": "array", "items": { "type": "object", "required": [ "name", "quantity", "unitPrice" ], "properties": { "name": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "unitCode": { "type": "string" }, "vatRate": { "type": "number" }, "vatCategory": { "type": "string" } } } } } } } } } } }, "/v1/efactura/parse": { "post": { "operationId": "parse_efactura", "summary": "Parse invoice XML (1 credit)", "description": "UBL Invoice/CreditNote -> English JSON", "tags": [ "e-Factura" ], "x-credits": 1, "responses": { "200": { "description": "OK", "headers": { "x-credits-used": { "schema": { "type": "integer" } }, "x-credits-remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid input (not billed)" }, "401": { "description": "Missing/invalid key" }, "402": { "description": "Out of credits; credit packs open soon" }, "403": { "description": "Endpoint not in demo key" }, "404": { "description": "Not found (not billed)" }, "429": { "description": "Demo limit reached" }, "502": { "description": "Upstream error (not billed)" } }, "requestBody": { "required": true, "content": { "application/xml": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "properties": { "xml": { "type": "string" } }, "required": [ "xml" ] } } } } } }, "/v1/efactura/pdf": { "post": { "operationId": "efactura_to_pdf", "summary": "Invoice PDF (1 credit)", "description": "ANAF official PDF rendering", "tags": [ "e-Factura" ], "x-credits": 1, "responses": { "200": { "description": "OK", "headers": { "x-credits-used": { "schema": { "type": "integer" } }, "x-credits-remaining": { "schema": { "type": "integer" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input (not billed)" }, "401": { "description": "Missing/invalid key" }, "402": { "description": "Out of credits; credit packs open soon" }, "403": { "description": "Endpoint not in demo key" }, "404": { "description": "Not found (not billed)" }, "429": { "description": "Demo limit reached" }, "502": { "description": "Upstream error (not billed)" } }, "requestBody": { "required": true, "content": { "application/xml": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "properties": { "xml": { "type": "string" } }, "required": [ "xml" ] } } } } } }, "/v1/legislation/search": { "get": { "operationId": "search_legislation", "summary": "Search acts (1 credit)", "description": "By citation ('Legea 31/1990') or title words", "tags": [ "Legislation" ], "x-credits": 1, "responses": { "200": { "description": "OK", "headers": { "x-credits-used": { "schema": { "type": "integer" } }, "x-credits-remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid input (not billed)" }, "401": { "description": "Missing/invalid key" }, "402": { "description": "Out of credits; credit packs open soon" }, "403": { "description": "Endpoint not in demo key" }, "404": { "description": "Not found (not billed)" }, "429": { "description": "Demo limit reached" }, "502": { "description": "Upstream error (not billed)" } }, "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Citation or title words", "example": "Legea 31/1990" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "number", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "year", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1..50" } ] } }, "/v1/legislation/act/{id}": { "get": { "operationId": "get_legal_act", "summary": "Act (in force) (1 credit)", "description": "Current consolidated text, split by article", "tags": [ "Legislation" ], "x-credits": 1, "responses": { "200": { "description": "OK", "headers": { "x-credits-used": { "schema": { "type": "integer" } }, "x-credits-remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid input (not billed)" }, "401": { "description": "Missing/invalid key" }, "402": { "description": "Out of credits; credit packs open soon" }, "403": { "description": "Endpoint not in demo key" }, "404": { "description": "Not found (not billed)" }, "429": { "description": "Demo limit reached" }, "502": { "description": "Upstream error (not billed)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "171282", "description": "legislatie.just.ro act id" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1..200" } ] } }, "/v1/legislation/act/{id}/article/{n}": { "get": { "operationId": "get_legal_article", "summary": "Article (in force) (1 credit)", "description": "One article + dated amendment notes", "tags": [ "Legislation" ], "x-credits": 1, "responses": { "200": { "description": "OK", "headers": { "x-credits-used": { "schema": { "type": "integer" } }, "x-credits-remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid input (not billed)" }, "401": { "description": "Missing/invalid key" }, "402": { "description": "Out of credits; credit packs open soon" }, "403": { "description": "Endpoint not in demo key" }, "404": { "description": "Not found (not billed)" }, "429": { "description": "Demo limit reached" }, "502": { "description": "Upstream error (not billed)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "171282", "description": "legislatie.just.ro act id" }, { "name": "n", "in": "path", "required": true, "schema": { "type": "string" }, "example": "291" } ] } }, "/v1/legislation/act/{id}/history": { "get": { "operationId": "get_legal_act_history", "summary": "Amendment history (2 credits)", "description": "Consolidation dates, dated amendments per article", "tags": [ "Legislation" ], "x-credits": 2, "responses": { "200": { "description": "OK", "headers": { "x-credits-used": { "schema": { "type": "integer" } }, "x-credits-remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid input (not billed)" }, "401": { "description": "Missing/invalid key" }, "402": { "description": "Out of credits; credit packs open soon" }, "403": { "description": "Endpoint not in demo key" }, "404": { "description": "Not found (not billed)" }, "429": { "description": "Demo limit reached" }, "502": { "description": "Upstream error (not billed)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "171282", "description": "legislatie.just.ro act id" }, { "name": "article", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" } ] } }, "/v1/legislation/new": { "get": { "operationId": "get_new_legal_acts", "summary": "New acts (1 credit)", "description": "Acts in force since a date (max 35 days)", "tags": [ "Legislation" ], "x-credits": 1, "responses": { "200": { "description": "OK", "headers": { "x-credits-used": { "schema": { "type": "integer" } }, "x-credits-remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "400": { "description": "Invalid input (not billed)" }, "401": { "description": "Missing/invalid key" }, "402": { "description": "Out of credits; credit packs open soon" }, "403": { "description": "Endpoint not in demo key" }, "404": { "description": "Not found (not billed)" }, "429": { "description": "Demo limit reached" }, "502": { "description": "Upstream error (not billed)" } }, "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "YYYY-MM-DD, max 35 days back" } ] } }, "/v1/keys": { "post": { "operationId": "create_key", "summary": "Create a free key (100 credits)", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "201": { "description": "Key (shown once)" }, "409": { "description": "Email has a key" }, "429": { "description": "Too many keys from this IP" } } } }, "/v1/pricing": { "get": { "operationId": "pricing", "summary": "Prices and credit packs", "security": [], "responses": { "200": { "description": "OK" } } } }, "/v1/me": { "get": { "operationId": "me", "summary": "Balance and 30-day usage", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing/invalid key" } } } } } }