{"openapi":"3.1.0","info":{"title":"Pointsvalue API","version":"0.1.0","description":"A fully local, program-agnostic loyalty/rewards points valuation methodology using the cents-per-point (CPP) framework: redemption valuation, ranking your own redemption options, cash-vs-points decisions, transfer-partner math, earn-rate effective rebate, annual-fee breakeven, devaluation impact, and a goal calculator, plus a methodology guide and glossary. No real program's current point values are bundled.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://pointsvalue.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/pointsvalue/docs"},"termsOfService":"https://connectorbay.com/pointsvalue/terms"},"servers":[{"url":"https://pointsvalue.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/pointsvalue/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/cents_per_point":{"post":{"operationId":"cents_per_point","summary":"The cents-per-point (CPP) value of one redemption: cash value ÷ points used, in cents, with a rough quality","description":"The cents-per-point (CPP) value of one redemption: cash value ÷ points used, in cents, with a rough quality\n    band. Use for \"is 25,000 points for a $400 flight good\", \"what's the cpp on this redemption\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cash_value":{"description":"The cash value of what you got for the redemption.","examples":[400],"exclusiveMinimum":0,"title":"Cash Value","type":"number"},"points_used":{"description":"Points/miles spent on it.","examples":[25000],"exclusiveMinimum":0,"title":"Points Used","type":"number"}},"required":["cash_value","points_used"],"title":"cents_per_pointArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/compare_redemptions":{"post":{"operationId":"compare_redemptions","summary":"Ranks several of your own redemption options by cents-per-point to find the best value among them, with the","description":"Ranks several of your own redemption options by cents-per-point to find the best value among them, with the\n    gap between best and worst. Use for \"which of these redemptions is the best value: A, B, C\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"redemptions":{"description":"2-20 of YOUR OWN redemption options, each {\"label\": \"...\", \"value\": 400, \"points\": 25000}.","examples":[[{"label":"Flight A","points":25000,"value":400},{"label":"Flight B","points":30000,"value":550}]],"items":{"additionalProperties":true,"type":"object"},"title":"Redemptions","type":"array"}},"required":["redemptions"],"title":"compare_redemptionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/cash_vs_points":{"post":{"operationId":"cash_vs_points","summary":"Whether to pay cash or points for one specific purchase: computes the implied CPP of using points here and","description":"Whether to pay cash or points for one specific purchase: computes the implied CPP of using points here and\n    compares it to your own baseline CPP for the program. Use for \"should I use points or pay cash for this hotel\n    night\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cash_price":{"description":"What this would cost in cash.","examples":[400],"exclusiveMinimum":0,"title":"Cash Price","type":"number"},"points_price":{"description":"What it costs in points.","examples":[25000],"exclusiveMinimum":0,"title":"Points Price","type":"number"},"your_baseline_cpp":{"description":"Your usual/target cents-per-point value for this program.","examples":[1.5],"exclusiveMinimum":0,"title":"Your Baseline Cpp","type":"number"}},"required":["cash_price","points_price","your_baseline_cpp"],"title":"cash_vs_pointsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/transfer_value":{"post":{"operationId":"transfer_value","summary":"The effective cents-per-point on your ORIGINAL points after transferring to a partner program at a given","description":"The effective cents-per-point on your ORIGINAL points after transferring to a partner program at a given\n    ratio and bonus, then redeeming there at an assumed CPP — so you can compare transferring versus redeeming\n    directly. Use for \"is it worth transferring my points to this partner with a 30% bonus\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"source_points":{"description":"Points you'd transfer out of your source program.","examples":[60000],"exclusiveMinimum":0,"title":"Source Points","type":"number"},"transfer_ratio_out":{"default":1,"description":"Source side of the ratio.","examples":[1],"exclusiveMinimum":0,"title":"Transfer Ratio Out","type":"number"},"transfer_ratio_in":{"default":1,"description":"Destination side of the ratio.","examples":[1],"exclusiveMinimum":0,"title":"Transfer Ratio In","type":"number"},"bonus_pct":{"default":0,"description":"A transfer bonus percentage, if any.","examples":[0,30],"maximum":200,"minimum":0,"title":"Bonus Pct","type":"number"},"destination_cpp":{"default":1.0,"description":"Your assumed cents-per-point value once transferred and redeemed.","examples":[1.8],"exclusiveMinimum":0,"title":"Destination Cpp","type":"number"}},"required":["source_points"],"title":"transfer_valueArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/earn_rate_value":{"post":{"operationId":"earn_rate_value","summary":"Turns an earn rate (points per dollar spent) plus your assumed redemption value into an effective cash-back","description":"Turns an earn rate (points per dollar spent) plus your assumed redemption value into an effective cash-back\n    percentage for that spend. Use for \"what's the effective rebate on 20,000 points for $1,000 spent, if I\n    redeem at 1.5 cents per point\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dollars_spent":{"description":"Dollars spent to earn the points.","examples":[1000],"exclusiveMinimum":0,"title":"Dollars Spent","type":"number"},"points_earned":{"description":"Points earned on that spend.","examples":[20000],"minimum":0,"title":"Points Earned","type":"number"},"redemption_cpp":{"description":"The cents-per-point you assume you'll redeem at.","examples":[1.5],"exclusiveMinimum":0,"title":"Redemption Cpp","type":"number"}},"required":["dollars_spent","points_earned","redemption_cpp"],"title":"earn_rate_valueArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/annual_fee_breakeven":{"post":{"operationId":"annual_fee_breakeven","summary":"Whether a program's annual fee pays for itself, given the cash value you actually extract from it in a","description":"Whether a program's annual fee pays for itself, given the cash value you actually extract from it in a\n    year. Use for \"does a $95 annual fee pay for itself if I get $150 of value a year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"annual_fee":{"description":"The program/card's annual fee.","examples":[95],"minimum":0,"title":"Annual Fee","type":"number"},"value_earned_per_year":{"description":"Cash value you actually extract per year (points earned at your own cpp, plus credits/perks you use).","examples":[150],"minimum":0,"title":"Value Earned Per Year","type":"number"}},"required":["annual_fee","value_earned_per_year"],"title":"annual_fee_breakevenArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/devaluation_impact":{"post":{"operationId":"devaluation_impact","summary":"Quantifies how a program devaluation (or improvement) — requiring a different number of points for the same","description":"Quantifies how a program devaluation (or improvement) — requiring a different number of points for the same\n    reward — changes your cents-per-point and how many extra points you now need. Use for \"the price went from\n    25,000 to 35,000 points for the same $400 flight, how much value did I lose\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"old_points_required":{"description":"Points the redemption used to cost.","examples":[25000],"exclusiveMinimum":0,"title":"Old Points Required","type":"number"},"new_points_required":{"description":"Points it costs now.","examples":[35000],"exclusiveMinimum":0,"title":"New Points Required","type":"number"},"redemption_value":{"description":"The cash value of the redemption (assumed unchanged).","examples":[400],"exclusiveMinimum":0,"title":"Redemption Value","type":"number"}},"required":["old_points_required","new_points_required","redemption_value"],"title":"devaluation_impactArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/points_needed_for_goal":{"post":{"operationId":"points_needed_for_goal","summary":"How many points you'd need to reach a target redemption value at a chosen cents-per-point. Use for \"how many","description":"How many points you'd need to reach a target redemption value at a chosen cents-per-point. Use for \"how many\n    points do I need for a $1,000 redemption at 1.5 cents per point\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"redemption_value_target":{"description":"The cash value you're aiming to redeem.","examples":[1000],"exclusiveMinimum":0,"title":"Redemption Value Target","type":"number"},"target_cpp":{"description":"The cents-per-point you're aiming to hit.","examples":[1.5],"exclusiveMinimum":0,"title":"Target Cpp","type":"number"}},"required":["redemption_value_target","target_cpp"],"title":"points_needed_for_goalArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/methodology_guide":{"post":{"operationId":"methodology_guide","summary":"Explains the cents-per-point (CPP) valuation framework, how to use it to compare redemptions, rough quality","description":"Explains the cents-per-point (CPP) valuation framework, how to use it to compare redemptions, rough quality\n    bands, and common pitfalls (fees/taxes on 'free' awards, blackout dates, expiry, devaluations). Use for \"how do\n    I value my points\", \"what counts as a good redemption\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"methodology_guideArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/glossary":{"post":{"operationId":"glossary","summary":"Definitions of loyalty-program terms — cents per point, devaluation, transfer partner, elite status, award","description":"Definitions of loyalty-program terms — cents per point, devaluation, transfer partner, elite status, award\n    chart, fuel surcharge, breakage, pooling, signup bonus, revenue-based earning. Use for \"what does breakage\n    mean\", \"what's an award chart\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up; omit to list all.","title":"Term"}},"title":"glossaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}