{"openapi":"3.0.3","info":{"title":"Emily API","version":"1.0.0","description":"Family-scoped structured data for servers, scripts, and automation tools. API access is included in the family plan. Create a key in Settings → Developer API. Chat, photos, billing, and family administration are outside v1."},"servers":[{"url":"/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/family":{"get":{"summary":"Read the connected family","description":"","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"family":{"$ref":"#/components/schemas/Family"}},"required":["family"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/members":{"get":{"summary":"List family members","description":"Use membership IDs for payerMembershipId. Member emails are not exposed.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/Member"}}},"required":["members"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/categories":{"get":{"summary":"List categories","description":"","parameters":[{"name":"includeArchived","in":"query","schema":{"type":"boolean","default":false},"description":""}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}},"required":["categories"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rates":{"get":{"summary":"Read exchange rates","description":"Rates from the family currency into currencies used by this family. Read-only; expense fxRate uses the opposite direction, into the family currency.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rates"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses":{"get":{"summary":"List expenses and income","description":"Newest occurredOn first, then createdAt and ID. count is the filtered record count; total is net money in the family currency, excluding unconverted records. Paginate with limit/offset until offset + expenses.length >= count. The list is live; changes between requests can move records.","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Inclusive start date."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Inclusive end date."},{"name":"categoryId","in":"query","schema":{"type":"string"},"description":""},{"name":"memberId","in":"query","schema":{"type":"string"},"description":"Filter by payer membership ID."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search description and merchant."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":""},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0},"description":""}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"expenses":{"type":"array","items":{"$ref":"#/components/schemas/Expense"}},"count":{"type":"integer"},"total":{"type":"integer"},"unconverted":{"$ref":"#/components/schemas/Unconverted"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Record an expense or income","description":"","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseCreate"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"expense":{"$ref":"#/components/schemas/Expense"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["expense","warnings"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/{expenseId}":{"parameters":[{"name":"expenseId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read a ledger entry","description":"","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"expense":{"$ref":"#/components/schemas/Expense"}},"required":["expense"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Edit a ledger entry","description":"Only supplied fields change. Currency/amount changes use Emily’s normal conversion rules.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpensePatch"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"expense":{"$ref":"#/components/schemas/Expense"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["expense","warnings"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Remove a ledger entry","description":"Soft-deletes the record.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events":{"get":{"summary":"List calendar occurrences","description":"Returns occurrences with eventId, rather than event series. Defaults to today through 90 days ahead; includePast also includes 90 days back. At most 366 occurrences per series. If truncated is true, use smaller date windows. Times have no time-zone conversion.","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Inclusive start date."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Inclusive end date."},{"name":"q","in":"query","schema":{"type":"string"},"description":""},{"name":"kind","in":"query","schema":{"type":"string","enum":["birthday","anniversary","appointment","school","trip","celebration","reminder","other"],"default":"other"},"description":""},{"name":"includePast","in":"query","schema":{"type":"boolean","default":false},"description":""},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":200},"description":""}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/Occurrence"}},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"truncated":{"type":"boolean"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a calendar event","description":"","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventCreate"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"$ref":"#/components/schemas/Event"}},"required":["event"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events/{eventId}":{"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read an event series","description":"","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"$ref":"#/components/schemas/Event"}},"required":["event"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Edit an event series","description":"Edits the whole series, including recurring events.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventPatch"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"$ref":"#/components/schemas/Event"}},"required":["event"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Remove an event series","description":"","responses":{"204":{"description":"Deleted; no response body"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/budgets":{"get":{"summary":"Read budgets and spending progress","description":"","parameters":[{"name":"period","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"description":"Report month, YYYY-MM; defaults to the current UTC month."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"budgets":{"type":"array","items":{"$ref":"#/components/schemas/Budget"}},"currency":{"type":"string"},"period":{"type":"string"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Create or update a budget","description":"Upsert by categoryId + period: one whole-family or category budget for each weekly/monthly/yearly period. Read results are converted to family currency.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetInput"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"budget":{"$ref":"#/components/schemas/Budget"}},"required":["budget"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/budgets/{budgetId}":{"parameters":[{"name":"budgetId","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Delete a budget","description":"","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/summary":{"get":{"summary":"Read spending and income summaries","description":"Defaults to the current UTC calendar month. Unconverted entries are excluded from family-currency totals and reported separately.","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Inclusive start date."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Inclusive end date."},{"name":"fields","in":"query","schema":{"type":"string"},"description":"Comma-separated subset: totals,byCategory,byMember,byMonth,byDay,unconverted. Defaults to all."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Summary"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Family subscription requires attention","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key cannot write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found in this family","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON content type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer emily_sk_…; one family per key. Access is read or read_write."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request","unauthorized","payment_required","forbidden","not_found","conflict","payload_too_large","unsupported_media_type","rate_limited","server_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Ok":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]},"Family":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"defaultCurrency":{"type":"string"},"locale":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"Member":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"emoji":{"type":"string"},"color":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member"]},"joinedAt":{"type":"string"}}},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"},"color":{"type":"string"},"sortOrder":{"type":"integer"},"archived":{"type":"boolean"}}},"ExpenseCreate":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":-1000000000000000,"maximum":1000000000000000,"description":"Non-zero integer minor units. Positive for an expense; negative for income."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Defaults to the family currency."},"occurredOn":{"type":"string","format":"date","description":"Defaults to today in UTC."},"description":{"type":"string","maxLength":200},"merchant":{"type":"string","maxLength":120,"nullable":true},"categoryId":{"type":"string","nullable":true,"description":"Category in this family. Income defaults to the Income category."},"payerMembershipId":{"type":"string","description":"Defaults to the key creator’s membership."},"notes":{"type":"string","nullable":true,"maxLength":1000}},"required":["amountMinor"],"additionalProperties":false},"ExpensePatch":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":-1000000000000000,"maximum":1000000000000000,"description":"Non-zero integer minor units. Positive for an expense; negative for income."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Defaults to the family currency."},"occurredOn":{"type":"string","format":"date","description":"Defaults to today in UTC."},"description":{"type":"string","maxLength":200},"merchant":{"type":"string","maxLength":120,"nullable":true},"categoryId":{"type":"string","nullable":true,"description":"Category in this family. Income defaults to the Income category."},"payerMembershipId":{"type":"string","description":"Defaults to the key creator’s membership."},"notes":{"type":"string","nullable":true,"maxLength":1000}},"additionalProperties":false},"Expense":{"type":"object","properties":{"id":{"type":"string"},"occurredOn":{"type":"string","format":"date"},"amountMinor":{"type":"integer","minimum":-1000000000000000,"maximum":1000000000000000,"description":"Non-zero integer minor units. Positive for an expense; negative for income."},"currency":{"type":"string"},"amountDefaultMinor":{"type":"integer"},"fxRate":{"type":"number","nullable":true},"fxSource":{"type":"string","enum":["identity","manual","manual-inverse","auto","auto-inverse","none"]},"description":{"type":"string"},"merchant":{"type":"string","nullable":true},"category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"},"color":{"type":"string","nullable":true}},"nullable":true},"payer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"}},"nullable":true},"source":{"type":"string"},"status":{"type":"string"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string"},"createdBy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"nullable":true},"deletedAt":{"type":"string","nullable":true}}},"EventCreate":{"type":"object","properties":{"title":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":1000},"startsOn":{"type":"string","format":"date"},"startTime":{"type":"string","nullable":true,"description":"HH:MM, 24-hour time; null means all day."},"endsOn":{"type":"string","format":"date","nullable":true},"endTime":{"type":"string","nullable":true,"description":"HH:MM; requires a start time."},"location":{"type":"string","nullable":true,"maxLength":120},"kind":{"type":"string","enum":["birthday","anniversary","appointment","school","trip","celebration","reminder","other"],"default":"other"},"recurrence":{"type":"string","enum":["none","daily","weekly","monthly","yearly"],"default":"none"},"recurrenceUntil":{"type":"string","format":"date","nullable":true}},"required":["title","startsOn"],"additionalProperties":false},"EventPatch":{"type":"object","properties":{"title":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":1000},"startsOn":{"type":"string","format":"date"},"startTime":{"type":"string","nullable":true,"description":"HH:MM, 24-hour time; null means all day."},"endsOn":{"type":"string","format":"date","nullable":true},"endTime":{"type":"string","nullable":true,"description":"HH:MM; requires a start time."},"location":{"type":"string","nullable":true,"maxLength":120},"kind":{"type":"string","enum":["birthday","anniversary","appointment","school","trip","celebration","reminder","other"],"default":"other"},"recurrence":{"type":"string","enum":["none","daily","weekly","monthly","yearly"],"default":"none"},"recurrenceUntil":{"type":"string","format":"date","nullable":true}},"additionalProperties":false},"Event":{"type":"object","properties":{"title":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":1000},"startsOn":{"type":"string","format":"date"},"startTime":{"type":"string","nullable":true,"description":"HH:MM, 24-hour time; null means all day."},"endsOn":{"type":"string","format":"date","nullable":true},"endTime":{"type":"string","nullable":true,"description":"HH:MM; requires a start time."},"location":{"type":"string","nullable":true,"maxLength":120},"kind":{"type":"string","enum":["birthday","anniversary","appointment","school","trip","celebration","reminder","other"],"default":"other"},"recurrence":{"type":"string","enum":["none","daily","weekly","monthly","yearly"],"default":"none"},"recurrenceUntil":{"type":"string","format":"date","nullable":true},"id":{"type":"string"},"allDay":{"type":"boolean"},"emoji":{"type":"string"},"color":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"deletedAt":{"type":"string","nullable":true},"createdBy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"nullable":true}}},"Occurrence":{"type":"object","properties":{"title":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":1000},"startsOn":{"type":"string","format":"date"},"startTime":{"type":"string","nullable":true,"description":"HH:MM, 24-hour time; null means all day."},"endsOn":{"type":"string","format":"date","nullable":true},"endTime":{"type":"string","nullable":true,"description":"HH:MM; requires a start time."},"location":{"type":"string","nullable":true,"maxLength":120},"kind":{"type":"string","enum":["birthday","anniversary","appointment","school","trip","celebration","reminder","other"],"default":"other"},"recurrence":{"type":"string","enum":["none","daily","weekly","monthly","yearly"],"default":"none"},"recurrenceUntil":{"type":"string","format":"date","nullable":true},"eventId":{"type":"string"},"occurrenceOn":{"type":"string","format":"date"},"occurrenceEndsOn":{"type":"string","format":"date","nullable":true},"occurrenceIndex":{"type":"integer"},"recurring":{"type":"boolean"},"allDay":{"type":"boolean"},"emoji":{"type":"string"},"color":{"type":"string"}}},"BudgetInput":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":1,"maximum":1000000000000000,"description":"Positive integer minor units."},"categoryId":{"type":"string","nullable":true,"description":"null means a budget for the whole family."},"currency":{"type":"string","description":"Defaults to the family currency."},"period":{"type":"string","enum":["monthly","weekly","yearly"],"default":"monthly"}},"required":["amountMinor"],"additionalProperties":false},"Budget":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":1,"maximum":1000000000000000,"description":"Positive integer minor units."},"categoryId":{"type":"string","nullable":true,"description":"null means a budget for the whole family."},"currency":{"type":"string","description":"Defaults to the family currency."},"period":{"type":"string","enum":["monthly","weekly","yearly"],"default":"monthly"},"id":{"type":"string"},"categoryName":{"type":"string"},"emoji":{"type":"string"},"color":{"type":"string","nullable":true},"spentMinor":{"type":"integer"},"remainingMinor":{"type":"integer"},"percent":{"type":"integer"},"overBudget":{"type":"boolean"},"unconvertedCount":{"type":"integer"},"spentPeriod":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}}}},"Unconverted":{"type":"object","properties":{"count":{"type":"integer"},"byCurrency":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"amountMinor":{"type":"integer"},"count":{"type":"integer"}}}}}},"Rates":{"type":"object","properties":{"base":{"type":"string"},"source":{"type":"string"},"fetchedAt":{"type":"string","nullable":true},"rates":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"rate":{"type":"number","nullable":true},"source":{"type":"string"},"fetchedAt":{"type":"string","nullable":true}}}}}},"Summary":{"type":"object","properties":{"currency":{"type":"string"},"period":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"totals":{"type":"object","properties":{"count":{"type":"integer"},"amountMinor":{"type":"integer"},"expenseMinor":{"type":"integer"},"incomeMinor":{"type":"integer"}}},"byCategory":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"name":{"type":"string"},"emoji":{"type":"string"},"color":{"type":"string","nullable":true},"amountMinor":{"type":"integer"},"expenseMinor":{"type":"integer"},"incomeMinor":{"type":"integer"},"count":{"type":"integer"}}}},"byMember":{"type":"array","items":{"type":"object","properties":{"membershipId":{"type":"string","nullable":true},"name":{"type":"string"},"emoji":{"type":"string"},"paidMinor":{"type":"integer"},"count":{"type":"integer"}}}},"byMonth":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"amountMinor":{"type":"integer"},"count":{"type":"integer"}}}},"byDay":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"amountMinor":{"type":"integer"},"count":{"type":"integer"}}}},"unconverted":{"$ref":"#/components/schemas/Unconverted"}}}}}}