{"openapi":"3.0.3","info":{"title":"Lien Deadline API","version":"0.1.0"},"paths":{"/api/v1/calculate-deadline":{"post":{"tags":["calculations"],"summary":"Calculate lien and notice deadlines for one invoice","description":"This is the primary buyer-facing endpoint. Send one invoice payload and get back the two most important operational dates: preliminary notice and lien filing deadlines, plus day counts you can use to trigger reminders in a project workflow.","operationId":"calculate_deadline_api_v1_calculate_deadline_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculationRequest"},"example":{"state":"CA","invoice_date":"2025-01-15","role":"supplier","project_type":"commercial"},"examples":{"supplier-commercial-ca":{"summary":"Supplier in California","value":{"state":"CA","invoice_date":"2025-01-15","role":"supplier","project_type":"commercial","notice_date":"2025-01-20"}},"subcontractor-commercial-tx":{"summary":"Subcontractor in Texas","value":{"state":"TX","invoice_date":"2025-01-15","role":"subcontractor","project_type":"commercial"}}}}},"required":true},"responses":{"200":{"description":"Deadline projection with concrete dates and day counters for closeout planning.","content":{"application/json":{"schema":{},"examples":{"success-response":{"summary":"Commercial supplier result (success path)","value":{"status":"success","state":"CA","invoice_date":"2025-01-15","project_type":"commercial","preliminary_notice_deadline":"2025-02-04","lien_deadline":"2025-06-30","prelim_deadline_days":20,"lien_deadline_days":165,"preliminary_notice":{"required":true,"deadline":"2025-02-04","days_from_now":20},"lien_filing":{"deadline":"2025-06-30","days_from_now":165},"warnings":["Notice-of-completion filing can shorten a timeline."]}}}}}},"422":{"description":"Invalid request body for schema validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"},"examples":{"bad-state":{"summary":"State code does not match format","value":{"detail":[{"loc":["body","state"],"msg":"string pattern failed"}]}}}}}},"400":{"description":"Bad request: payload or date format is invalid.","content":{"application/json":{"examples":{"invalid-date":{"summary":"Invalid invoice_date format","value":{"error":"Invalid invoice_date format"}}}}}},"500":{"description":"Calculation engine failed to evaluate the request.","content":{"application/json":{"example":{"error":"Calculation failed"}}}}},"x-demo-scope":"primary-business"}},"/api/v1/supported-states":{"get":{"tags":["calculations"],"summary":"List supported states","description":"Returns the exact states supported by the calculation engine. Use this before you let an invoice flow continue, so your users cannot choose unsupported jurisdictions.","operationId":"get_supported_states_api_v1_supported_states_get","responses":{"200":{"description":"Supported states payload for pre-validation and UI guidance.","content":{"application/json":{"schema":{},"examples":{"success-response":{"summary":"Supported state list","value":{"status":"success","states":["CA","TX","NY","FL"],"count":4}}}}}},"500":{"description":"Failed to read supported state configuration.","content":{"application/json":{"example":{"detail":"Unable to load state list"}}}}},"x-demo-scope":"preflight"}},"/api/v1/state-guides":{"get":{"tags":["state-guides"],"summary":"List available state guides","description":"Returns published state guides used when operations need a human-readable reference. Use include_drafts=true only for admin workflows and internal operations.","operationId":"list_state_guides_api_v1_state_guides_get","parameters":[{"name":"include_drafts","in":"query","required":false,"schema":{"type":"boolean","description":"When true, include draft guides in addition to published guides. Requires editor credentials via the API key header.","examples":{"published_only":{"summary":"Published guides only","value":false},"include_drafts":{"summary":"Include draft guides","value":true}},"default":false,"title":"Include Drafts"},"description":"When true, include draft guides in addition to published guides. Requires editor credentials via the API key header."}],"responses":{"200":{"description":"State guide list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateGuidesListResponse"},"example":{"states":[{"state_code":"CA","title":"California - Lien Notice Requirements","slug":"california-lien-notice","status":"published","updated_at":"2025-01-15T09:00:00Z"},{"state_code":"TX","title":"Texas - Preliminary Notice and Lien Filing","slug":"texas-lien-guide","status":"published","updated_at":"2025-01-10T10:30:00Z"}]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-demo-scope":"sales-context"}},"/api/v1/state-guides/index":{"get":{"tags":["state-guides"],"summary":"List published state guide index","description":"Returns a compact, UI-friendly index for fast state lookups when routing invoices before deep-loading guide details.","operationId":"list_state_guides_index_api_v1_state_guides_index_get","responses":{"200":{"description":"Published state guide index payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateGuidesIndexResponse"},"example":{"states":[{"state_code":"CA","title":"California - Lien Notice Requirements","slug":"california-lien-notice"},{"state_code":"TX","title":"Texas Mechanics Lien Guide","slug":"texas-mechanics-lien"}]}}}}},"x-demo-scope":"sales-context"}},"/api/v1/state-guides/{state_code}":{"get":{"tags":["state-guides"],"summary":"Get state guide payload by state","description":"Returns the published guide used by the calculator for one state. Use this before notices are sent so closeout checks align with local rules.","operationId":"get_state_guide_api_v1_state_guides__state_code__get","parameters":[{"name":"state_code","in":"path","required":true,"schema":{"type":"string","title":"State Code"}},{"name":"include_drafts","in":"query","required":false,"schema":{"type":"boolean","description":"Return draft data when true. Requires editor credentials.","examples":{"published_only":{"summary":"Published guide only","value":false},"include_drafts":{"summary":"Include draft versions","value":true}},"default":false,"title":"Include Drafts"},"description":"Return draft data when true. Requires editor credentials."}],"responses":{"200":{"description":"State guide payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateGuidePublicPayloadResponse"},"example":{"state_code":"CA","title":"California mechanics lien guide","slug":"california-mechanics-lien","status":"published","intro_html":"

Intro summary for California.

","high_risk_html":"

High-Risk Scenario

High-risk timing details.

","deadlines_html":"

Deadlines

Key filing deadlines are below.

","mistakes_html":"

Mistakes

Common mistakes to avoid.

","cta_html":"

Not sure which deadline applies?

Use our calculator.

","faq_html":"

FAQ

Frequently asked questions.

","disclaimer_html":"

Informational only.

","rule_payload":{"preliminary_notice":{"required":true,"days":20},"lien_filing":{"required":true,"days":90}},"published_at":"2025-01-01T10:00:00Z"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"Guide not found","content":{"application/json":{"example":{"detail":"State guide not found"}}}}},"x-demo-scope":"operational-context"}},"/api/v1/state-guides/{state_code}/calculator-payload":{"get":{"tags":["state-guides"],"summary":"Get calculator payload for a state","description":"Returns the normalized payload consumed by the calculation engine. This is an internal/partner-facing integration view for rule-level behavior.","operationId":"get_state_guide_calculator_payload_api_v1_state_guides__state_code__calculator_payload_get","parameters":[{"name":"state_code","in":"path","required":true,"schema":{"type":"string","title":"State Code"}}],"responses":{"200":{"description":"State guide calculator payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateGuideCalculatorPayloadResponse"},"example":{"state_code":"CA","state_name":"California","status":"published","rule_payload":{"preliminary_notice":{"required":true,"days":20,"when":"Notice of completion filed may alter deadline."},"lien_filing":{"days":90,"required":true}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"Calculator payload missing","content":{"application/json":{"example":{"detail":"State guide payload not found"}}}}},"x-demo-scope":"technical-internal"}}},"components":{"schemas":{"CalculationRequest":{"properties":{"state":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Za-z]{2}$","title":"State","description":"Two-letter US state code used to select the lien deadline rule set","examples":["CA","TX"]},"invoice_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"Invoice Date","description":"Date used for all deadlines, in YYYY-MM-DD format","examples":["2025-01-15"]},"project_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Type","description":"Business context used by state rules. Use 'commercial' or 'residential'; common variants will be normalized.","default":"commercial","examples":["commercial","residential","commercial (default)"]},"notice_date":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"Notice Date","description":"Optional notice-of-completion date in YYYY-MM-DD for closer-term deadlines.","examples":["2025-01-21"]},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role","description":"Business role that submits notices in your workflow.","default":"supplier","examples":["supplier","contractor","subcontractor"]}},"type":"object","required":["state","invoice_date"],"title":"CalculationRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"StateGuideCalculatorPayloadResponse":{"properties":{"state_code":{"type":"string","title":"State Code"},"state_name":{"type":"string","title":"State Name"},"status":{"type":"string","enum":["draft","published"],"title":"Status"},"rule_payload":{"additionalProperties":true,"type":"object","title":"Rule Payload"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["state_code","state_name","status"],"title":"StateGuideCalculatorPayloadResponse"},"StateGuideIndexItem":{"properties":{"state_code":{"type":"string","title":"State Code"},"title":{"type":"string","title":"Title"},"slug":{"type":"string","title":"Slug"},"selector_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selector Description"}},"type":"object","required":["state_code","title","slug"],"title":"StateGuideIndexItem"},"StateGuideListItem":{"properties":{"state_code":{"type":"string","title":"State Code"},"title":{"type":"string","title":"Title"},"slug":{"type":"string","title":"Slug"},"selector_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selector Description"},"status":{"type":"string","enum":["draft","published"],"title":"Status"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["state_code","title","slug","status"],"title":"StateGuideListItem"},"StateGuidePublicPayloadResponse":{"properties":{"state_code":{"type":"string","title":"State Code"},"title":{"type":"string","title":"Title"},"slug":{"type":"string","title":"Slug"},"status":{"type":"string","enum":["draft","published"],"title":"Status"},"selector_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selector Description"},"intro_html":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Intro Html"},"high_risk_html":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"High Risk Html"},"deadlines_html":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deadlines Html"},"mistakes_html":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mistakes Html"},"cta_html":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cta Html"},"faq_html":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Faq Html"},"faq_json":{"anyOf":[{},{"type":"null"}],"title":"Faq Json"},"deadlines_rows_json":{"anyOf":[{},{"type":"null"}],"title":"Deadlines Rows Json"},"mistakes_json":{"anyOf":[{},{"type":"null"}],"title":"Mistakes Json"},"disclaimer_html":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Disclaimer Html"},"sections_json":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Sections Json"},"rule_payload":{"additionalProperties":true,"type":"object","title":"Rule Payload"},"seo_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Seo Title"},"seo_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Seo Description"},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published At"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By"},"updated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated By"}},"type":"object","required":["state_code","title","slug","status"],"title":"StateGuidePublicPayloadResponse"},"StateGuidesIndexResponse":{"properties":{"states":{"items":{"$ref":"#/components/schemas/StateGuideIndexItem"},"type":"array","title":"States"}},"type":"object","required":["states"],"title":"StateGuidesIndexResponse"},"StateGuidesListResponse":{"properties":{"states":{"items":{"$ref":"#/components/schemas/StateGuideListItem"},"type":"array","title":"States"}},"type":"object","required":["states"],"title":"StateGuidesListResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}