{ "openapi": "3.1.0", "info": { "title": "Voltformer Autonomous Transformer Procurement & Engineering API", "description": "Official unauthenticated B2B API for AI agents (OpenAI ChatGPT GPT Actions, Anthropic Claude Tool Use & MCP, Perplexity, Gemini) and ERP procurement bots to query 123 industrial transformers across 25 represented brands and 5 SOTA categories, retrieve full P0/Pk/Uk specs, run Ecodesign Tier 2 sizing & ROI calculations, and submit RFQs. No API key required — CORS * enabled. Static fallbacks: GET https://www.voltformer.com/agent-catalog.json (full catalog), https://www.voltformer.com/llms.txt (curated index), https://www.voltformer.com/llms-full.txt (full dump). All endpoints are idempotent except POST /api/v1/rfq which creates a tracked quotation. Use operationId names exactly as defined.", "version": "3.1.0", "contact": { "name": "Voltformer High Voltage Engineering Desk", "email": "teklif@voltformer.com", "url": "https://www.voltformer.com" }, "license": { "name": "Proprietary B2B API — free for AI agents, no key required", "url": "https://www.voltformer.com/legal" } }, "servers": [ { "url": "https://www.voltformer.com/api/v1", "description": "Production — canonical domain (use absolute paths like /api/v1/catalog)" } ], "tags": [ { "name": "Catalog", "description": "Search & filter transformers" }, { "name": "Product", "description": "Single product detail" }, { "name": "Brand", "description": "Manufacturer brands" }, { "name": "Category", "description": "SOTA taxonomy" }, { "name": "Articles", "description": "Technical guides" }, { "name": "Tools", "description": "Engineering calculators (sizing, ROI)" }, { "name": "RFQ", "description": "Autonomous quotation submission — no auth" }, { "name": "System", "description": "Static artefacts & discovery" } ], "paths": { "/api/v1/catalog": { "get": { "operationId": "queryTransformers", "summary": "Search and filter transformer catalog", "description": "Returns full specifications for matching transformers. Filter by mainCategory (5 SOTA), subCategory slug, targetIndustry, brandId (25 brands), power range minKva/maxKva (50–1,000,000 kVA). Use q for free-text search (name, sku, tags). Unfiltered returns all 123 products. Use this first to discover valid skuOrId values before POST /api/v1/rfq. No auth, CORS *.", "tags": [ "Catalog" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search (e.g. '1000 kVA 35kV SCB18', 'VF-TBEA-SCB18-1000-35')" }, { "name": "mainCategory", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "dagitim-trafolari", "guc-ve-iletim-trafolari", "yenilenebilir-enerji-ges-res", "ozel-endustriyel-ve-proses", "kompakt-merkezler-ve-padmounted" ] }, "description": "Main category id (see GET /api/v1/categories)" }, { "name": "subCategory", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sub-category id e.g. kuru-dokme-recine, ges-solar-step-up, ark-ve-ergitme-ocagi" }, { "name": "targetIndustry", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Industry filter e.g. 'Veri Merkezleri', 'Hastaneler', 'Güneş Santralleri (GES)'" }, { "name": "brandId", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "tbea", "baobian", "china-xd", "jshp", "chint", "sunten", "sanbian", "haihong", "ceeg", "jinpan", "mingyang", "taikai", "wolong", "wujiang", "dachi", "qingdao", "zhiguang", "schneider", "abb-hitachi", "siemens", "astor", "best", "eltas", "eaton", "legrand" ] }, "description": "Brand id filter" }, { "name": "minKva", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Minimum rated power kVA" }, { "name": "maxKva", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Maximum rated power kVA (up to 1,000,000)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "Max results (default 20, max 50)" } ], "responses": { "200": { "description": "Matching transformers", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "example": 123 }, "limit": { "type": "integer" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/TransformerProduct" } } } } } } } }, "x-openai-isConsequential": false } }, "/api/v1/product/{slug}": { "get": { "operationId": "getProductBySlug", "summary": "Get single transformer by slug or SKU", "description": "Retrieve full TransformerProduct including specs (P0, Pk, Uk, vectorGroup, cooling, winding, standards), pricing, stock, images. Slug example: schneider-electric-trihal-1000-kva-34-5-kv-kuru-tip-trafo or SKU VF-TBEA-SCB18-1000-35. No auth.", "tags": [ "Product" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product slug or SKU (case-insensitive)" } ], "responses": { "200": { "description": "Product found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformerProduct" } } } }, "404": { "description": "Not found — use GET /api/v1/catalog to discover valid slugs" } }, "x-openai-isConsequential": false } }, "/api/v1/brands": { "get": { "operationId": "listBrands", "summary": "List all 25 represented brands", "description": "Returns brands with headquarters, factory locations, warranty, productCount. No auth.", "tags": [ "Brand" ], "responses": { "200": { "description": "Brand list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Brand" } } } } } }, "x-openai-isConsequential": false } }, "/api/v1/brands/{slug}": { "get": { "operationId": "getBrand", "summary": "Get brand by slug", "description": "Brand detail + sample products. Slug e.g. tbea-energy, schneider-electric, siemens-energy.", "tags": [ "Brand" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Brand found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "404": { "description": "Brand not found" } }, "x-openai-isConsequential": false } }, "/api/v1/categories": { "get": { "operationId": "listCategories", "summary": "List 5 SOTA main categories with taxonomy", "description": "Returns SOTA taxonomy (dagitim-trafolari etc.) with subCategories. No auth. Use to understand category slugs for filtering.", "tags": [ "Category" ], "responses": { "200": { "description": "Category taxonomy", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MainCategory" } } } } } }, "x-openai-isConsequential": false } }, "/api/v1/categories/{mainSlug}": { "get": { "operationId": "getCategory", "summary": "Get main category by slug", "description": "Main category detail with subCategories. Example: dagitim-transformatorleri.", "tags": [ "Category" ], "parameters": [ { "name": "mainSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Category found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MainCategory" } } } }, "404": { "description": "Not found" } }, "x-openai-isConsequential": false } }, "/api/v1/categories/{mainSlug}/{subSlug}": { "get": { "operationId": "getSubCategory", "summary": "Get sub-category by slugs", "description": "Sub-category detail. Example: dagitim-transformatorleri / dokme-recineli-kuru-tip-trafolar.", "tags": [ "Category" ], "parameters": [ { "name": "mainSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sub-category", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not found" } }, "x-openai-isConsequential": false } }, "/api/v1/articles": { "get": { "operationId": "listArticles", "summary": "List technical articles & guides", "description": "Returns TECHNICAL_ARTICLES (Ecodesign Tier 2, kuru tip vs yağlı, GES solar, UHV). No auth.", "tags": [ "Articles" ], "responses": { "200": { "description": "Articles", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } } }, "x-openai-isConsequential": false } }, "/api/v1/articles/{slug}": { "get": { "operationId": "getArticle", "summary": "Get article by slug", "description": "Single technical article detail.", "tags": [ "Articles" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Article", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not found" } }, "x-openai-isConsequential": false } }, "/api/v1/tools/calculate-sizing": { "post": { "operationId": "calculateTransformerSizing", "summary": "Calculate required transformer kVA and cable cross-section", "description": "Engineering sizing simulator — same logic as /sizing-tool UI. Input totalActivePowerKW (required), optional powerFactorCosPhi (default 0.85), simultaneityFactor (0.8), growthMarginPercent (20), largestMotorKW (160). Returns calculatedKVA, recommendedStandardKVA (next IEC step), recommendedPrimaryCable (e.g. 3x(1x95/16) mm² XLPE 36 kV), matchingTransformers SKUs. No auth.", "tags": [ "Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "totalActivePowerKW" ], "properties": { "totalActivePowerKW": { "type": "number", "description": "Total active power kW", "example": 850 }, "powerFactorCosPhi": { "type": "number", "default": 0.85, "example": 0.85 }, "simultaneityFactor": { "type": "number", "default": 0.8, "example": 0.8 }, "growthMarginPercent": { "type": "number", "default": 20, "example": 20 }, "largestMotorKW": { "type": "number", "default": 160, "example": 160 } } } } } }, "responses": { "200": { "description": "Sizing result", "content": { "application/json": { "schema": { "type": "object", "properties": { "calculatedKVA": { "type": "number" }, "recommendedStandardKVA": { "type": "number", "example": 1600 }, "recommendedPrimaryCable": { "type": "string", "example": "3x(1x95/16) mm² XLPE 36 kV" }, "matchingTransformers": { "type": "array", "items": { "type": "string" } } } } } } } }, "x-openai-isConsequential": false } }, "/api/v1/tools/calculate-loss-roi": { "post": { "operationId": "calculateEcodesignLossRoi", "summary": "Calculate annual losses, CO2 and ROI payback (Ecodesign Tier 2)", "description": "Compares low-loss transformer vs legacy. Input ratedPowerKVA, p0Watts (no-load), pkWatts (load), optional loadFactorPercent (65), electricityPriceUsdPerKwh (0.14), operatingHoursPerYear (8760). No auth.", "tags": [ "Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ratedPowerKVA", "p0Watts", "pkWatts" ], "properties": { "ratedPowerKVA": { "type": "number", "example": 1000 }, "p0Watts": { "type": "number", "example": 680 }, "pkWatts": { "type": "number", "example": 7300 }, "loadFactorPercent": { "type": "number", "default": 65, "example": 65 }, "electricityPriceUsdPerKwh": { "type": "number", "default": 0.14, "example": 0.14 }, "operatingHoursPerYear": { "type": "number", "default": 8760, "example": 8760 } } } } } }, "responses": { "200": { "description": "ROI analysis", "content": { "application/json": { "schema": { "type": "object", "properties": { "annualLossKWh": { "type": "number" }, "annualLossCostUSD": { "type": "number" }, "annualSavingsVsLegacyUSD": { "type": "number" }, "co2SavedTonsPerYear": { "type": "number" }, "paybackYears": { "type": "number" } } } } } } }, "x-openai-isConsequential": false } }, "/api/v1/rfq": { "post": { "operationId": "submitRfqQuoteRequest", "summary": "Submit autonomous RFQ — instant reference code, no API key", "description": "Creates a formal RFQ in Voltformer procurement queue. Requires companyName, email, items[{skuOrId, quantity}]. Optional agentName, contactName, phone, city, projectType, requestedDeliveryTerms (Ex-Works/DAP/Montaj Dahil), targetBudgetUSD, notes per item. Returns rfqReferenceCode, status RECEIVED, estimatedOfferTimeHours 2, assignedEngineer, directFollowupLink. Unmatched SKUs return 400 with valid SKUs hint — retry with GET /api/v1/catalog. Idempotent, CORS *, no auth.", "tags": [ "RFQ" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRfqPayload" } } } }, "responses": { "200": { "description": "RFQ registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRfqResponse" } } } }, "400": { "description": "Validation error — missing companyName/email/items or no SKU matched. Body includes error string with valid SKUs." } }, "x-openai-isConsequential": true } }, "/agent-catalog.json": { "get": { "operationId": "getAgentCatalogStatic", "summary": "GET full static catalog JSON (fallback)", "description": "Static file fallback for agents that cannot call /api/v1/catalog. Same data as GET /api/v1/catalog but as single pre-generated JSON at https://www.voltformer.com/agent-catalog.json. No auth, CORS *.", "tags": [ "System" ], "responses": { "200": { "description": "Static catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCatalogResponse" } } } } }, "x-openai-isConsequential": false } } }, "components": { "schemas": { "TransformerProduct": { "type": "object", "description": "Full transformer product with specs", "properties": { "id": { "type": "string" }, "sku": { "type": "string", "example": "VF-TBEA-SCB18-1000-35" }, "name": { "type": "string" }, "slug": { "type": "string" }, "brandId": { "type": "string" }, "brandName": { "type": "string" }, "mainCategoryId": { "type": "string" }, "mainCategoryName": { "type": "string" }, "subCategoryId": { "type": "string" }, "specs": { "type": "object", "properties": { "ratedPowerKVA": { "type": "number" }, "primaryVoltageKV": { "type": "number" }, "secondaryVoltageKV": { "type": "number" }, "shortCircuitImpedanceUkPercent": { "type": "number" }, "noLoadLossesP0Watts": { "type": "number" }, "loadLossesPkWatts": { "type": "number" }, "lossClass": { "type": "string" }, "windingMaterial": { "type": "string" }, "coolingType": { "type": "string" }, "vectorGroup": { "type": "string" } } }, "approxPriceRangeUSD": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } } }, "stockStatus": { "type": "string" }, "image": { "type": "string", "format": "uri" } } }, "Brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "headquarters": { "type": "string" }, "warrantyYears": { "type": "integer" }, "productCount": { "type": "integer" } } }, "MainCategory": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "subCategories": { "type": "array", "items": { "type": "object" } } } }, "AgentRfqPayload": { "type": "object", "required": [ "companyName", "email", "items" ], "properties": { "agentName": { "type": "string", "example": "ProcureBot-v2", "description": "Calling agent identifier" }, "companyName": { "type": "string", "example": "EnerjiSan A.Ş." }, "contactName": { "type": "string", "example": "Müh. Selin Demir" }, "email": { "type": "string", "format": "email", "example": "selin.demir@enerjisan.com" }, "phone": { "type": "string", "example": "+90 533 111 22 33" }, "city": { "type": "string", "example": "Ankara" }, "projectType": { "type": "string", "example": "Sanayi Tesisi / Fabrika" }, "requestedDeliveryTerms": { "type": "string", "enum": [ "Fabrika Teslim (Ex-Works)", "Şantiye Teslim (DAP)", "Montaj & Devreye Alma Dahil" ] }, "items": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "skuOrId", "quantity" ], "properties": { "skuOrId": { "type": "string", "example": "VF-TBEA-SCB18-1000-35", "description": "SKU or slug from catalog — call GET /api/v1/catalog to discover" }, "quantity": { "type": "integer", "minimum": 1, "example": 2 }, "requiredPowerKVA": { "type": "number", "example": 1000 }, "primaryVoltageKV": { "type": "number", "example": 35 }, "customWinding": { "type": "string", "enum": [ "Cu-Cu", "Al-Al" ] }, "notes": { "type": "string", "example": "Class H ve IP31 hücre talep ediliyor." } } } }, "targetBudgetUSD": { "type": "number", "example": 45000 } } }, "AgentRfqResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "rfqReferenceCode": { "type": "string", "example": "VF-2026-8942" }, "status": { "type": "string", "example": "RECEIVED" }, "message": { "type": "string" }, "estimatedOfferTimeHours": { "type": "integer", "example": 2 }, "assignedEngineer": { "type": "string", "example": "Y. Elk. Müh. Kaan Yıldırım" }, "directFollowupLink": { "type": "string", "format": "uri", "example": "https://www.voltformer.com/rfq-tracking?ref=VF-2026-8942" }, "submittedItems": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" } } }, "AgentCatalogResponse": { "type": "object", "properties": { "apiVersion": { "type": "string", "example": "2026.1.0" }, "totalProducts": { "type": "integer", "example": 123 }, "taxonomySummary": { "type": "object" } } } }, "securitySchemes": {} }, "security": [] }