{"openapi":"3.1.0","info":{"title":"DemandAI Public API","version":"1.0.0","description":"Programmatic access to the DemandAI legal-document engines: settlement demand letters, case valuation, negotiation counter-offers, future-medical projections, and mortgage-servicer demand letters. All endpoints are JSON-only and authenticated with a `dl_` API key. Identifiers DETECTED in free-text inputs (names, emails, SSNs, account numbers, addresses) are pseudonymized in memory before reaching the AI and re-identified only on the finished output; requests with residual detected identifiers that cannot be fully tokenized are rejected with 422. Detection is automated and best-effort — supply party names in their dedicated fields so every occurrence tokenizes deterministically. The `piiProtected` response field reports whether any value was actually tokenized for that request.","contact":{"name":"DemandAI Support","url":"https://demandai.pro/help"}},"servers":[{"url":"https://demandai.pro/api/v1","description":"Production"},{"url":"http://localhost:3000/api/v1","description":"Local development"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"tags":[{"name":"Demand Letters","description":"Personal-injury and property demand generation"},{"name":"Case Value","description":"Pre-demand settlement-value prediction"},{"name":"Negotiation","description":"Counter-offer analysis and response letters"},{"name":"Future Medical","description":"Life-care / future-medical cost projection"},{"name":"Mortgage","description":"Mortgage-servicer default and demand correspondence"}],"paths":{"/demand-letters":{"post":{"tags":["Demand Letters"],"operationId":"createDemandLetter","summary":"Generate a settlement demand letter","description":"Runs the triple-check pipeline (draft, independent forensic damages audit, reconcile). Client and defendant names plus documentsText are pseudonymized before reaching the AI. Requires scope `documents:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemandLetterRequest"},"example":{"caseType":"personal-injury","clientName":"Jane Doe","defendantName":"John Roe","incidentDate":"2026-01-15","incidentLocation":"Intersection of 5th Ave & Main St, Columbus, OH","jurisdiction":"OH","documentsText":"--- DOCUMENT: er-bill.pdf ---\nGrant Medical Center ER visit 01/15/2026. CPT 99284: $1,850.00 ...","attorney":{"name":"Alex Counsel","firmName":"Counsel & Associates LLP","firmAddress":"100 Legal Way, Columbus, OH 43215","phone":"(614) 555-0100","email":"alex@counsel.law","barNumber":"OH-123456"}}}}},"responses":{"200":{"description":"Generated demand letter with audited figures.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemandLetterResponse"}}}},"400":{"description":"Invalid request — malformed JSON or missing/invalid fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, expired, or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key but insufficient scope, missing product access on the owning account, or an IP / user-agent restriction on the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"PII scrub incomplete — sensitive values in documentsText could not be fully tokenized. Supply the party names in their fields and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 50 generations per hour per key across all v1 endpoints (or the key’s own hourly/daily/monthly limit, whichever is lower), enforced per authenticated key. Repeated failed authentication from one IP is also limited. Includes Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/case-value":{"post":{"tags":["Case Value"],"operationId":"predictCaseValue","summary":"Predict a settlement-value range","description":"Returns a conservative low / expected / high settlement range with value drivers, risk factors, comparable basis, and full reasoning. Detected identifiers in caseSummary and injuries are pseudonymized before reaching the AI. Requires scope `case-value:read`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseValueRequest"},"example":{"caseSummary":"Rear-end collision at a stoplight. Client treated for cervical strain over 4 months (PT + injections). Defendant cited for failure to stop.","jurisdiction":"TX","injuries":"Cervical strain, lumbar sprain, post-concussive headaches","medicalSpecials":28500,"liability":"clear"}}}},"responses":{"200":{"description":"Predicted settlement-value range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseValueResponse"}}}},"400":{"description":"Invalid request — malformed JSON or missing/invalid fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, expired, or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key but insufficient scope, missing product access on the owning account, or an IP / user-agent restriction on the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"PII scrub incomplete — detected identifiers could not be fully tokenized, so generation was blocked. Remove or field-supply the identifiers and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 50 generations per hour per key across all v1 endpoints (or the key’s own hourly/daily/monthly limit, whichever is lower), enforced per authenticated key. Repeated failed authentication from one IP is also limited. Includes Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/negotiation":{"post":{"tags":["Negotiation"],"operationId":"generateCounterOffer","summary":"Analyze an insurer offer and draft the counter-offer response","description":"Structured adequacy analysis (offerRatio is recomputed deterministically) plus a ready-to-send counter-offer response letter. Detected identifiers in caseSummary and insurer are pseudonymized before reaching the AI. Requires scope `negotiation:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NegotiationRequest"},"example":{"demandAmount":250000,"offerAmount":62500,"caseSummary":"Clear-liability rear-end collision; $48k documented specials; ongoing PT; demand sent 30 days ago.","insurer":"Acme Mutual"}}}},"responses":{"200":{"description":"Offer analysis and counter-offer response letter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NegotiationResponse"}}}},"400":{"description":"Invalid request — malformed JSON or missing/invalid fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, expired, or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key but insufficient scope, missing product access on the owning account, or an IP / user-agent restriction on the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"PII scrub incomplete — detected identifiers could not be fully tokenized, so generation was blocked. Remove or field-supply the identifiers and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 50 generations per hour per key across all v1 endpoints (or the key’s own hourly/daily/monthly limit, whichever is lower), enforced per authenticated key. Repeated failed authentication from one IP is also limited. Includes Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/future-medical":{"post":{"tags":["Future Medical"],"operationId":"projectFutureMedical","summary":"Project future / life-care medical costs","description":"Itemized future-treatment line items with deterministic arithmetic (totalCost = annualCost x durationYears; grand total is the exact sum). Detected identifiers in injuries, prognosis, and currentTreatment are pseudonymized before reaching the AI. Requires scope `future-medical:read`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FutureMedicalRequest"},"example":{"injuries":"L4-L5 disc herniation with radiculopathy, status post microdiscectomy","prognosis":"Permanent lifting restriction; likely future fusion within 10-15 years","claimantAge":42,"currentTreatment":"PT twice weekly; epidural steroid injections quarterly","jurisdiction":"FL"}}}},"responses":{"200":{"description":"Itemized future-medical projection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FutureMedicalResponse"}}}},"400":{"description":"Invalid request — malformed JSON or missing/invalid fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, expired, or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key but insufficient scope, missing product access on the owning account, or an IP / user-agent restriction on the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"PII scrub incomplete — detected identifiers could not be fully tokenized, so generation was blocked. Remove or field-supply the identifiers and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 50 generations per hour per key across all v1 endpoints (or the key’s own hourly/daily/monthly limit, whichever is lower), enforced per authenticated key. Repeated failed authentication from one IP is also limited. Includes Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mortgage-demand":{"post":{"tags":["Mortgage"],"operationId":"createMortgageDemand","summary":"Generate a mortgage-servicer demand / notice letter","description":"Drafts servicer correspondence (default notice, acceleration, reinstatement, payoff, FDCPA validation, or general demand) with FDCPA/RESPA compliance guardrails and an independent figures audit. Loan numbers, borrower names, and documentsText are pseudonymized before reaching the AI. Every letter is a DRAFT for compliance review. Requires scope `mortgage:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MortgageDemandRequest"},"example":{"letterType":"default-notice","servicer":"First Example Servicing LLC","borrowerName":"Jane Q. Borrower","loanNumber":"0012345678","propertyAddress":"12 Elm St, Dayton, OH 45402","defaultDate":"2026-03-01","totalArrears":"8420.55","perDiem":"21.40","jurisdiction":"OH","documentsText":"--- DOCUMENT: payment-history.pdf ---\nLoan 0012345678. Missed P&I Mar-Jun 2026: 4 x $1,980.14 ..."}}}},"responses":{"200":{"description":"Generated mortgage letter with audited figures.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MortgageDemandResponse"}}}},"400":{"description":"Invalid request — malformed JSON or missing/invalid fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, expired, or inactive API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key but insufficient scope, missing product access on the owning account, or an IP / user-agent restriction on the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"PII scrub incomplete — sensitive borrower values in documentsText could not be fully tokenized. Supply borrowerName / coBorrowerName and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 50 generations per hour per key across all v1 endpoints (or the key’s own hourly/daily/monthly limit, whichever is lower), enforced per authenticated key. Repeated failed authentication from one IP is also limited. Includes Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"DemandAI API key in the Authorization header: `Authorization: Bearer dl_...`. Create keys in the dashboard under Settings → API Keys."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative to bearer auth: the same `dl_` key in the X-API-Key header."}},"schemas":{"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Short machine-stable error category."},"message":{"type":"string","description":"Human-readable explanation of the failure."}}},"DemandLetterRequest":{"type":"object","required":["clientName"],"properties":{"caseType":{"type":"string","enum":["personal-injury","property"],"default":"personal-injury","description":"personal-injury runs the premium attorney pipeline; property runs the standard homeowner pipeline."},"clientName":{"type":"string","description":"Claimant name (pseudonymized before the AI)."},"defendantName":{"type":"string"},"incidentDate":{"type":"string","description":"ISO date; drives the statute-of-limitations check."},"incidentLocation":{"type":"string"},"jurisdiction":{"type":"string","description":"US state (name or 2-letter code)."},"documentsText":{"type":"string","maxLength":800000,"description":"Pre-extracted text of the source documents (medical records, bills, police reports). Pseudonymized before the AI."},"attorney":{"type":"object","description":"Sender letterhead / signature block details.","properties":{"name":{"type":"string"},"firmName":{"type":"string"},"firmAddress":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"barNumber":{"type":"string"}}}}},"DemandLetterResponse":{"type":"object","properties":{"success":{"type":"boolean"},"letter":{"type":"string","description":"The complete demand letter (re-identified)."},"demandAmount":{"type":"number","description":"Final settlement demand in dollars."},"figures":{"type":"object","properties":{"medicalExpenses":{"type":"number"},"economicDamages":{"type":"number"},"nonEconomicDamages":{"type":"number"},"multiplier":{"type":["number","null"]},"punitiveDamages":{"type":"number"}}},"audit":{"type":"object","description":"Independent forensic-audit outcome.","properties":{"completed":{"type":"boolean"},"mathVerified":{"type":"boolean"},"corrected":{"type":"boolean","description":"Whether a reconcile pass rewrote the letter."},"discrepancies":{"type":"array","items":{"type":"string"}}}},"caseStrength":{"type":"string"},"confidence":{"type":"number"},"demandStrength":{"type":"number","description":"0-100 transparency score."},"strengthLabel":{"type":"string"},"statuteOfLimitations":{"type":["object","null"],"description":"SOL assessment when jurisdiction + incidentDate allow one."},"piiProtected":{"type":"boolean","description":"True when at least one detected identifier was tokenized before the AI call for this request; false when detection found nothing to tokenize."},"modelUsed":{"type":"string"},"processingTimeMs":{"type":"number"},"timestamp":{"type":"string"}}},"CaseValueRequest":{"type":"object","required":["caseSummary"],"properties":{"caseSummary":{"type":"string"},"jurisdiction":{"type":"string"},"injuries":{"type":"string"},"medicalSpecials":{"type":"number","description":"Documented medical specials in dollars."},"liability":{"type":"string","enum":["clear","disputed","shared"]}}},"CaseValueResponse":{"type":"object","properties":{"success":{"type":"boolean"},"prediction":{"type":"object","properties":{"low":{"type":"number"},"expected":{"type":"number"},"high":{"type":"number"},"confidence":{"type":"number"},"valueDrivers":{"type":"array","items":{"type":"string"}},"riskFactors":{"type":"array","items":{"type":"string"}},"comparableBasis":{"type":"string"},"reasoning":{"type":"string"}}},"piiProtected":{"type":"boolean","description":"True when at least one detected identifier was tokenized before the AI call for this request."},"modelUsed":{"type":"string"},"processingTimeMs":{"type":"number"},"timestamp":{"type":"string"}}},"NegotiationRequest":{"type":"object","required":["demandAmount","offerAmount","caseSummary"],"properties":{"demandAmount":{"type":"number","exclusiveMinimum":0},"offerAmount":{"type":"number","minimum":0},"caseSummary":{"type":"string"},"insurer":{"type":"string"}}},"NegotiationResponse":{"type":"object","properties":{"success":{"type":"boolean"},"analysis":{"type":"object","properties":{"offerAmount":{"type":"number"},"demandAmount":{"type":"number"},"offerRatio":{"type":"number","description":"offerAmount / demandAmount (deterministic)."},"adequacy":{"type":"string","enum":["lowball","below-market","reasonable","strong"]},"recommendation":{"type":"string","enum":["accept","counter","reject"]},"suggestedCounter":{"type":"number"},"leveragePoints":{"type":"array","items":{"type":"string"}},"reasoning":{"type":"string"}}},"responseLetter":{"type":"string"},"piiProtected":{"type":"boolean","description":"True when at least one detected identifier was tokenized before the AI call for this request."},"modelUsed":{"type":"string"},"processingTimeMs":{"type":"number"},"timestamp":{"type":"string"}}},"FutureMedicalRequest":{"type":"object","required":["injuries"],"properties":{"injuries":{"type":"string"},"prognosis":{"type":"string"},"claimantAge":{"type":"number","exclusiveMinimum":0,"exclusiveMaximum":130},"currentTreatment":{"type":"string"},"jurisdiction":{"type":"string"}}},"FutureMedicalResponse":{"type":"object","properties":{"success":{"type":"boolean"},"projection":{"type":"object","properties":{"lineItems":{"type":"array","items":{"type":"object","properties":{"treatment":{"type":"string"},"frequency":{"type":"string"},"durationYears":{"type":"number"},"annualCost":{"type":"number"},"totalCost":{"type":"number"}}}},"totalFutureMedical":{"type":"number"},"lifeCareSummary":{"type":"string"},"assumptions":{"type":"array","items":{"type":"string"}},"confidence":{"type":"number"}}},"piiProtected":{"type":"boolean","description":"True when at least one detected identifier was tokenized before the AI call for this request."},"modelUsed":{"type":"string"},"processingTimeMs":{"type":"number"},"timestamp":{"type":"string"}}},"MortgageDemandRequest":{"type":"object","properties":{"letterType":{"type":"string","enum":["default-notice","acceleration","reinstatement-demand","payoff-demand","fdcpa-validation","general-demand"],"default":"default-notice"},"servicer":{"type":"string","description":"Servicer / sender name (letterhead)."},"borrowerName":{"type":"string"},"coBorrowerName":{"type":"string"},"loanNumber":{"type":"string"},"propertyAddress":{"type":"string"},"defaultDate":{"type":"string"},"totalArrears":{"type":["string","number"]},"perDiem":{"type":["string","number"]},"reinstatementAmount":{"type":["string","number"]},"payoffAmount":{"type":["string","number"]},"investor":{"type":"string"},"jurisdiction":{"type":"string"},"documentsText":{"type":"string","maxLength":800000}},"description":"At least one of documentsText, borrowerName, loanNumber, or totalArrears is required."},"MortgageDemandResponse":{"type":"object","properties":{"success":{"type":"boolean"},"letter":{"type":"string","description":"DRAFT letter for compliance/legal review (re-identified)."},"figures":{"type":"object","properties":{"totalArrears":{"type":"number"},"perDiem":{"type":"number"},"reinstatementAmount":{"type":"number"},"payoffAmount":{"type":"number"},"lateFees":{"type":"number"}}},"figuresVerified":{"type":"boolean"},"auditCompleted":{"type":"boolean"},"letterType":{"type":"string"},"discrepancies":{"type":"array","items":{"type":"string"}},"piiProtected":{"type":"boolean","description":"True when at least one detected identifier was tokenized before the AI call for this request; false when detection found nothing to tokenize."},"modelUsed":{"type":"string"},"processingTimeMs":{"type":"number"},"timestamp":{"type":"string"}}}}}}