{"openapi":"3.1.0","info":{"title":"Giftwise API","version":"2026-11-08","description":"Benefit-safe giving checks for people who receive SSI. Rules version 2026.1. Every answer cites the regulation or SSA's operating manual. Sandbox only: no real money and no real personal data."},"servers":[{"url":"https://giftwise-405i.onrender.com"}],"tags":[{"name":"Checks","description":"The rules engine and the AI readers. A key is optional; with one you get higher limits and usage."},{"name":"Utilities","description":"Presets, the ledger check and service status."},{"name":"Keys","description":"Free sandbox keys."},{"name":"Manage","description":"A page's organizer, through its private manage link: the needs, the note, and the person's situation."}],"paths":{"/api/v1/check-gift":{"post":{"operationId":"checkGift","summary":"Check a gift","description":"How one gift changes her SSI check, the benefit-safe way to give it, and the rules and sources behind the answer.","tags":["Checks"],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"Success. The answer is in data; meta has request_id, version, rules_version and latency_ms.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CheckGiftData"}}}]}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"gift":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":100000,"description":"Gift amount in US dollars."},"delivery":{"type":"string","enum":["cash","vendor","item","able"],"description":"How the gift reaches her: cash to her, paid to a vendor, the item itself, or her ABLE account. A home given outright is item, with category mortgage."},"category":{"default":"other","type":"string","enum":["medical","equipment","phone","internet","education","utility","rent","mortgage","property_tax","food","clothing","transport","personal","event","other"],"description":"What the money is for. Rent, mortgage, property tax and utilities are housing (shelter). event means tickets to a game, show or other event; a birthday or holiday gift of money is other."},"date":{"description":"Date the gift arrives, YYYY-MM-DD. Defaults to today.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"recurring":{"description":"True when the same giver pays this every month.","type":"boolean"},"giver":{"description":"Who gives it, for example a first name. In a list of gifts, two gifts from the same giver in one quarter (or the months either side) are not one-off, so neither gets the $60 exclusion.","type":"string","maxLength":80},"label":{"description":"A short name for the gift, such as Wheelchair repair. It comes back with the answer and does not change the math.","type":"string","maxLength":120},"covers":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"First month covered, YYYY-MM."},"to":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"Last month covered, YYYY-MM."}},"required":["from","to"],"description":"For a housing bill paid ahead or behind: the months it covers. A gift's share for months up to the payment counts when it is paid, and each later month's share in that month (POMS SI 00835.360 D.2)."},"payerCoOwns":{"description":"True when the person paying a housing bill co-owns the home. The payment is not a gift, so with covers each month's share counts in that month, past months included (POMS SI 00835.360 D.3).","type":"boolean"},"rentPaid":{"description":"For rent below market from a landlord who is her parent or child: the monthly rent she pays, with category rent and amount the market rent less that rent. The subsidy counted is the lesser of the market rent and the presumed maximum value, less this rent (POMS SI 00835.380).","type":"number","minimum":0,"maximum":100000},"every":{"type":"string","enum":["week","two_weeks"],"description":"For rent or another housing bill paid to the landlord or company weekly (week) or every two weeks (two_weeks): the amount is one payment, and the month counts the weekly amount times 13, divided by 3, a two-week amount halved first (POMS SI 00835.474 B.3)."},"loan":{"type":"object","properties":{"mustRepay":{"type":"boolean","description":"She must repay it whether or not SSI or any other benefit is ever paid (POMS SI 00835.482 B.3)."},"agreedWhenGiven":{"type":"boolean","description":"She and the lender both agreed she would repay at the time it was given, not afterwards (B.2, B.3)."},"feasiblePlan":{"type":"boolean","description":"She has a plan to repay from her own income or property that she can meet; services do not count (B.4, B.5)."},"enforceable":{"description":"Enforceable under the State's law (B.1). Leave it out to mean yes.","type":"boolean"},"repay":{"description":"What she agreed to repay, when less than the amount: her share of a bill paid for the household (B.4).","type":"number","minimum":0,"maximum":100000},"fromHousehold":{"description":"True when the household she lives in lends her its own shelter: the amount borrowed counts as what she pays toward her share of its costs (SI 00835.482 E, F).","type":"boolean"}},"required":["mustRepay","agreedWhenGiven","feasiblePlan"],"description":"Only for help that already exists and is a loan, to check how SSA counts it: a bona fide loan is not income (20 CFR 416.1103(f); cash, POMS SI 01120.220; food or shelter, SI 00835.482), and one that fails any test counts like the same help given. Giftwise moves gifts only; it does not arrange or record loans."}},"required":["amount","delivery"],"description":"The gift to check."},"profile":{"type":"object","properties":{"couple":{"default":false,"description":"True for a couple who both receive SSI. A couple's full check is higher ($1,491 a month in 2026) and their savings limit is $3,000.","type":"boolean"},"livesInAnothersHousehold":{"default":false,"description":"True when she lives all month in someone else's home, with no ownership or rental liability. Unless she pays her pro rata share of the household's costs (householdCosts with householdSize, or proRataShare, and householdPays; within $20 counts), the household's shelter lowers her check every month, gift or not: by the one-third reduction ($331.33 in 2026) when it gives her all her meals. With no householdPays she is taken to pay nothing.","type":"boolean"},"householdProvidesAllMeals":{"description":"Only used when livesInAnothersHousehold is true: whether that household gives her all her meals. The one-third reduction applies only then. Leave it out to mean true; false values housing help at up to $351.33 instead.","type":"boolean"},"otherUnearnedMonthly":{"default":0,"description":"Other unearned income each month, in US dollars, such as a pension. It is counted along with any cash gift.","type":"number","minimum":0,"maximum":100000},"earnedMonthly":{"default":0,"description":"Wages each month, in US dollars. After the first $65 and any of the $20 exclusion that is left, half of the rest is counted.","type":"number","minimum":0,"maximum":100000},"ableEligible":{"default":true,"description":"False when she cannot have an ABLE account. Then no gift is routed to ABLE.","type":"boolean"},"ableBalance":{"default":0,"description":"Her ABLE account balance, in US dollars. The first $100,000 does not count toward savings; the part over it does, and with her savings over the limit no SSI is paid that month, though Medicaid continues when the ABLE balance is the reason (POMS SI 01130.740 D.1). An ABLE gift that would take the account past $100,000 says so.","type":"number","minimum":0},"ableContributedThisYear":{"default":0,"description":"Dollars already put into her ABLE account this year. An ABLE gift that would pass the $20,000 yearly limit comes back with ambiguous set to true.","type":"number","minimum":0},"savings":{"default":1240,"description":"Her countable savings at the start of the month the gift arrives, in US dollars. Cash she keeps adds to it, and the answer says when it would pass the limit on the 1st ($2,000, or $3,000 for a couple). Over the limit, no SSI is paid for the month.","type":"number","minimum":0},"householdSize":{"description":"The people in her household, herself included (both members of a couple). Housing paid from outside the household is divided equally among them and she is charged her share (POMS SI 00835.350 B.4). Leave it out when no one else lives with her.","type":"integer","minimum":1,"maximum":20},"householdCosts":{"description":"In someone else's household: its monthly operating costs, rent or mortgage, property tax, heat, gas, electricity, water, sewer and garbage, not food (20 CFR 416.1133(c)). With householdSize it gives her pro rata share.","type":"number","minimum":0,"maximum":100000},"proRataShare":{"description":"Her pro rata share of those costs, when it is known directly (the couple's together). It takes the place of householdCosts.","type":"number","minimum":0,"maximum":100000},"householdPays":{"description":"What she pays toward those costs each month, in cash, not counting money for her food or any services (POMS SI 00835.480 C). Leave it out to mean nothing.","type":"number","minimum":0,"maximum":100000}},"description":"The person who receives SSI. Every field is optional; leave it out for one adult who lives on her own with $1,240 in savings."}},"required":["gift"]},"example":{"gift":{"amount":1000,"delivery":"cash","category":"other","date":"2026-04-10"},"profile":{"savings":1240}}}}}}},"/api/v1/plan-month":{"post":{"operationId":"planMonth","summary":"Plan several gifts","description":"Many gifts over several months, counted the way Social Security counts them: monthly, with the quarterly exclusion shared.","tags":["Checks"],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"Success. The answer is in data; meta has request_id, version, rules_version and latency_ms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"gifts":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":100000,"description":"Gift amount in US dollars."},"delivery":{"type":"string","enum":["cash","vendor","item","able"],"description":"How the gift reaches her: cash to her, paid to a vendor, the item itself, or her ABLE account. A home given outright is item, with category mortgage."},"category":{"default":"other","type":"string","enum":["medical","equipment","phone","internet","education","utility","rent","mortgage","property_tax","food","clothing","transport","personal","event","other"],"description":"What the money is for. Rent, mortgage, property tax and utilities are housing (shelter). event means tickets to a game, show or other event; a birthday or holiday gift of money is other."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date the gift arrives, YYYY-MM-DD."},"recurring":{"description":"True when the same giver pays this every month.","type":"boolean"},"giver":{"description":"Who gives it, for example a first name. In a list of gifts, two gifts from the same giver in one quarter (or the months either side) are not one-off, so neither gets the $60 exclusion.","type":"string","maxLength":80},"label":{"description":"A short name for the gift, such as Wheelchair repair. It comes back with the answer and does not change the math.","type":"string","maxLength":120},"covers":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"First month covered, YYYY-MM."},"to":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"Last month covered, YYYY-MM."}},"required":["from","to"],"description":"For a housing bill paid ahead or behind: the months it covers. A gift's share for months up to the payment counts when it is paid, and each later month's share in that month (POMS SI 00835.360 D.2)."},"payerCoOwns":{"description":"True when the person paying a housing bill co-owns the home. The payment is not a gift, so with covers each month's share counts in that month, past months included (POMS SI 00835.360 D.3).","type":"boolean"},"rentPaid":{"description":"For rent below market from a landlord who is her parent or child: the monthly rent she pays, with category rent and amount the market rent less that rent. The subsidy counted is the lesser of the market rent and the presumed maximum value, less this rent (POMS SI 00835.380).","type":"number","minimum":0,"maximum":100000},"every":{"type":"string","enum":["week","two_weeks"],"description":"For rent or another housing bill paid to the landlord or company weekly (week) or every two weeks (two_weeks): the amount is one payment, and the month counts the weekly amount times 13, divided by 3, a two-week amount halved first (POMS SI 00835.474 B.3)."},"loan":{"type":"object","properties":{"mustRepay":{"type":"boolean","description":"She must repay it whether or not SSI or any other benefit is ever paid (POMS SI 00835.482 B.3)."},"agreedWhenGiven":{"type":"boolean","description":"She and the lender both agreed she would repay at the time it was given, not afterwards (B.2, B.3)."},"feasiblePlan":{"type":"boolean","description":"She has a plan to repay from her own income or property that she can meet; services do not count (B.4, B.5)."},"enforceable":{"description":"Enforceable under the State's law (B.1). Leave it out to mean yes.","type":"boolean"},"repay":{"description":"What she agreed to repay, when less than the amount: her share of a bill paid for the household (B.4).","type":"number","minimum":0,"maximum":100000},"fromHousehold":{"description":"True when the household she lives in lends her its own shelter: the amount borrowed counts as what she pays toward her share of its costs (SI 00835.482 E, F).","type":"boolean"}},"required":["mustRepay","agreedWhenGiven","feasiblePlan"],"description":"Only for help that already exists and is a loan, to check how SSA counts it: a bona fide loan is not income (20 CFR 416.1103(f); cash, POMS SI 01120.220; food or shelter, SI 00835.482), and one that fails any test counts like the same help given. Giftwise moves gifts only; it does not arrange or record loans."}},"required":["amount","delivery","date"]},"description":"Between 1 and 500 gifts, in any order. Each one needs a date."},"profile":{"type":"object","properties":{"couple":{"default":false,"description":"True for a couple who both receive SSI. A couple's full check is higher ($1,491 a month in 2026) and their savings limit is $3,000.","type":"boolean"},"livesInAnothersHousehold":{"default":false,"description":"True when she lives all month in someone else's home, with no ownership or rental liability. Unless she pays her pro rata share of the household's costs (householdCosts with householdSize, or proRataShare, and householdPays; within $20 counts), the household's shelter lowers her check every month, gift or not: by the one-third reduction ($331.33 in 2026) when it gives her all her meals. With no householdPays she is taken to pay nothing.","type":"boolean"},"householdProvidesAllMeals":{"description":"Only used when livesInAnothersHousehold is true: whether that household gives her all her meals. The one-third reduction applies only then. Leave it out to mean true; false values housing help at up to $351.33 instead.","type":"boolean"},"otherUnearnedMonthly":{"default":0,"description":"Other unearned income each month, in US dollars, such as a pension. It is counted along with any cash gift.","type":"number","minimum":0,"maximum":100000},"earnedMonthly":{"default":0,"description":"Wages each month, in US dollars. After the first $65 and any of the $20 exclusion that is left, half of the rest is counted.","type":"number","minimum":0,"maximum":100000},"ableEligible":{"default":true,"description":"False when she cannot have an ABLE account. Then no gift is routed to ABLE.","type":"boolean"},"ableBalance":{"default":0,"description":"Her ABLE account balance, in US dollars. The first $100,000 does not count toward savings; the part over it does, and with her savings over the limit no SSI is paid that month, though Medicaid continues when the ABLE balance is the reason (POMS SI 01130.740 D.1). An ABLE gift that would take the account past $100,000 says so.","type":"number","minimum":0},"ableContributedThisYear":{"default":0,"description":"Dollars already put into her ABLE account this year. An ABLE gift that would pass the $20,000 yearly limit comes back with ambiguous set to true.","type":"number","minimum":0},"savings":{"default":1240,"description":"Her countable savings at the start of the month the gift arrives, in US dollars. Cash she keeps adds to it, and the answer says when it would pass the limit on the 1st ($2,000, or $3,000 for a couple). Over the limit, no SSI is paid for the month.","type":"number","minimum":0},"householdSize":{"description":"The people in her household, herself included (both members of a couple). Housing paid from outside the household is divided equally among them and she is charged her share (POMS SI 00835.350 B.4). Leave it out when no one else lives with her.","type":"integer","minimum":1,"maximum":20},"householdCosts":{"description":"In someone else's household: its monthly operating costs, rent or mortgage, property tax, heat, gas, electricity, water, sewer and garbage, not food (20 CFR 416.1133(c)). With householdSize it gives her pro rata share.","type":"number","minimum":0,"maximum":100000},"proRataShare":{"description":"Her pro rata share of those costs, when it is known directly (the couple's together). It takes the place of householdCosts.","type":"number","minimum":0,"maximum":100000},"householdPays":{"description":"What she pays toward those costs each month, in cash, not counting money for her food or any services (POMS SI 00835.480 C). Leave it out to mean nothing.","type":"number","minimum":0,"maximum":100000}},"description":"The person who receives SSI. Every field is optional; leave it out for one adult who lives on her own with $1,240 in savings."}},"required":["gifts"]},"example":{"gifts":[{"date":"2026-04-05","amount":50,"delivery":"cash","giver":"Ana"},{"date":"2026-06-25","amount":50,"delivery":"cash","giver":"Ben"},{"date":"2026-06-26","amount":420,"delivery":"vendor","category":"equipment","giver":"Dan"}]}}}}}},"/api/v1/read-bill":{"post":{"operationId":"readBill","summary":"Read a bill","description":"Upload a photo or PDF of a bill (multipart field file). Claude reads it. A bill at or near housing, or one Claude is less than 90% sure of, also goes to the two reviewers, and the referee decides; then the rules engine picks the benefit-safe way to pay it.","tags":["Checks"],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"Success. The answer is in data; meta has request_id, version, rules_version and latency_ms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"JPEG, PNG, WebP or PDF, up to 10 MB."}}}}}}}},"/api/v1/read-letter":{"post":{"operationId":"readLetter","summary":"Read a letter from Social Security","description":"Upload a photo or PDF of the person's letter about their SSI payment (multipart field file, optional field pronoun). Claude reads the facts a gift page asks for, each with a short quote, and never returns an SSN, claim number, address or date of birth. The rules engine computes the check from those facts and compares it with the payment the letter states; for a PDF with a text layer, each quote is checked against the letter's text. Nothing is stored: send the confirmed answers as profile to /api/v1/gift-pages or PATCH /api/manage/{token}.","tags":["Checks"],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"Success. The answer is in data; meta has request_id, version, rules_version and latency_ms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"JPEG, PNG, WebP or PDF, up to 10 MB."},"pronoun":{"type":"string","enum":["she","he","they"],"description":"How the answer refers to the person. Optional; she/her when left out."}}}}}}}},"/api/v1/analyze-fundraiser":{"post":{"operationId":"analyzeFundraiser","summary":"Read a fundraiser","description":"Read a public fundraiser page and plan how each use of the money can reach her without lowering her check.","tags":["Checks"],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"Success. The answer is in data; meta has request_id, version, rules_version and latency_ms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":8,"maxLength":2000,"description":"A public fundraiser page, http or https. A path on this site, such as /samples/fundraiser.html, also works."}},"required":["url"]},"example":{"url":"/samples/fundraiser.html"}}}}}},"/api/v1/review-bill":{"post":{"operationId":"reviewBill","summary":"Ask the two reviewers","description":"Two Claude reviewers decide whether a bill paid by someone else is a housing cost. One reads the regulations and the Federal Register, the other SSA's operating manual, and each must quote its rulebook word for word. A program checks every quote, and the rules engine picks the route.","tags":["Checks"],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"Success. The answer is in data; meta has request_id, version, rules_version and latency_ms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","minLength":3,"maxLength":2000,"description":"What the bill is for, in its own words: the business, the service and any line items."},"amount":{"type":"number","minimum":1,"maximum":100000,"description":"Amount someone else would pay, in US dollars."},"category":{"type":"string","enum":["medical","equipment","phone","internet","education","utility","rent","mortgage","property_tax","food","clothing","transport","personal","event","other"],"description":"The category the bill was read as. Housing categories (rent, mortgage, property tax, utility) are the ones the reviewers settle."},"date":{"description":"Date it is paid, YYYY-MM-DD. Defaults to today.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"recurring":{"description":"True when the same person pays it every month.","type":"boolean"},"profile":{"type":"object","properties":{"couple":{"default":false,"description":"True for a couple who both receive SSI. A couple's full check is higher ($1,491 a month in 2026) and their savings limit is $3,000.","type":"boolean"},"livesInAnothersHousehold":{"default":false,"description":"True when she lives all month in someone else's home, with no ownership or rental liability. Unless she pays her pro rata share of the household's costs (householdCosts with householdSize, or proRataShare, and householdPays; within $20 counts), the household's shelter lowers her check every month, gift or not: by the one-third reduction ($331.33 in 2026) when it gives her all her meals. With no householdPays she is taken to pay nothing.","type":"boolean"},"householdProvidesAllMeals":{"description":"Only used when livesInAnothersHousehold is true: whether that household gives her all her meals. The one-third reduction applies only then. Leave it out to mean true; false values housing help at up to $351.33 instead.","type":"boolean"},"otherUnearnedMonthly":{"default":0,"description":"Other unearned income each month, in US dollars, such as a pension. It is counted along with any cash gift.","type":"number","minimum":0,"maximum":100000},"earnedMonthly":{"default":0,"description":"Wages each month, in US dollars. After the first $65 and any of the $20 exclusion that is left, half of the rest is counted.","type":"number","minimum":0,"maximum":100000},"ableEligible":{"default":true,"description":"False when she cannot have an ABLE account. Then no gift is routed to ABLE.","type":"boolean"},"ableBalance":{"default":0,"description":"Her ABLE account balance, in US dollars. The first $100,000 does not count toward savings; the part over it does, and with her savings over the limit no SSI is paid that month, though Medicaid continues when the ABLE balance is the reason (POMS SI 01130.740 D.1). An ABLE gift that would take the account past $100,000 says so.","type":"number","minimum":0},"ableContributedThisYear":{"default":0,"description":"Dollars already put into her ABLE account this year. An ABLE gift that would pass the $20,000 yearly limit comes back with ambiguous set to true.","type":"number","minimum":0},"savings":{"default":1240,"description":"Her countable savings at the start of the month the gift arrives, in US dollars. Cash she keeps adds to it, and the answer says when it would pass the limit on the 1st ($2,000, or $3,000 for a couple). Over the limit, no SSI is paid for the month.","type":"number","minimum":0},"householdSize":{"description":"The people in her household, herself included (both members of a couple). Housing paid from outside the household is divided equally among them and she is charged her share (POMS SI 00835.350 B.4). Leave it out when no one else lives with her.","type":"integer","minimum":1,"maximum":20},"householdCosts":{"description":"In someone else's household: its monthly operating costs, rent or mortgage, property tax, heat, gas, electricity, water, sewer and garbage, not food (20 CFR 416.1133(c)). With householdSize it gives her pro rata share.","type":"number","minimum":0,"maximum":100000},"proRataShare":{"description":"Her pro rata share of those costs, when it is known directly (the couple's together). It takes the place of householdCosts.","type":"number","minimum":0,"maximum":100000},"householdPays":{"description":"What she pays toward those costs each month, in cash, not counting money for her food or any services (POMS SI 00835.480 C). Leave it out to mean nothing.","type":"number","minimum":0,"maximum":100000}},"description":"The person who receives SSI. Every field is optional; leave it out for one adult who lives on her own with $1,240 in savings."}},"required":["description","amount","category"]},"example":{"description":"Northside Electric Co-op, residential electric service, monthly bill","amount":138,"category":"utility","recurring":true}}}}}},"/api/v1/ask-rules":{"post":{"operationId":"askRules","summary":"Ask the rulebook","description":"Ask a question about SSI and gifts in plain words. Elasticsearch finds the passages (hybrid keyword and semantic search with jina-embeddings-v3, reranked by jina-reranker-v3) across the regulations, SSA's operating manual and its worked examples; Claude answers from only those passages, and a program checks every quote word for word.","tags":["Checks"],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"Success. The answer is in data; meta has request_id, version, rules_version and latency_ms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","minLength":4,"maxLength":300,"description":"A question about SSI and gifts, in plain words, for example \"Does it count if my sister pays my phone bill?\""}},"required":["question"]},"example":{"question":"Does it count as income if my sister pays my phone bill?"}}}}}},"/api/v1/gift-pages":{"post":{"operationId":"giftPages","summary":"Create a gift page","description":"Turn a list of needs, for example from a fundraiser, into a live gift page where every dollar is paid straight to the shop or the ABLE account through PayPal. The rules engine picks each route. Send the person's situation as profile and every check on the page uses it; without it the page names the sample situation it uses. Sandbox pages, five a day per visitor.","tags":["Checks"],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"Success. The answer is in data; meta has request_id, version, rules_version and latency_ms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40,"pattern":"^\\p{L}[\\p{L} .'-]*$","description":"First name of the person who receives SSI, as it should appear on the page."},"pronoun":{"type":"string","enum":["she","he","they"],"description":"How the page refers to them: she/her, he/him or they/them."},"organizer":{"description":"Who is organizing, for the thank-you line. Optional.","type":"string","maxLength":60},"note":{"description":"A short note to givers. Optional; a plain default is written if empty.","type":"string","maxLength":400},"source_url":{"description":"The fundraiser page the needs came from. Optional.","type":"string","maxLength":2000,"format":"uri"},"needs":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":2,"maxLength":80,"description":"What the money is for, in a few words."},"amount":{"type":"number","minimum":1,"maximum":20000,"description":"Dollars still needed."},"category":{"type":"string","enum":["medical","equipment","phone","internet","education","utility","rent","mortgage","property_tax","food","clothing","transport","personal","event","other"],"description":"What the money is for. Rent, mortgage, property tax and utilities are housing (shelter). event means tickets to a game, show or other event; a birthday or holiday gift of money is other."},"vendor":{"description":"The kind of business that would be paid, for example a van conversion shop.","anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"recurring":{"description":"True when the need comes back every month, such as rent.","type":"boolean"}},"required":["title","amount","category"]},"description":"What the page asks for. Giftwise decides each route: housing goes to the ABLE account, everything else straight to the shop."},"profile":{"description":"The person's own situation, so every check and route on the page uses their facts: where they live, Social Security or other benefits, wages, savings, a couple, and whether they can have an ABLE account. Send only the fields you know; the rest keep the sample situation's values. Left out, the page says it uses a sample situation (one adult on their own, no other income) until the organizer adds theirs.","type":"object","properties":{"couple":{"default":false,"description":"True for a couple who both receive SSI. A couple's full check is higher ($1,491 a month in 2026) and their savings limit is $3,000.","type":"boolean"},"livesInAnothersHousehold":{"default":false,"description":"True when she lives all month in someone else's home, with no ownership or rental liability. Unless she pays her pro rata share of the household's costs (householdCosts with householdSize, or proRataShare, and householdPays; within $20 counts), the household's shelter lowers her check every month, gift or not: by the one-third reduction ($331.33 in 2026) when it gives her all her meals. With no householdPays she is taken to pay nothing.","type":"boolean"},"householdProvidesAllMeals":{"description":"Only used when livesInAnothersHousehold is true: whether that household gives her all her meals. The one-third reduction applies only then. Leave it out to mean true; false values housing help at up to $351.33 instead.","type":"boolean"},"otherUnearnedMonthly":{"default":0,"description":"Other unearned income each month, in US dollars, such as a pension. It is counted along with any cash gift.","type":"number","minimum":0,"maximum":100000},"earnedMonthly":{"default":0,"description":"Wages each month, in US dollars. After the first $65 and any of the $20 exclusion that is left, half of the rest is counted.","type":"number","minimum":0,"maximum":100000},"ableEligible":{"default":true,"description":"False when she cannot have an ABLE account. Then no gift is routed to ABLE.","type":"boolean"},"ableBalance":{"default":0,"description":"Her ABLE account balance, in US dollars. The first $100,000 does not count toward savings; the part over it does, and with her savings over the limit no SSI is paid that month, though Medicaid continues when the ABLE balance is the reason (POMS SI 01130.740 D.1). An ABLE gift that would take the account past $100,000 says so.","type":"number","minimum":0},"ableContributedThisYear":{"default":0,"description":"Dollars already put into her ABLE account this year. An ABLE gift that would pass the $20,000 yearly limit comes back with ambiguous set to true.","type":"number","minimum":0},"savings":{"default":1240,"description":"Her countable savings at the start of the month the gift arrives, in US dollars. Cash she keeps adds to it, and the answer says when it would pass the limit on the 1st ($2,000, or $3,000 for a couple). Over the limit, no SSI is paid for the month.","type":"number","minimum":0},"householdSize":{"description":"The people in her household, herself included (both members of a couple). Housing paid from outside the household is divided equally among them and she is charged her share (POMS SI 00835.350 B.4). Leave it out when no one else lives with her.","type":"integer","minimum":1,"maximum":20},"householdCosts":{"description":"In someone else's household: its monthly operating costs, rent or mortgage, property tax, heat, gas, electricity, water, sewer and garbage, not food (20 CFR 416.1133(c)). With householdSize it gives her pro rata share.","type":"number","minimum":0,"maximum":100000},"proRataShare":{"description":"Her pro rata share of those costs, when it is known directly (the couple's together). It takes the place of householdCosts.","type":"number","minimum":0,"maximum":100000},"householdPays":{"description":"What she pays toward those costs each month, in cash, not counting money for her food or any services (POMS SI 00835.480 C). Leave it out to mean nothing.","type":"number","minimum":0,"maximum":100000}}},"profile_source":{"type":"string","enum":["answers","letter"],"description":"How the facts were gathered: answers typed by the organizer, or read from the person's letter from Social Security and then confirmed. Optional; the letter itself is never stored."}},"required":["name","pronoun","needs"]},"example":{"name":"Jordan","pronoun":"they","organizer":"Sam","needs":[{"title":"Van wheelchair lift","amount":1800,"category":"transport","vendor":"a van conversion shop"},{"title":"Rent, December","amount":650,"category":"rent"}],"profile":{"livesInAnothersHousehold":true,"otherUnearnedMonthly":600},"profile_source":"answers"}}}}}},"/api/v1/ssa-report":{"get":{"operationId":"ssaReport","summary":"Monthly report to SSA","description":"One month of a gift page's gifts, written up as SSI reporting asks: what to tell Social Security by the 10th of the next month, and the PayPal capture or payout behind every gift that is not income. Add view=cash to see the report the same gifts would have needed as cash, or format=csv for a spreadsheet.","tags":["Checks"],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"Success. The answer is in data; meta has request_id, version, rules_version and latency_ms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"page","in":"query","description":"Gift page id, the part after /g/. The sample page is \"maya\".","schema":{"type":"string","example":"maya"}},{"name":"month","in":"query","description":"Income month, like 2026-10. Defaults to the month whose report is due next.","schema":{"type":"string","example":"2026-10"}},{"name":"view","in":"query","description":"\"given\" (default) or \"cash\".","schema":{"type":"string","enum":["given","cash"]}},{"name":"format","in":"query","description":"csv for a spreadsheet instead of JSON.","schema":{"type":"string","enum":["csv"]}}]}},"/api/presets/{id}":{"get":{"operationId":"presets","summary":"Download a preset","description":"A sample case with its input and the engine's current answer. Add ?format=csv for gift lists. Ids: wheelchair-repair, birthday-cash, electric-bill, rent-help, laptop-college, groceries, van-fundraiser, march-month.","tags":["Utilities"],"security":[],"responses":{"200":{"description":"Success. The answer is in data; meta has request_id, version, rules_version and latency_ms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["csv"]}}]}},"/api/ledger/verify":{"get":{"operationId":"ledger","summary":"Verify the ledger","description":"Recompute the audit ledger's SHA-256 hash chain from the first entry and report whether every entry still matches.","tags":["Utilities"],"security":[],"responses":{"200":{"description":"Success. The answer is in data; meta has request_id, version, rules_version and latency_ms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/health":{"get":{"operationId":"health","summary":"Service status","description":"Whether PayPal, Claude, the database and each sponsor tool are live or using a fallback right now.","tags":["Utilities"],"security":[],"responses":{"200":{"description":"Success. The answer is in data; meta has request_id, version, rules_version and latency_ms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/manage/{token}":{"get":{"operationId":"getManagedPage","summary":"Read a page you organize","description":"The page, its needs and the gifts received, with the person's situation (situation: own or sample, and the profile every check on the page uses) and their check with no gift.","tags":["Manage"],"parameters":[{"name":"token","in":"path","required":true,"description":"The page's private manage token, from manage_url when the page was made.","schema":{"type":"string"}}],"responses":{"200":{"description":"The page as its organizer sees it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateManagedPage","summary":"Change a page you organize","description":"Change the note, close or reopen the page, or set the person's situation: profile with the fields you know (the rest keep the sample situation's values), or null to go back to the sample situation. Only these confirmed facts are saved; a letter read with /api/v1/read-letter is never stored.","tags":["Manage"],"parameters":[{"name":"token","in":"path","required":true,"description":"The page's private manage token, from manage_url when the page was made.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"description":"The note to givers at the top of the page, up to 400 characters.","type":"string","maxLength":400},"status":{"description":"closed stops new gifts; open takes them again. Receipts stay public either way.","type":"string","enum":["open","closed"]},"profile":{"description":"The person's own situation, as for a new page: send the fields you know and the rest keep the sample situation's values. null puts the page back on the sample situation.","anyOf":[{"type":"object","properties":{"couple":{"default":false,"description":"True for a couple who both receive SSI. A couple's full check is higher ($1,491 a month in 2026) and their savings limit is $3,000.","type":"boolean"},"livesInAnothersHousehold":{"default":false,"description":"True when she lives all month in someone else's home, with no ownership or rental liability. Unless she pays her pro rata share of the household's costs (householdCosts with householdSize, or proRataShare, and householdPays; within $20 counts), the household's shelter lowers her check every month, gift or not: by the one-third reduction ($331.33 in 2026) when it gives her all her meals. With no householdPays she is taken to pay nothing.","type":"boolean"},"householdProvidesAllMeals":{"description":"Only used when livesInAnothersHousehold is true: whether that household gives her all her meals. The one-third reduction applies only then. Leave it out to mean true; false values housing help at up to $351.33 instead.","type":"boolean"},"otherUnearnedMonthly":{"default":0,"description":"Other unearned income each month, in US dollars, such as a pension. It is counted along with any cash gift.","type":"number","minimum":0,"maximum":100000},"earnedMonthly":{"default":0,"description":"Wages each month, in US dollars. After the first $65 and any of the $20 exclusion that is left, half of the rest is counted.","type":"number","minimum":0,"maximum":100000},"ableEligible":{"default":true,"description":"False when she cannot have an ABLE account. Then no gift is routed to ABLE.","type":"boolean"},"ableBalance":{"default":0,"description":"Her ABLE account balance, in US dollars. The first $100,000 does not count toward savings; the part over it does, and with her savings over the limit no SSI is paid that month, though Medicaid continues when the ABLE balance is the reason (POMS SI 01130.740 D.1). An ABLE gift that would take the account past $100,000 says so.","type":"number","minimum":0},"ableContributedThisYear":{"default":0,"description":"Dollars already put into her ABLE account this year. An ABLE gift that would pass the $20,000 yearly limit comes back with ambiguous set to true.","type":"number","minimum":0},"savings":{"default":1240,"description":"Her countable savings at the start of the month the gift arrives, in US dollars. Cash she keeps adds to it, and the answer says when it would pass the limit on the 1st ($2,000, or $3,000 for a couple). Over the limit, no SSI is paid for the month.","type":"number","minimum":0},"householdSize":{"description":"The people in her household, herself included (both members of a couple). Housing paid from outside the household is divided equally among them and she is charged her share (POMS SI 00835.350 B.4). Leave it out when no one else lives with her.","type":"integer","minimum":1,"maximum":20},"householdCosts":{"description":"In someone else's household: its monthly operating costs, rent or mortgage, property tax, heat, gas, electricity, water, sewer and garbage, not food (20 CFR 416.1133(c)). With householdSize it gives her pro rata share.","type":"number","minimum":0,"maximum":100000},"proRataShare":{"description":"Her pro rata share of those costs, when it is known directly (the couple's together). It takes the place of householdCosts.","type":"number","minimum":0,"maximum":100000},"householdPays":{"description":"What she pays toward those costs each month, in cash, not counting money for her food or any services (POMS SI 00835.480 C). Leave it out to mean nothing.","type":"number","minimum":0,"maximum":100000}},"description":"The person who receives SSI. Every field is optional; leave it out for one adult who lives on her own with $1,240 in savings."},{"type":"null"}]},"profile_source":{"type":"string","enum":["answers","letter"],"description":"How the facts were gathered: answers typed by the organizer, or read from the person's letter from Social Security and then confirmed. Optional; the letter itself is never stored."}}},"example":{"profile":{"livesInAnothersHousehold":true,"otherUnearnedMonthly":600},"profile_source":"letter"}}}},"responses":{"200":{"description":"The page's status, note, situation, profile and check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/keys":{"post":{"operationId":"createKey","summary":"Create a sandbox API key","description":"Returns the full key once. Only its SHA-256 hash is stored. Limits: 5 new keys per client and 3 per email each day.","tags":["Keys"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"Your name or your team's."},"email":{"type":"string","maxLength":200,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Where to reach you about the key."},"purpose":{"description":"What you are building. Optional.","type":"string","maxLength":200},"accept":{"type":"boolean","const":true,"description":"You accept that sandbox keys are for testing, with no real money and no real personal data."}},"required":["name","email","accept"]}}}},"responses":{"200":{"description":"The new key, shown once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A gw_test_ key from the Developers page."}},"schemas":{"CheckGiftData":{"type":"object","properties":{"check_before":{"type":"number","description":"Her check for the payment month with no gift."},"check_after":{"type":"number","description":"Her check for the payment month with the gift as given."},"counted_amount":{"type":"number","description":"How much of the gift counts as income after exclusions."},"income_month":{"type":"string","description":"The month the gift counts in, YYYY-MM: the month it arrives."},"payment_month":{"type":"string","description":"The month whose check the income month decides, two months later, YYYY-MM."},"best_route":{"type":"string","enum":["cash","vendor","item","able"],"description":"The way to give it that keeps the most of her check."},"check_with_best_route":{"type":"number","description":"Her check for the payment month on the best route."},"routes":{"type":"array","items":{"type":"object","properties":{"delivery":{"type":"string"},"check":{"type":"number"},"possible":{"type":"boolean"},"reason":{"type":"string"}},"required":["delivery","check","possible"],"additionalProperties":false},"description":"Every way to give it, with the check each leaves."},"resources_after_gift":{"type":"object","properties":{"on":{"type":"string","description":"The day the test is for, YYYY-MM-01."},"countable":{"type":"number","description":"Countable resources that day: other resources plus the ABLE balance over $100,000."},"other":{"type":"number","description":"Savings and other countable resources, before any ABLE balance."},"able_balance":{"type":"number","description":"The ABLE balance that day."},"able_excess":{"type":"number","description":"The part of the ABLE balance over $100,000, which counts as a resource."},"limit":{"type":"number","description":"The resource limit: $2,000, or $3,000 for a couple."},"over":{"type":"boolean","description":"True when countable resources are over the limit."},"status":{"type":"string","enum":["under","able_suspension","excess"],"description":"under: at or below the limit. able_suspension: over only because of the ABLE balance, so SSI cash stops and Medicaid continues. excess: over on other resources alone."}},"required":["on","countable","other","able_balance","able_excess","limit","over","status"],"additionalProperties":false,"description":"The resource test on the 1st of the month after the gift arrives, with the gift as given: cash she keeps adds to savings, an ABLE deposit to the account."},"resources_for_check":{"type":"object","properties":{"on":{"type":"string","description":"The day the test is for, YYYY-MM-01."},"countable":{"type":"number","description":"Countable resources that day: other resources plus the ABLE balance over $100,000."},"other":{"type":"number","description":"Savings and other countable resources, before any ABLE balance."},"able_balance":{"type":"number","description":"The ABLE balance that day."},"able_excess":{"type":"number","description":"The part of the ABLE balance over $100,000, which counts as a resource."},"limit":{"type":"number","description":"The resource limit: $2,000, or $3,000 for a couple."},"over":{"type":"boolean","description":"True when countable resources are over the limit."},"status":{"type":"string","enum":["under","able_suspension","excess"],"description":"under: at or below the limit. able_suspension: over only because of the ABLE balance, so SSI cash stops and Medicaid continues. excess: over on other resources alone."}},"required":["on","countable","other","able_balance","able_excess","limit","over","status"],"additionalProperties":false,"description":"The resource test on the 1st of the payment month, which decides that check: over the limit, the check is $0. It counts the savings she states and the ABLE deposits; cash kept from the gift is in resources_after_gift."},"household":{"anyOf":[{"type":"object","properties":{"rule":{"type":"string","enum":["vtr","pmv","none"],"description":"vtr: the one-third reduction, because the household gives her shelter and all her meals. pmv: the shelter it gives her counts as housing support up to the presumed maximum value. none: she pays her share."},"pro_rata_share":{"description":"Her pro rata share of the household's monthly costs (the couple's together), or null when not known.","type":["number","null"]},"pays":{"type":"number","description":"What she pays toward them each month, with any bona fide loan of the household's shelter."},"short_by":{"description":"How far what she pays falls short of her share, or null when her share is not known.","type":["number","null"]},"sharing":{"type":"boolean","description":"True when she pays her share, or within $20 of it, so the household does not lower her check."},"shelter_value":{"type":"number","description":"Under pmv, the value of the shelter the household gives her; 0 otherwise."},"lowers_check_before_gift":{"type":"boolean","description":"True when the household already lowers her check, whatever the gift."},"plain":{"description":"The same in plain words, as the explanation says it.","type":["string","null"]}},"required":["rule","pro_rata_share","pays","short_by","sharing","shelter_value","lowers_check_before_gift","plain"],"additionalProperties":false},{"type":"null"}],"description":"Only when profile.livesInAnothersHousehold is true: her place in that household for the payment month (POMS SI 00835.160, 20 CFR 416.1131 and 416.1133). Null otherwise."},"savings_on_next_first":{"type":"number","description":"Deprecated, kept for version 1: resources_after_gift.countable.","deprecated":true},"over_savings_limit":{"type":"boolean","description":"Deprecated, kept for version 1: resources_after_gift.over, for the 1st of the month after the gift.","deprecated":true},"able_balance_on_next_first":{"type":"number","description":"Deprecated, kept for version 1: resources_after_gift.able_balance.","deprecated":true},"resource_status":{"type":"string","enum":["under","able_suspension","excess"],"description":"Deprecated, kept for version 1: resources_for_check.status, for the 1st of the payment month.","deprecated":true},"ambiguous":{"type":"boolean","description":"True when the rules leave room for doubt, for example whether a bill is a utility."},"ambiguity_reason":{"description":"Why, when ambiguous.","type":["string","null"]},"rule_ids":{"type":"array","items":{"type":"string"},"description":"The rules applied, from the rule table."},"citations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":["string","null"]}},"required":["id","title","url"],"additionalProperties":false},"description":"The regulation or POMS section behind each rule."},"explanation":{"type":"object","properties":{"plain":{"type":"string"},"technical":{"type":"string"}},"required":["plain","technical"],"additionalProperties":false,"description":"The answer in plain words, and with the numbers."},"trace":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The month's arithmetic, step by step."}},"required":["check_before","check_after","counted_amount","income_month","payment_month","best_route","check_with_best_route","routes","resources_after_gift","resources_for_check","household","savings_on_next_first","over_savings_limit","able_balance_on_next_first","resource_status","ambiguous","ambiguity_reason","rule_ids","citations","explanation","trace"],"additionalProperties":false},"Envelope":{"type":"object","properties":{"data":{"description":"The answer. Null on error."},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"version":{"type":"string"},"rules_version":{"type":"string"},"latency_ms":{"type":"integer"}}},"error":{"$ref":"#/components/schemas/Error"}}},"Error":{"type":["object","null"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","not_found","rate_limited","upstream_unavailable","internal"]},"message":{"type":"string","description":"A plain sentence you can show to people."},"docs":{"type":"string"},"details":{}}}},"responses":{"Error":{"description":"An error, with a plain message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"RateLimited":{"description":"Too many requests. Retry after the number of seconds in Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}}