{"openapi":"3.0.3","info":{"title":"Penny Engine Agent API","version":"0.7.7","description":"Free deterministic tools via REST. No authentication."},"servers":[{"url":"https://penny-agent-api-production.up.railway.app"}],"paths":{"/api/margin":{"post":{"operationId":"penny_margin","summary":"Unit margin, markup and break-even units. Free, no signup, deterministic.","tags":["Commerce"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"price":{"type":"number"},"variableCost":{"type":"number"},"fixedCost":{"type":"number"}},"required":["price","variableCost"]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}},"/api/cleaning-quote":{"post":{"operationId":"penny_cleaning_quote","summary":"Commercial cleaning quote by labor and target margin. Free, no signup, deterministic.","tags":["Business"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"hours":{"type":"number"},"hourlyWage":{"type":"number"},"laborBurdenPct":{"type":"number"},"suppliesUsd":{"type":"number"},"overheadUsd":{"type":"number"},"targetMarginPct":{"type":"number"}},"required":["hours","hourlyWage"]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}},"/api/marketplace-profit":{"post":{"operationId":"penny_marketplace_profit","summary":"Ecommerce net contribution after goods, fees, ads and shipping. Free, no signup, deterministic.","tags":["Commerce"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"salePrice":{"type":"number"},"productCost":{"type":"number"},"shippingCost":{"type":"number"},"shippingCharged":{"type":"number"},"platformFeePct":{"type":"number"},"platformFeeFixed":{"type":"number"},"adCost":{"type":"number"}},"required":["salePrice","productCost"]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}},"/api/target-price":{"post":{"operationId":"penny_target_price","summary":"Find minimum price for target gross margin after fees. Free, no signup, deterministic.","tags":["Commerce"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"cost":{"type":"number"},"feePct":{"type":"number"},"feeFixed":{"type":"number"},"targetMarginPct":{"type":"number"}},"required":["cost"]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}},"/api/campaign-economics":{"post":{"operationId":"penny_campaign_economics","summary":"Customer acquisition cost and break-even click price. Free, no signup, deterministic.","tags":["Marketing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"costPerClick":{"type":"number"},"conversionRatePct":{"type":"number"},"contributionPerOrderUsd":{"type":"number"}},"required":["costPerClick","conversionRatePct","contributionPerOrderUsd"]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}},"/api/subscription-ltv":{"post":{"operationId":"penny_subscription_ltv","summary":"Simple monthly churn lifetime value estimates. Free, no signup, deterministic.","tags":["Marketing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"pricePerMonth":{"type":"number"},"monthlyChurnPct":{"type":"number"},"grossMarginPct":{"type":"number"},"acquisitionCostUsd":{"type":"number"}},"required":["pricePerMonth","monthlyChurnPct"]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}},"/api/url-clean":{"post":{"operationId":"penny_url_clean","summary":"Remove common tracking parameters from HTTP links without fetching. Free, no signup, deterministic.","tags":["Developer"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string"},"removeAllQuery":{"type":"boolean"}},"required":["url"]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}},"/api/slugify":{"post":{"operationId":"penny_slugify","summary":"Turn a short string into a lowercase ASCII URL slug. Free, no signup, deterministic.","tags":["Developer"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"text":{"type":"string"}},"required":["text"]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}},"/api/json-inspect":{"post":{"operationId":"penny_json_inspect","summary":"Parse and inspect bounded JSON input without retaining it. Free, no signup, deterministic.","tags":["Developer"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"text":{"type":"string"}},"required":["text"]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}},"/api/html-extract":{"post":{"operationId":"penny_html_extract","summary":"Extract structured page title, meta tags, headings and JSON-LD from supplied HTML without browsing or executing scripts. Free, no signup, deterministic.","tags":["Developer"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"html":{"type":"string"}},"required":["html"]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}},"/api/csv-to-json":{"post":{"operationId":"penny_csv_to_json","summary":"Transform CSV text into a bounded array of JSON records with quoted cell support. Free, no signup, deterministic.","tags":["Developer"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"csv":{"type":"string"}},"required":["csv"]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}},"/api/catalog-audit":{"post":{"operationId":"penny_catalog_audit","summary":"Batch-audit up to 50 product records for duplicate SKUs, missing attributes, malformed URLs and estimated net contribution per order. Useful for scheduled ecommerce catalog ingestion and agent product publishing. No external network calls. Free, no signup.","tags":["Commerce"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"items":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"sku":{"type":"string","maxLength":100},"name":{"type":"string","maxLength":200},"price":{"type":"number","minimum":0},"cost":{"type":"number","minimum":0},"shippingCost":{"type":"number","minimum":0},"feePct":{"type":"number","minimum":0,"maximum":70},"url":{"type":"string","maxLength":1000}},"required":["sku","name"]}},"targetMarginPct":{"type":"number","minimum":-100,"maximum":95}},"required":["items"]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}},"/api/trend-radar":{"post":{"operationId":"penny_trend_radar","summary":"Get recent US Google Trends rising-search queries and transparent heuristic purchase-intent classification to identify digital product research candidates. Public RSS, cached 10 minutes, no customer or sales data. Free, no signup.","tags":["Market Research"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"number","description":"Maximum entries to return; integer 1–25, default 10"},"commercialOnly":{"type":"boolean","description":"Only include potential commercial-intent terms; default false"}},"required":[]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}},"/api/capability-router":{"post":{"operationId":"penny_capability_router","summary":"Resolve an agent task to existing Penny Engine capabilities only. Does not execute, purchase, research live web content, or claim to handle arbitrary tasks. Unsupported requests are labeled explicitly. Free, no signup.","tags":["Agent Integration"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"task":{"type":"string","minLength":3,"maxLength":180}},"required":["task"]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}},"/api/fulfillment-preflight":{"post":{"operationId":"penny_fulfillment_preflight","summary":"FREE checkout preflight for M2M catalog CSV workflow. Inspect buyer-supplied product CSV, verify inputs and receive exact $0.001 Base USDC paid endpoint. Does NOT charge, sign or complete a sale; agents choose payment later.","tags":["Agent Integration"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"goal":{"type":"string","enum":["catalog-csv-audit"]},"input":{"type":"object","additionalProperties":false,"properties":{"csv":{"type":"string","minLength":15,"maxLength":9500},"targetMarginPct":{"type":"number","minimum":0,"maximum":95}},"required":["csv"]},"maxPriceUsd":{"type":"number","minimum":0.001}},"required":["goal","input"]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}},"/api/choose-service":{"post":{"operationId":"penny_choose_service","summary":"Given an agent's real task, get the single best supported Penny Engine payable route, exact $0.001 quote, required input, sample, and buyer-authorized checkout instructions. Includes optional FREE CSV preflight; does not sign, pay or execute a paid call.","tags":["Agent Integration"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"task":{"type":"string","minLength":3,"maxLength":180},"maxPriceUsd":{"type":"number","minimum":0},"input":{"type":"object","description":"Optional catalog CSV input for free validation, or a public wallet address."}},"required":["task"]}}}},"responses":{"200":{"description":"JSON calculation"},"400":{"description":"Invalid input"},"429":{"description":"Rate limit"}}}}}}