{"openapi":"3.1.0","info":{"title":"Stoke Pricing API","version":"1.0.0","description":"Deterministic price recommendations with machine-readable decision evidence, guarantees, assumptions, and warnings."},"servers":[{"url":"https://7257ff762093:8080","description":"This Stoke deployment"}],"paths":{"/api/v1/recommendations":{"post":{"operationId":"createPricingRecommendation","summary":"Create a pricing recommendation","description":"Calculates the next price using Stoke's sigma_lin strategy. Every numeric recommendation is produced by the deterministic pricing core.","security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendationRequest"},"examples":{"elasticity":{"summary":"Elasticity bounds","value":{"currentPrice":99,"currentVolume":1200,"currency":"USD","volumePeriod":"month","bounds":{"mode":"elasticity","epsSteep":-2.5,"epsFlat":-0.5}}}}}}},"responses":{"200":{"description":"Recommendation calculated","headers":{"x-request-id":{"schema":{"type":"string"},"description":"Request trace identifier"},"x-ratelimit-remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendationResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Stoke API key as a bearer token"},"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"RecommendationRequest":{"type":"object","additionalProperties":false,"required":["currentPrice","currentVolume","bounds"],"properties":{"currentPrice":{"type":"number","exclusiveMinimum":0,"description":"Current unit price"},"currentVolume":{"type":"number","exclusiveMinimum":0,"description":"Units sold during volumePeriod"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","default":"USD","description":"Display-only ISO 4217 currency code; it does not change the calculation"},"volumePeriod":{"type":"string","description":"Human-readable period such as month; it does not change the calculation"},"bounds":{"oneOf":[{"$ref":"#/components/schemas/DirectBounds"},{"$ref":"#/components/schemas/ElasticityBounds"},{"$ref":"#/components/schemas/HistoryBounds"}]}}},"DirectBounds":{"type":"object","additionalProperties":false,"required":["mode","tauLo","tauHi"],"properties":{"mode":{"const":"direct"},"tauLo":{"type":"number","exclusiveMaximum":0,"description":"Steepest allowed demand slope"},"tauHi":{"type":"number","exclusiveMaximum":0,"description":"Flattest allowed demand slope"}}},"ElasticityBounds":{"type":"object","additionalProperties":false,"required":["mode","epsSteep","epsFlat"],"properties":{"mode":{"const":"elasticity"},"epsSteep":{"type":"number","exclusiveMaximum":0,"description":"Most-negative elasticity"},"epsFlat":{"type":"number","exclusiveMaximum":0,"description":"Least-negative elasticity"}}},"HistoryBounds":{"type":"object","additionalProperties":false,"required":["mode","observations"],"properties":{"mode":{"const":"history"},"observations":{"type":"array","minItems":2,"items":{"type":"object","additionalProperties":false,"required":["price","volume"],"properties":{"price":{"type":"number","exclusiveMinimum":0},"volume":{"type":"number","exclusiveMinimum":0}}}},"padLo":{"type":"number","default":1.5},"padHi":{"type":"number","default":0.67}}},"RecommendationResponse":{"type":"object","required":["object","recommendation","explanation","interpretation","resolvedBounds","context","algorithm"],"properties":{"object":{"const":"pricing_recommendation"},"recommendation":{"type":"object","required":["currentPrice","recommendedPrice","direction","percentChange","currency"],"properties":{"currentPrice":{"type":"number"},"recommendedPrice":{"type":"number"},"direction":{"type":"string","enum":["raise","hold","lower"]},"percentChange":{"type":"number","description":"Decimal change; 0.1 means 10%"},"currency":{"type":"string"}}},"explanation":{"type":"object","description":"Deterministic evidence produced by the same core calculation as the recommendation","properties":{"decision":{"type":"object","properties":{"branch":{"type":"string","enum":["raise","hold","lower"]},"observedVolume":{"type":"number"},"lowerThreshold":{"type":"number"},"upperThreshold":{"type":"number"},"comparison":{"type":"string","enum":["volume_above_upper_threshold","volume_between_thresholds","volume_below_lower_threshold"]},"activeSlope":{"type":["number","null"]},"formulaId":{"type":"string","enum":["sigma_lin_raise","sigma_lin_hold","sigma_lin_lower"]}}},"bounds":{"type":"object","additionalProperties":true},"guarantee":{"type":"object","properties":{"captureFraction":{"type":"number","minimum":0,"maximum":1},"interpretation":{"const":"worst_case_profit_floor"},"strength":{"type":"string","enum":["strong","moderate","weak"]}}},"assumptions":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"interpretation":{"type":"object","description":"Human-readable wording corresponding to the stable explanation codes","additionalProperties":true},"resolvedBounds":{"type":"object","additionalProperties":{"type":"number"}},"diagnostics":{"type":"object","additionalProperties":true},"context":{"type":"object","additionalProperties":true},"algorithm":{"type":"object","additionalProperties":true}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"requestId":{"type":"string"}}}}}},"responses":{"InvalidRequest":{"description":"Request validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"API key missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Server configuration or calculation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}