{"openapi":"3.1.0","info":{"title":"Ecomwith Tool Agent API","version":"2026-06-14","description":"Agent-callable APIs for Ecomwith tools. Access and quotas depend on the API key owner's current membership plan. Pro keys allow up to 60 requests per UTC minute per API key and tool; Max keys allow up to 200. Requests beyond the minute limit return 429 rate_limited."},"servers":[{"url":"/api/v1"}],"components":{"securitySchemes":{"ApiKeyBearer":{"type":"http","scheme":"bearer"},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"ToolApiError":{"type":"object","properties":{"object":{"const":"tool_api.error"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["object","error"]}}},"security":[{"ApiKeyBearer":[]},{"ApiKeyHeader":[]}],"paths":{"/tools/gtin/generate":{"post":{"operationId":"generateGTIN14","summary":"Generate GTIN-14 numbers","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer","minimum":1}},"required":["quantity"]}}}},"responses":{"200":{"description":"Generated GTIN-14 values"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Membership or scope blocked"},"409":{"description":"Idempotency conflict or in-progress request"},"413":{"description":"Request body exceeds the plan payload limit"},"429":{"description":"Quota, rate limit, or sequential request limit exceeded"}}}},"/tools/qrcode/generate":{"post":{"operationId":"generateQRCode","summary":"Generate QR code SVG or data URL","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":2048},"url":{"type":"string","maxLength":2048},"format":{"enum":["svg","data_url"]},"size":{"type":"integer","minimum":128,"maximum":1024},"margin":{"type":"integer","minimum":0,"maximum":10},"errorCorrectionLevel":{"enum":["L","M","Q","H"]}}}}}},"responses":{"200":{"description":"Generated QR code output"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Membership or scope blocked"},"409":{"description":"Idempotency conflict or in-progress request"},"413":{"description":"Request body exceeds the plan payload limit"},"429":{"description":"Quota, rate limit, or sequential request limit exceeded"}}}},"/tools/utm-builder/build":{"post":{"operationId":"buildUtmLinks","summary":"Build one or more UTM campaign links","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048},"urls":{"type":"array","items":{"type":"string","maxLength":2048}},"urlsText":{"type":"string"},"source":{"type":"string","maxLength":120},"medium":{"type":"string","maxLength":120},"campaign":{"type":"string","maxLength":180},"content":{"type":"string","maxLength":180},"term":{"type":"string","maxLength":180},"id":{"type":"string","maxLength":180,"description":"Optional value emitted as utm_id."},"sourcePlatform":{"type":"string","maxLength":180,"description":"Optional value emitted as utm_source_platform."}},"required":["source","medium","campaign"]}}}},"responses":{"200":{"description":"Built UTM campaign links"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Membership or scope blocked"},"409":{"description":"Idempotency conflict or in-progress request"},"413":{"description":"Request body exceeds the plan payload limit"},"429":{"description":"Quota, rate limit, or sequential request limit exceeded"}}}},"/tools/break-even-roas/calculate":{"post":{"operationId":"calculateBreakEvenRoas","summary":"Calculate break-even ROAS and target-profit ROAS","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"price":{"type":"number","exclusiveMinimum":0},"productCost":{"type":"number","minimum":0},"shippingCost":{"type":"number","minimum":0},"paymentFeeRate":{"type":"number","minimum":0,"maximum":100},"refundRate":{"type":"number","minimum":0,"maximum":100},"targetProfit":{"type":"number"}},"required":["price","productCost"]}}}},"responses":{"200":{"description":"Calculated ROAS guardrails"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Membership or scope blocked"},"409":{"description":"Idempotency conflict or in-progress request"},"413":{"description":"Request body exceeds the plan payload limit"},"429":{"description":"Quota, rate limit, or sequential request limit exceeded"}}}}}}