{"openapi":"3.1.0","info":{"title":"TN.tax","version":"1.0.0","description":"Act for one property owner on their TN.tax account: properties, documents, appeal status and billing. Steps only the owner may take (signing, paying, turning on texts) come back as a link for the owner. See /llms.txt."},"servers":[{"url":"https://tn.tax"}],"security":[{"bearer":[]},{"oauth":["account"]}],"paths":{"/api/assistant/v1/get_account":{"post":{"operationId":"get_account","summary":"Account overview","description":"Start here. Who the account belongs to, how they get appeal updates, how many properties they have, what is waiting on them, what the owner lets this assistant do (sign, pay), and the owner's steps: which ones you can finish and which you hand back with request_owner_action.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/list_properties":{"post":{"operationId":"list_properties","summary":"List properties","description":"Every property on the account with its appeal status for one season, whether this season's authorization is signed, documents on file, and the to-dos for it. Each to-do says whether only the owner can do it.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"season":{"description":"Tax year, e.g. 2027. Defaults to the season being filed.","type":"string","pattern":"^\\d{4}$"}}}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/get_property":{"post":{"operationId":"get_property","summary":"Property detail","description":"One property: the county record we hold, the appeal checklist with what is done, and the history of past appeals with their results.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"property_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"season":{"type":"string","pattern":"^\\d{4}$"}},"required":["property_id"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/get_appeal_report":{"post":{"operationId":"get_appeal_report","summary":"Get a filed report","description":"A download link, good for five minutes, for the report TN.tax filed with the county for one appeal (appeal_id from get_property). Only appeals that have been filed have one.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"appeal_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["appeal_id"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/list_todos":{"post":{"operationId":"list_todos","summary":"What is waiting on the owner","description":"The owner's to-do list across all properties, most urgent first: the same list the portal home page shows. Do the ones you can with the other tools. For owner-only ones, give the owner the link from request_owner_action.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/list_documents":{"post":{"operationId":"list_documents","summary":"List documents","description":"Documents the owner (or you) uploaded as evidence or financials, optionally for one property. Signed authorizations and filed reports are not listed here; the owner sees those in the portal.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"property_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/get_billing":{"post":{"operationId":"get_billing","summary":"Billing","description":"Invoices and payment status: what is owed, what was paid, and the card on file (brand and last four digits only).","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/lookup_county_record":{"post":{"operationId":"lookup_county_record","summary":"Look up a county record","description":"The county assessor's record for an address: parcel id, appraised value (land, improvements, total), land use, acreage and last sale. Public data from the county roll. Covers the counties TN.tax files in.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","minLength":4,"maxLength":300,"description":"Street address, with city or ZIP if known."}},"required":["address"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/get_deadlines":{"post":{"operationId":"get_deadlines","summary":"Filing deadlines","description":"When each county's informal review window closes for the season being filed. A deadline marked provisional is our projection until the county confirms it.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/search_help":{"post":{"operationId":"search_help","summary":"Search TN.tax help","description":"Search TN.tax's help articles and how-tos: how informal reviews work, the fee, deadlines, what evidence helps, what happens after filing. Use it to answer the owner's questions in TN.tax's own words.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":2,"maxLength":200}},"required":["query"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/list_shares":{"post":{"operationId":"list_shares","summary":"Who else can see the account","description":"People the owner has invited to see the account or one property, and whether each may add documents. Inviting or removing someone is owner-only (request_owner_action with share_account).","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/add_property":{"post":{"operationId":"add_property","summary":"Add a property","description":"Add a property to the account by street address, with the city or ZIP. TN.tax looks it up on the county roll: on an exact match it saves the parcel and appraised value; otherwise it shows the nearest record so you can check with the owner.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","minLength":4,"maxLength":300},"nickname":{"type":"string","maxLength":80},"use":{"description":"What the property is: home, rental, commercial...","type":"string","enum":["primary_residence","second_home","rental","commercial"]}},"required":["address"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/update_property":{"post":{"operationId":"update_property","summary":"Update property details","description":"Record what a property is used for and who owns it on the county record: a person, or a company or trust (by company_id from list_companies, or by name) with the signer's title. For income property, the yearly gross rent. For commercial property, its type, rentable square feet and occupancy.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"property_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"use":{"type":"string","enum":["primary_residence","second_home","rental","commercial"]},"owner_type":{"type":"string","enum":["individual","entity"]},"company_id":{"description":"A company already on the account (list_companies).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"owner_name":{"description":"The company or trust on the deed, when owner_type is entity.","type":"string","maxLength":160},"entity_type":{"type":"string","enum":["llc","corporation","s_corp","partnership","trust","other"]},"signer_title":{"type":"string","maxLength":80},"annual_gross_rent_dollars":{"type":"integer","minimum":0,"maximum":100000000},"commercial_type":{"type":"string","enum":["office","medical_office","retail","strip_center","warehouse","industrial","restaurant","multifamily","hotel","special_purpose","land"]},"rentable_area_sqft":{"type":"number","exclusiveMinimum":0,"maximum":5000000},"occupancy_percent":{"description":"How full it is, 0 to 100.","type":"number","minimum":0,"maximum":100},"cost_segregation":{"description":"Whether a cost segregation study has been done.","type":"string","enum":["completed","not_done","unsure"]}},"required":["property_id"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/remove_property":{"post":{"operationId":"remove_property","summary":"Remove a property","description":"Take a property off the account: a mistyped address, or one added by mistake. Only for a property with no paperwork: no authorization signed and no appeal, this season or before.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"property_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["property_id"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/list_companies":{"post":{"operationId":"list_companies","summary":"List companies and trusts","description":"The companies and trusts the owner holds property through, with the legal name, the kind of entity and the signer's title. Use a company_id with update_property.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/save_company":{"post":{"operationId":"save_company","summary":"Add a company or trust","description":"Add a company or trust the owner holds property through, by its legal name as it appears on the deed. Adding one that is already on the list returns the existing one. Then name it on a property with update_property.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"legal_name":{"type":"string","minLength":2,"maxLength":160},"entity_type":{"type":"string","enum":["llc","corporation","s_corp","partnership","trust","other"]},"signer_title":{"description":"The title of the person who signs for it, e.g. Managing Member.","type":"string","maxLength":80}},"required":["legal_name"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/upload_document":{"post":{"operationId":"upload_document","summary":"Upload a document","description":"Attach evidence to a property's appeal: photos of needed repairs, contractor estimates, a closing statement, an appraisal, or (for income property, kind=financials) a rent roll and operating statements. PDF, JPG, PNG, HEIC or WebP, up to 15 MB.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"property_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"file_name":{"type":"string","minLength":1,"maxLength":200},"content_type":{"type":"string","enum":["application/pdf","image/jpeg","image/png","image/heic","image/webp"]},"content_base64":{"type":"string","minLength":4,"maxLength":20971528},"kind":{"default":"evidence","type":"string","enum":["evidence","financials"]},"note":{"description":"What the document shows, in a sentence.","type":"string","maxLength":500}},"required":["property_id","file_name","content_type","content_base64"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/create_upload_link":{"post":{"operationId":"create_upload_link","summary":"Make an upload link","description":"Make a link that adds documents to one property, for three days and up to 20 files, with no sign-in. Two uses. For the owner: their photos are on their phone, so give them page_url, or set send_to_owner and we email it to them (and text it if they chose texts).","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"property_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"kind":{"default":"evidence","description":"financials for a rent roll or operating statements.","type":"string","enum":["evidence","financials"]},"send_to_owner":{"default":false,"description":"Email the owner the link to open on their phone, and text it if they chose texts.","type":"boolean"}},"required":["property_id"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/get_document_link":{"post":{"operationId":"get_document_link","summary":"Open a document","description":"A download link, good for five minutes, for one document the owner uploaded (from list_documents). Use it to read a document the owner asks about.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"document_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["document_id"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/delete_document":{"post":{"operationId":"delete_document","summary":"Remove a document","description":"Remove a document the owner uploaded, such as a wrong file or a duplicate. It is deleted, not archived. Signed authorizations and filed reports cannot be removed.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"document_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["document_id"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/mark_checklist_step":{"post":{"operationId":"mark_checklist_step","summary":"Tick a checklist step","description":"Mark an owner step on a property's checklist done or not done: record_check (the county record has been checked for errors) or evidence (everything useful has been added). Signing and choosing a plan are owner-only; steps TN.tax performs cannot be ticked.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"property_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"step":{"type":"string","enum":["record_check","evidence"]},"done":{"type":"boolean"}},"required":["property_id","step","done"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/set_update_channel":{"post":{"operationId":"set_update_channel","summary":"Choose how updates arrive","description":"Set how the owner gets appeal updates: email, sms, both, or none. Receipts, bills and sign-in links always go by email. Texts are turned on by the phone's owner: if they are not on yet, use start_texts with the owner's mobile number, and texts begin when that phone replies YES.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["email","sms","both","none"]}},"required":["channel"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/update_profile":{"post":{"operationId":"update_profile","summary":"Update the owner's legal name","description":"Set the owner's full legal name, the name authorizations are prepared in. The owner confirms it when they sign.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"legal_name":{"type":"string","minLength":2,"maxLength":160}},"required":["legal_name"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/set_season_emails":{"post":{"operationId":"set_season_emails","summary":"Season news emails on or off","description":"Turn TN.tax's season emails on or off: when the filing window opens, deadline reminders and the like. Emails about the owner's own appeal, bills and sign-in are not affected. If the address bounced or reported spam, it cannot be turned back on here.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subscribed":{"type":"boolean"}},"required":["subscribed"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/send_message":{"post":{"operationId":"send_message","summary":"Message the TN.tax office","description":"Send a question or note to the TN.tax office. A person reads it and replies to the owner's email. Say it comes from the owner's assistant. Never include ID, bank or card numbers.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":4000}},"required":["message"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/get_authorization":{"post":{"operationId":"get_authorization","summary":"Read the authorization before signing","description":"The exact Letter of Authorization the owner would sign for one property this season: the full text, the fee rate, the season, who is bound, and an agreement_ref. Show the owner the key terms and ask before anyone signs.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"property_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"signer_name":{"description":"The owner's full legal name, as they sign. Defaults to the name on the account. For a company, the person signing for it.","type":"string","minLength":2,"maxLength":120},"use_type":{"description":"What the property is for. Sets the fee rate. Needed if the record does not say.","type":"string","enum":["primary_residence","second_home","rental","commercial"]},"owner_type":{"description":"Who is on the deed: the owner personally, or a company or trust.","type":"string","enum":["individual","entity"]},"owner_name":{"description":"The owner of record's name, for a company or trust.","type":"string","maxLength":160},"owner_entity_type":{"type":"string","enum":["llc","corporation","s_corp","partnership","trust","other"]},"signer_title":{"description":"The signer's title at the company, e.g. Managing Member.","type":"string","maxLength":80}},"required":["property_id"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/sign_authorization":{"post":{"operationId":"sign_authorization","summary":"Sign the authorization for the owner","description":"Sign one property's Letter of Authorization as the owner's electronic signature. Only when the owner turned on Sign for me for you in TN.tax, and only on the owner's clear instruction for this property.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"property_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"signer_name":{"description":"The owner's full legal name, as they sign. Defaults to the name on the account. For a company, the person signing for it.","type":"string","minLength":2,"maxLength":120},"use_type":{"description":"What the property is for. Sets the fee rate. Needed if the record does not say.","type":"string","enum":["primary_residence","second_home","rental","commercial"]},"owner_type":{"description":"Who is on the deed: the owner personally, or a company or trust.","type":"string","enum":["individual","entity"]},"owner_name":{"description":"The owner of record's name, for a company or trust.","type":"string","maxLength":160},"owner_entity_type":{"type":"string","enum":["llc","corporation","s_corp","partnership","trust","other"]},"signer_title":{"description":"The signer's title at the company, e.g. Managing Member.","type":"string","maxLength":80},"agreement_ref":{"type":"string","pattern":"^[0-9a-f]{24}$","description":"From get_authorization, with the same details."},"owner_instruction":{"type":"string","minLength":8,"maxLength":1000,"description":"What the owner told you, in their words, e.g. \"Yes, sign the authorization for 12 Oak St.\""},"terms_shown_to_owner":{"type":"boolean","const":true,"description":"True only if you showed the owner the key terms from get_authorization and they said to sign."}},"required":["property_id","agreement_ref","owner_instruction","terms_shown_to_owner"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/pay_invoice":{"post":{"operationId":"pay_invoice","summary":"Pay an open invoice","description":"Pay one of the owner's open TN.tax invoices, on the owner's instruction. Two ways: the owner's saved card, if they turned on Pay for me for you; or a Stripe shared payment token (spt_...) that the owner's wallet granted to TN.tax's Stripe profile (see get_billing) for at least the amount due.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_number":{"description":"From get_billing. Needed only when more than one invoice is open.","type":"string","maxLength":64},"shared_payment_token":{"description":"A Stripe shared payment token from the owner's wallet. Leave out to use the saved card.","type":"string","pattern":"^spt_[A-Za-z0-9_]{6,120}$"}}}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/start_texts":{"post":{"operationId":"start_texts","summary":"Start text updates","description":"Turn on appeal updates by text, on the owner's instruction. TN.tax texts the phone \"Reply YES to get texts\", and texts begin only when that phone replies YES: the consent has to come from the phone's owner. Use the owner's own mobile number, as they gave it to you.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string","minLength":10,"maxLength":20,"description":"The owner's US mobile number."}},"required":["phone"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/request_owner_action":{"post":{"operationId":"request_owner_action","summary":"Hand a step to the owner","description":"Hand one of the owner's steps back to them: sign_authorization (needs property_id; signing also confirms the plan), choose_plan_and_pay, pay_invoice, add_or_change_card, turn_on_texts, share_account, delete_my_data, change_email, identity_numbers.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["sign_authorization","choose_plan_and_pay","pay_invoice","add_or_change_card","turn_on_texts","share_account","delete_my_data","change_email","identity_numbers"]},"property_id":{"description":"Needed for sign_authorization, and for choose_plan_and_pay on one property.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"send_to_owner":{"default":false,"description":"Email the owner a link that finishes the step (a one-time signing link for a signature), and text it if they chose texts.","type":"boolean"}},"required":["action"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/api/assistant/v1/check_owner_action":{"post":{"operationId":"check_owner_action","summary":"Has the owner done it?","description":"Whether the owner has finished a step handed to them (a handoff_id from request_owner_action or create_upload_link): done, waiting, or unknown when TN.tax cannot tell. Read from the account itself, so it is right even if the owner did it another way.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handoff_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"From request_owner_action or create_upload_link."}},"required":["handoff_id"]}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A key the owner makes in TN.tax Settings (AI assistants), or an OAuth access token."},"oauth":{"type":"oauth2","description":"Authorization code with PKCE (S256). Register at /api/oauth/register.","flows":{"authorizationCode":{"authorizationUrl":"https://tn.tax/oauth/authorize","tokenUrl":"https://tn.tax/api/oauth/token","refreshUrl":"https://tn.tax/api/oauth/token","scopes":{"account":"Act on the owner's TN.tax account"}}}}},"responses":{"Problem":{"description":"Why the call did not go through, in words to relay to the owner.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"kind":{"type":"string","enum":["unknown","read_only","invalid","refused","error","unauthorized","rate_limited"]}},"required":["error"]}}}}}}}