{"openapi":"3.1.0","info":{"title":"KillionApps Promotion Allocation API","version":"0.4.0","description":"Experimental, platform-neutral promotion-capital allocation capability for commerce agents."},"servers":[{"url":"https://killionapps-promotion-allocation-sandbox.onrender.com"}],"x-payment-info":{"offers":[{"amount":"500","currency":"usd","intent":"charge","method":"stripe"}]},"paths":{"/skill.md":{"get":{"operationId":"getAgentSkillDocument","summary":"Get the complete agent evaluation and purchase guide","responses":{"200":{"description":"Markdown agent skill document","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/llms.txt":{"get":{"operationId":"getLlmDiscoveryIndex","summary":"Get the LLM-readable discovery index","responses":{"200":{"description":"Plain-text discovery index","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/.well-known/agent-card.json":{"get":{"operationId":"getA2aAgentCard","summary":"Get the A2A 1.0 Agent Card","responses":{"200":{"description":"A2A Agent Card for KillionApps"}}}},"/mcp":{"post":{"operationId":"invokeRemoteMcp","summary":"Invoke the Streamable HTTP MCP server","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"MCP JSON-RPC result"},"202":{"description":"MCP notification accepted"},"403":{"description":"Rejected Host or Origin"}}}},"/v1/allocate":{"post":{"operationId":"allocatePromotionCapital","summary":"Purchase one promotion-allocation decision","description":"Returns a versioned portfolio allocation decision. Price: $5 USD. This experimental version does not claim causal incremental-profit lift.","x-payment-info":{"offers":[{"amount":"500","currency":"usd","intent":"charge","method":"stripe"}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["as_of","budget","products"],"properties":{"as_of":{"type":"string","format":"date-time"},"budget":{"type":"number","exclusiveMinimum":0,"maximum":1000000000},"currency":{"type":"string","pattern":"^[A-Z]{3}$","default":"USD"},"objective":{"type":"string","enum":["maximize_expected_incremental_contribution_profit"]},"constraints":{"type":"object","properties":{"max_product_share":{"type":"number","minimum":0.01,"maximum":1,"default":0.25},"scale_pool_share":{"type":"number","minimum":0,"maximum":1,"default":0.7},"keep_pool_share":{"type":"number","minimum":0,"maximum":1,"default":0.1},"exploration_pool_share":{"type":"number","minimum":0,"maximum":1,"default":0.2},"exploration_products":{"type":"integer","minimum":1,"maximum":20,"default":5}},"additionalProperties":false},"products":{"type":"array","minItems":2,"maxItems":2000,"items":{"type":"object","required":["product_id","promotion_eligible","history"],"properties":{"product_id":{"type":"string","minLength":1,"maxLength":200},"name":{"type":"string","minLength":1,"maxLength":200},"promotion_eligible":{"type":"boolean"},"inventory":{"type":"number","minimum":0},"cost_confidence":{"type":"string","enum":["high","medium","low","unknown"]},"history":{"type":"array","minItems":1,"maxItems":3660,"items":{"type":"object","required":["timestamp","units","revenue"],"properties":{"timestamp":{"type":"string","format":"date-time"},"units":{"type":"number","minimum":0},"revenue":{"type":"number"},"variable_cost":{"type":"number"},"marketplace_or_payment_fees":{"type":"number"},"promotion_spend":{"type":"number"},"promotion_impressions":{"type":"number","minimum":0},"promotion_clicks":{"type":"number","minimum":0},"promotion_orders":{"type":"number","minimum":0},"promotion_revenue":{"type":"number"}},"additionalProperties":false}}},"additionalProperties":false}}},"examples":[{"as_of":"2026-08-10T23:59:59.000Z","budget":100,"currency":"USD","objective":"maximize_expected_incremental_contribution_profit","constraints":{"max_product_share":0.6,"scale_pool_share":0.7,"keep_pool_share":0.1,"exploration_pool_share":0.2,"exploration_products":1},"products":[{"product_id":"validator_product_a","name":"Established product","promotion_eligible":true,"cost_confidence":"high","history":[{"timestamp":"2026-07-20T00:00:00.000Z","units":10,"revenue":500,"variable_cost":240,"marketplace_or_payment_fees":50,"promotion_spend":35,"promotion_impressions":5000,"promotion_clicks":80,"promotion_orders":6,"promotion_revenue":300},{"timestamp":"2026-08-05T00:00:00.000Z","units":12,"revenue":600,"variable_cost":288,"marketplace_or_payment_fees":60,"promotion_spend":40,"promotion_impressions":6000,"promotion_clicks":95,"promotion_orders":7,"promotion_revenue":350}]},{"product_id":"validator_product_b","name":"Emerging product","promotion_eligible":true,"cost_confidence":"medium","history":[{"timestamp":"2026-07-25T00:00:00.000Z","units":3,"revenue":150,"variable_cost":60,"marketplace_or_payment_fees":15,"promotion_spend":5,"promotion_impressions":800,"promotion_clicks":12,"promotion_orders":1,"promotion_revenue":50},{"timestamp":"2026-08-08T00:00:00.000Z","units":7,"revenue":350,"variable_cost":140,"marketplace_or_payment_fees":35,"promotion_spend":8,"promotion_impressions":1200,"promotion_clicks":20,"promotion_orders":1,"promotion_revenue":50}]}]}],"additionalProperties":false},"example":{"as_of":"2026-08-10T23:59:59.000Z","budget":100,"currency":"USD","objective":"maximize_expected_incremental_contribution_profit","constraints":{"max_product_share":0.6,"scale_pool_share":0.7,"keep_pool_share":0.1,"exploration_pool_share":0.2,"exploration_products":1},"products":[{"product_id":"validator_product_a","name":"Established product","promotion_eligible":true,"cost_confidence":"high","history":[{"timestamp":"2026-07-20T00:00:00.000Z","units":10,"revenue":500,"variable_cost":240,"marketplace_or_payment_fees":50,"promotion_spend":35,"promotion_impressions":5000,"promotion_clicks":80,"promotion_orders":6,"promotion_revenue":300},{"timestamp":"2026-08-05T00:00:00.000Z","units":12,"revenue":600,"variable_cost":288,"marketplace_or_payment_fees":60,"promotion_spend":40,"promotion_impressions":6000,"promotion_clicks":95,"promotion_orders":7,"promotion_revenue":350}]},{"product_id":"validator_product_b","name":"Emerging product","promotion_eligible":true,"cost_confidence":"medium","history":[{"timestamp":"2026-07-25T00:00:00.000Z","units":3,"revenue":150,"variable_cost":60,"marketplace_or_payment_fees":15,"promotion_spend":5,"promotion_impressions":800,"promotion_clicks":12,"promotion_orders":1,"promotion_revenue":50},{"timestamp":"2026-08-08T00:00:00.000Z","units":7,"revenue":350,"variable_cost":140,"marketplace_or_payment_fees":35,"promotion_spend":8,"promotion_impressions":1200,"promotion_clicks":20,"promotion_orders":1,"promotion_revenue":50}]}]}}}},"responses":{"200":{"description":"Paid versioned allocation decision","content":{"application/json":{"schema":{"type":"object","required":["decision_id","decision_version","recommendations","experimental"],"properties":{"decision_id":{"type":"string"},"decision_version":{"type":"string"},"experimental":{"type":"boolean"},"incrementality_status":{"type":"string"},"expected_incremental_contribution_profit":{"type":["number","null"]},"recommendations":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Invalid portfolio payload"},"402":{"description":"MPP payment challenge"},"413":{"description":"Request body exceeds the configured limit"},"415":{"description":"Content-Type must be application/json"},"429":{"description":"Rate limit exceeded"}}}},"/v1/validate":{"post":{"operationId":"validatePromotionAllocationRequest","summary":"Validate an allocation request for free","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Valid payload"},"400":{"description":"Invalid payload"},"413":{"description":"Request body exceeds the configured limit"},"415":{"description":"Content-Type must be application/json"},"429":{"description":"Rate limit exceeded"}}}},"/v1/quote":{"get":{"operationId":"getPromotionAllocationQuote","summary":"Get the current KillionApps machine price","responses":{"200":{"description":"Machine-readable price and endpoint metadata"}}}},"/v1/reputation":{"get":{"operationId":"getPromotionAllocationReputation","summary":"Get factual validation and performance-claim status","responses":{"200":{"description":"Factual machine reputation record"}}}},"/health":{"get":{"operationId":"health","summary":"Service health","responses":{"200":{"description":"Service is healthy"}}}}}}