{"openapi":"3.1.0","info":{"title":"NaturoMedica Agent Front Door","version":"1.0.0","description":"Research public sources before calling. No live calendar or automatic booking. Patient-specific replies are explicitly approved by staff. Actual booking times require a live attendant at 425-557-8900."},"servers":[{"url":"/api/naturomedica/agent","description":"Same-origin NaturoMedica agent service"}],"components":{"securitySchemes":{"requestToken":{"type":"http","scheme":"bearer","description":"Private 64-character token returned on submission. Never place in URL/query."}},"schemas":{"SchedulingRequest":{"type":"object","additionalProperties":false,"required":["requestKey","patientName","patientEmail","patientPhone","appointmentType","availabilityPreferences","consent"],"properties":{"requestKey":{"type":"string","format":"uuid","description":"Generate once per request and reuse unchanged on network retries. Never reuse for different details."},"patientName":{"type":"string","maxLength":200},"patientEmail":{"type":"string","format":"email","maxLength":200},"patientPhone":{"type":"string","minLength":7,"maxLength":40},"appointmentType":{"type":"string","enum":["new_patient","existing_patient"]},"providerPreference":{"type":"string","maxLength":200},"availabilityPreferences":{"type":"string","maxLength":500,"description":"Scheduling preferences only; no symptoms or medical history. Washington/Pacific timezone."},"agentName":{"type":"string","maxLength":100},"consent":{"type":"boolean","enum":[true],"description":"Patient authorized this contact and minimal scheduling request."}}}}},"paths":{"/info":{"get":{"operationId":"getClinicAgentInfo","summary":"Instructions, policies and tool URLs","responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["name","policy","endpoints","phone"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"phone":{"type":"string"},"policy":{"type":"array","items":{"type":"string"}},"endpoints":{"type":"object","additionalProperties":{"type":"string"}},"staffScript":{"type":"string"},"corpusScope":{"type":"string"}}}}}},"400":{"description":"Invalid input or missing consent"},"429":{"description":"Rate limit; honor Retry-After"},"503":{"description":"Temporarily unavailable; retry submissions with the same requestKey"}}}},"/sources":{"get":{"operationId":"getClinicAgentSources","summary":"Read full published sources, or search across the whole corpus","parameters":[{"name":"query","in":"query","schema":{"type":"string","maxLength":300}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["sources","total","offset","nextOffset","refreshedAt"],"properties":{"sources":{"type":"array","items":{"type":"object","required":["id","title","url","category","content"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"category":{"type":"string"},"content":{"type":"string"},"updatedAt":{"type":["string","null"]}}}},"total":{"type":"integer"},"offset":{"type":"integer"},"nextOffset":{"type":["integer","null"]},"refreshedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid input or missing consent"},"429":{"description":"Rate limit; honor Retry-After"},"503":{"description":"Temporarily unavailable; retry submissions with the same requestKey"}}}},"/corpus.txt":{"get":{"operationId":"downloadClinicCorpus","summary":"Download full published clinic research corpus as text","responses":{"200":{"description":"Current public corpus","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/answer":{"post":{"operationId":"answerClinicAgentQuestion","summary":"Get cited published-source excerpts. No personalized medical advice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question"],"properties":{"question":{"type":"string","minLength":3,"maxLength":500}}}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["answer","sources","generatedAt","needsStaff"],"properties":{"answer":{"type":"string"},"sources":{"type":"array","items":{"type":"object","required":["id","title","url","category","content"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"category":{"type":"string"},"content":{"type":"string"},"updatedAt":{"type":["string","null"]}}}},"generatedAt":{"type":"string","format":"date-time"},"needsStaff":{"type":"boolean"}}}}}},"400":{"description":"Invalid input or missing consent"},"429":{"description":"Rate limit; honor Retry-After"},"503":{"description":"Temporarily unavailable; retry submissions with the same requestKey"}}}},"/requests":{"post":{"operationId":"submitClinicAgentRequest","summary":"Submit one authorized scheduling request into the clinic inquiry queue","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingRequest"}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["token","status","inquiryNumber","message"],"properties":{"token":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Private capability token: retain securely; use only as Authorization: Bearer."},"status":{"type":"string"},"inquiryNumber":{"type":"string"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid input or missing consent"},"429":{"description":"Rate limit; honor Retry-After"},"503":{"description":"Temporarily unavailable; retry submissions with the same requestKey"}}}},"/requests/status":{"get":{"operationId":"getClinicAgentRequestStatus","summary":"Read staff-approved reply only. Poll about every four hours; at most once per minute.","security":[{"requestToken":[]}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["status","reply","inquiryNumber","updatedAt","message"],"properties":{"status":{"type":"string","description":"pending, reviewing, needs_info, ready_to_call or declined. No status returned here confirms a booking."},"reply":{"type":["string","null"]},"inquiryNumber":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid input or missing consent"},"401":{"description":"Missing/invalid bearer token"},"404":{"description":"No request found"},"429":{"description":"Rate limit; honor Retry-After"},"503":{"description":"Temporarily unavailable; retry submissions with the same requestKey"}}}},"/requests/follow-up":{"post":{"operationId":"followUpClinicAgentRequest","summary":"Add minimal scheduling clarification to the same inquiry; at most five follow-ups","security":[{"requestToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["requestKey","message"],"properties":{"requestKey":{"type":"string","format":"uuid"},"message":{"type":"string","minLength":1,"maxLength":1000}}}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","required":["status","reply","inquiryNumber","updatedAt","message"],"properties":{"status":{"type":"string","description":"pending, reviewing, needs_info, ready_to_call or declined. No status returned here confirms a booking."},"reply":{"type":["string","null"]},"inquiryNumber":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid input or missing consent"},"429":{"description":"Rate limit; honor Retry-After"},"503":{"description":"Temporarily unavailable; retry submissions with the same requestKey"}}}}}}