{"openapi":"3.0.3","info":{"title":"MLP Tax Computation API","version":"1.0.0","description":"IRS-cited tax computation for Master Limited Partnership (MLP) positions. Compute basis projections, estate planning analysis, K-1 basis tracking, sell-vs-hold comparisons, and ETF wrapper vs direct MLP analysis. Every response includes specific IRC section citations and source attribution.","contact":{"name":"lucasandersen.ai","url":"https://lucasandersen.ai/api"},"license":{"name":"Proprietary — commercial use requires paid tier"}},"servers":[{"url":"https://api.lucasandersen.ai","description":"Production"}],"tags":[{"name":"mlp","description":"MLP tax projection + analysis"},{"name":"basis","description":"K-1 partner basis worksheet"},{"name":"reference","description":"Supported MLPs + API status"},{"name":"mcp","description":"Model Context Protocol server"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key as Bearer token. Unauthenticated requests permitted at lower rate limit (10/day per IP)."}},"parameters":{},"schemas":{"Ticker":{"type":"string","enum":["EPD","ET","MPLX","WES","PAA","NRP","USAC","SUN"],"description":"Supported MLP ticker symbol"},"Attribution":{"type":"object","required":["source","methodology","url"],"properties":{"source":{"type":"string"},"methodology":{"type":"string"},"url":{"type":"string","format":"uri"}}},"SuccessEnvelope":{"type":"object","required":["success","data","citations","computation_id","engine_version","timestamp","attribution"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","description":"Endpoint-specific result"},"citations":{"type":"array","items":{"type":"string"},"description":"IRC sections and IRS publications used in the computation"},"computation_id":{"type":"string","description":"Unique per-call ID for audit trail"},"engine_version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"attribution":{"$ref":"#/components/schemas/Attribution"}}},"ErrorEnvelope":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"details":{"description":"Optional error-specific details"},"documentation":{"type":"string","format":"uri"},"supported_tickers":{"type":"array","items":{"type":"string"}},"limit":{"type":"integer"},"remaining":{"type":"integer"},"resetAt":{"type":"string","format":"date-time"},"upgrade":{"type":"string","format":"uri"}}},"ValidationIssue":{"type":"object","required":["field","issue"],"properties":{"field":{"type":"string"},"issue":{"type":"string"},"received":{"description":"Value received that failed validation"}}},"ProjectInput":{"type":"object","required":["ticker","units"],"properties":{"ticker":{"$ref":"#/components/schemas/Ticker"},"units":{"type":"number","minimum":1,"maximum":1000000},"purchasePrice":{"type":"number","minimum":0.01,"maximum":10000},"years":{"type":"integer","minimum":1,"maximum":50,"default":20},"taxBracket":{"type":"number","minimum":0.1,"maximum":0.5,"default":0.32},"distributionGrowth":{"type":"number","minimum":-0.5,"maximum":0.5}}},"EstatePositionInput":{"type":"object","required":["ticker","units"],"properties":{"ticker":{"$ref":"#/components/schemas/Ticker"},"units":{"type":"number","minimum":1,"maximum":1000000},"purchasePrice":{"type":"number","minimum":0.01,"maximum":10000},"yearsHeld":{"type":"integer","minimum":0,"maximum":50,"default":10}}},"EstateInput":{"type":"object","required":["positions"],"properties":{"positions":{"type":"array","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/EstatePositionInput"}},"beneficiaries":{"type":"integer","minimum":1,"maximum":20,"default":1},"communityProperty":{"type":"boolean","default":false},"taxBracket":{"type":"number","minimum":0.1,"maximum":0.5,"default":0.32},"state":{"type":"string","description":"2-letter state code"}}},"CompareInput":{"type":"object","required":["ticker","units"],"properties":{"ticker":{"$ref":"#/components/schemas/Ticker"},"units":{"type":"number","minimum":1,"maximum":1000000},"purchasePrice":{"type":"number"},"yearsHeld":{"type":"integer","default":10},"yearsToProject":{"type":"integer","default":10},"taxBracket":{"type":"number","default":0.32},"communityProperty":{"type":"boolean","default":false}}},"EtfInput":{"type":"object","required":["ticker","investmentAmount"],"properties":{"ticker":{"$ref":"#/components/schemas/Ticker"},"investmentAmount":{"type":"number","minimum":100,"maximum":100000000},"unitPrice":{"type":"number"},"years":{"type":"integer","default":20},"taxBracket":{"type":"number","default":0.32},"etfExpenseRatio":{"type":"number","default":0.0087},"etfCorporateTaxDrag":{"type":"number","default":0.21},"etfQualifiedDividendPct":{"type":"number","default":0.8}}},"StressInput":{"type":"object","required":["ticker","units","cutPercentage"],"properties":{"ticker":{"$ref":"#/components/schemas/Ticker"},"units":{"type":"number","minimum":1,"maximum":1000000},"purchasePrice":{"type":"number"},"years":{"type":"integer","default":20},"taxBracket":{"type":"number","default":0.32},"cutPercentage":{"type":"number","minimum":0.01,"maximum":0.99},"cutYear":{"type":"integer","default":5},"recoveryPeriod":{"type":"integer","default":3},"recoveryShape":{"type":"string","enum":["linear","step","immediate"],"default":"linear"}}},"BatchInput":{"type":"object","required":["requests"],"properties":{"requests":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["endpoint","params"],"properties":{"endpoint":{"type":"string","enum":["project","estate","compare","etf","stress"]},"params":{"type":"object"}}}}}},"K1BoxData":{"type":"object","required":["box1","box19a"],"properties":{"box1":{"type":"number","description":"Ordinary business income (loss)"},"box2":{"type":"number","description":"Net rental income"},"box4a":{"type":"number","description":"Guaranteed payments"},"box5":{"type":"number","description":"Interest income"},"box6a":{"type":"number","description":"Ordinary dividends"},"box11":{"type":"number","description":"§179 / other deductions"},"box13w":{"type":"number","description":"§199A QBI amount"},"box19a":{"type":"number","description":"Cash distributions"},"box19b":{"type":"number","description":"Property distributions"},"liabilityIncrease":{"type":"number","description":"§752(a) increase"},"liabilityDecrease":{"type":"number","description":"§752(b) decrease"}}},"BasisComputeInput":{"type":"object","required":["ticker","units","priorBasis","k1Data"],"properties":{"ticker":{"$ref":"#/components/schemas/Ticker"},"units":{"type":"number"},"priorBasis":{"type":"number","minimum":0},"k1Data":{"$ref":"#/components/schemas/K1BoxData"},"taxBracket":{"type":"number","default":0.32}}},"BasisMultiYearInput":{"type":"object","required":["ticker","units","purchasePrice","k1Years"],"properties":{"ticker":{"$ref":"#/components/schemas/Ticker"},"units":{"type":"number"},"purchasePrice":{"type":"number"},"purchaseYear":{"type":"integer","default":2015},"taxBracket":{"type":"number","default":0.32},"k1Years":{"type":"array","minItems":1,"maxItems":50,"items":{"allOf":[{"$ref":"#/components/schemas/K1BoxData"},{"type":"object","required":["year"],"properties":{"year":{"type":"integer","minimum":1900,"maximum":2100}}}]}}}}},"responses":{"Success":{"description":"Successful computation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Engine-Version":{"schema":{"type":"string"}},"X-Cache":{"schema":{"type":"string","enum":["HIT","MISS","BYPASS"]}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}}},"ValidationError":{"description":"Validation failed","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"type":"object","properties":{"details":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssue"}}}}]}}}},"RateLimitExceeded":{"description":"Rate limit exceeded for this key/IP","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid API key (when required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/v1/health":{"get":{"tags":["reference"],"summary":"API status and endpoint list","security":[],"responses":{"200":{"$ref":"#/components/responses/Success"}}}},"/v1/mlps":{"get":{"tags":["reference"],"summary":"List of supported MLPs with default parameters","security":[],"responses":{"200":{"$ref":"#/components/responses/Success"}}}},"/v1/mlp/project":{"post":{"tags":["mlp"],"summary":"Multi-year basis + tax projection","description":"Compute year-by-year basis erosion, §751 accumulation, annual federal tax, terminal FMV, §1014 step-up value, and break-even sell price.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectInput"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/v1/mlp/estate":{"post":{"tags":["mlp"],"summary":"§1014 step-up analysis across multiple positions","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstateInput"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/v1/mlp/compare":{"post":{"tags":["mlp"],"summary":"Sell-vs-hold comparison with break-even price","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareInput"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/v1/mlp/etf":{"post":{"tags":["mlp"],"summary":"Direct MLP vs C-corp ETF wrapper comparison","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EtfInput"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/v1/mlp/stress":{"post":{"tags":["mlp"],"summary":"Distribution cut stress test","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StressInput"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/v1/mlp/batch":{"post":{"tags":["mlp"],"summary":"Batch up to 20 endpoint calls in a single request","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchInput"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/v1/basis/compute":{"post":{"tags":["basis"],"summary":"Single-year partner basis from K-1 data (IRS worksheet Lines 1-14)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasisComputeInput"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/v1/basis/multi-year":{"post":{"tags":["basis"],"summary":"Running basis across multiple years with broker-gap analysis","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasisMultiYearInput"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/mcp":{"post":{"tags":["mcp"],"summary":"MCP JSON-RPC 2.0 endpoint for AI agent tool use","description":"Methods: initialize, tools/list, tools/call, ping. 6 tools available: mlp_projection, mlp_estate_planning, mlp_sell_vs_hold, mlp_info, k1_basis_compute, k1_basis_multi_year.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{},"method":{"type":"string"},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response"}}}}},"x-engine-version":"0.1.0"}