{"openapi":"3.0.3","info":{"title":"Lumagen API","version":"v1","description":"Connect an EHR, a scheduling system or a lab interface to Lumagen. One base URL, two ways to authenticate, JSON in and out.","x-updated":"September 15, 2026"},"servers":[{"url":"https://www.lumagen.ai/api/v1"}],"security":[{"apiKey":[]},{"oauth":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An admin creates a key under Admin, API and integrations, picks its scopes and, for a health system with several sites, the sites it may reach. The key is shown once and hashed at rest. Send it as a bearer token."},"oauth":{"type":"oauth2","description":"For an integration service that should hold a client id and secret rather than a key. A client is created against an existing key and inherits its scopes, sites, environment and revocation. Exchange the credentials for an access token that lasts one hour, then send the token as a bearer.","flows":{"clientCredentials":{"tokenUrl":"https://www.lumagen.ai/api/v1/oauth/token","scopes":{"patients:read":"patients:read","patients:write":"patients:write","appointments:read":"appointments:read","appointments:write":"appointments:write","pedigrees:read":"pedigrees:read","eligibility:read":"eligibility:read","results:read":"results:read","results:write":"results:write","recontact:read":"recontact:read","guidelines:read":"guidelines:read","locations:read":"locations:read","locations:write":"locations:write","calls:read":"calls:read"}}}}},"x-rateLimit":{"perMinute":600},"x-webhookEvents":["pedigree.completed","eligibility.changed","result.released","recontact.created","call.failed"]},"paths":{"/patients":{"get":{"operationId":"patients.list","summary":"List patients","description":"Newest first. Filter by record number to find one.","tags":["patients"],"security":[{"apiKey":["patients:read"]},{"oauth":["patients:read"]}],"parameters":[{"name":"mrn","in":"query","required":false,"description":"Exact record number.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many rows to return.","schema":{"type":"integer","description":"At most 200; 50 when omitted.","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name_given":{"type":"string","description":"Given name.","nullable":true},"name_family":{"type":"string","description":"Family name.","nullable":true},"date_of_birth":{"type":"string","description":"YYYY-MM-DD.","nullable":true,"format":"date"},"sex":{"type":"string","description":"Sex assigned at birth.","nullable":true,"enum":["female","male","intersex","unknown"]},"external_patient_ref":{"type":"string","description":"Your record number (MRN).","nullable":true},"monitoring_status":{"type":"string","description":"Whether the patient is still monitored on the registry.","enum":["active","deceased","departed","withdrawn"]},"location_id":{"type":"string","description":"The site the patient belongs to.","nullable":true,"format":"uuid"},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false}}},"additionalProperties":false}}}},"401":{"description":"unauthorized"},"403":{"description":"missing_scope"},"429":{"description":"rate_limited"}}},"post":{"operationId":"patients.create","summary":"Create a patient","description":"Identifiers need a paid plan and a current BAA; a test key writes to the sandbox.","tags":["patients"],"security":[{"apiKey":["patients:write"]},{"oauth":["patients:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Every write (POST and PATCH) requires an Idempotency-Key header, any string unique to the attempt. A retry with the same key replays the first response instead of writing twice. The same key with a different body is refused with 409.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name_given":{"type":"string","description":"Given name.","nullable":true,"maxLength":120},"name_family":{"type":"string","description":"Family name.","nullable":true,"maxLength":120},"date_of_birth":{"type":"string","description":"YYYY-MM-DD.","nullable":true,"format":"date"},"sex":{"type":"string","description":"Sex assigned at birth.","nullable":true,"enum":["female","male","intersex","unknown"]},"external_patient_ref":{"type":"string","description":"Your record number (MRN).","nullable":true,"maxLength":120},"phone":{"type":"string","description":"E.164 where possible.","nullable":true,"maxLength":40},"email":{"type":"string","description":"Contact email.","nullable":true,"format":"email"},"preferred_language":{"type":"string","description":"BCP 47 tag, such as en or es.","nullable":true,"maxLength":16},"location_id":{"type":"string","description":"The site the patient belongs to.","nullable":true,"format":"uuid"}},"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"invalid_request, idempotency_key_required or invalid_json"},"401":{"description":"unauthorized"},"403":{"description":"identity_not_permitted","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"idempotency_key_reused"},"429":{"description":"rate_limited"}}}},"/patients/{id}":{"patch":{"operationId":"patients.update","summary":"Update a patient","description":"Send only the fields to change. Null clears a field.","tags":["patients"],"security":[{"apiKey":["patients:write"]},{"oauth":["patients:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The patient id.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Every write (POST and PATCH) requires an Idempotency-Key header, any string unique to the attempt. A retry with the same key replays the first response instead of writing twice. The same key with a different body is refused with 409.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name_given":{"type":"string","description":"Given name.","nullable":true,"maxLength":120},"name_family":{"type":"string","description":"Family name.","nullable":true,"maxLength":120},"date_of_birth":{"type":"string","description":"YYYY-MM-DD.","nullable":true,"format":"date"},"sex":{"type":"string","description":"Sex assigned at birth.","nullable":true,"enum":["female","male","intersex","unknown"]},"external_patient_ref":{"type":"string","description":"Your record number (MRN).","nullable":true,"maxLength":120},"phone":{"type":"string","description":"E.164 where possible.","nullable":true,"maxLength":40},"email":{"type":"string","description":"Contact email.","nullable":true,"format":"email"},"preferred_language":{"type":"string","description":"BCP 47 tag, such as en or es.","nullable":true,"maxLength":16},"location_id":{"type":"string","description":"The site the patient belongs to.","nullable":true,"format":"uuid"},"monitoring_status":{"type":"string","enum":["active","deceased","departed","withdrawn"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name_given":{"type":"string","description":"Given name.","nullable":true},"name_family":{"type":"string","description":"Family name.","nullable":true},"date_of_birth":{"type":"string","description":"YYYY-MM-DD.","nullable":true,"format":"date"},"sex":{"type":"string","description":"Sex assigned at birth.","nullable":true,"enum":["female","male","intersex","unknown"]},"external_patient_ref":{"type":"string","description":"Your record number (MRN).","nullable":true},"monitoring_status":{"type":"string","description":"Whether the patient is still monitored on the registry.","enum":["active","deceased","departed","withdrawn"]},"location_id":{"type":"string","description":"The site the patient belongs to.","nullable":true,"format":"uuid"},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"invalid_request, idempotency_key_required or invalid_json"},"401":{"description":"unauthorized"},"403":{"description":"missing_scope"},"404":{"description":"not_found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"idempotency_key_reused"},"429":{"description":"rate_limited"}}}},"/appointments":{"get":{"operationId":"appointments.list","summary":"List appointments","description":"Soonest first.","tags":["appointments"],"security":[{"apiKey":["appointments:read"]},{"oauth":["appointments:read"]}],"parameters":[{"name":"from","in":"query","required":false,"description":"Starting at or after this instant.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"description":"Starting before this instant.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"How many rows to return.","schema":{"type":"integer","description":"At most 500; 100 when omitted.","minimum":1,"maximum":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"case_id":{"type":"string","format":"uuid"},"location_id":{"type":"string","format":"uuid"},"starts_at":{"type":"string","format":"date-time"},"visit_type":{"type":"string","description":"Your visit type, as text.","nullable":true},"provider":{"type":"string","description":"The clinician, as text.","nullable":true},"source":{"type":"string","description":"How the appointment arrived: feed, api, or console."},"external_ref":{"type":"string","description":"Your identifier for the appointment.","nullable":true},"status":{"type":"string","enum":["scheduled","completed","cancelled","no_show"]}},"additionalProperties":false}}},"additionalProperties":false}}}},"401":{"description":"unauthorized"},"403":{"description":"missing_scope"},"429":{"description":"rate_limited"}}},"post":{"operationId":"appointments.create","summary":"Book an appointment on a case","tags":["appointments"],"security":[{"apiKey":["appointments:write"]},{"oauth":["appointments:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Every write (POST and PATCH) requires an Idempotency-Key header, any string unique to the attempt. A retry with the same key replays the first response instead of writing twice. The same key with a different body is refused with 409.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"case_id":{"type":"string","format":"uuid"},"location_id":{"type":"string","format":"uuid"},"starts_at":{"type":"string","format":"date-time"},"visit_type":{"type":"string","nullable":true,"maxLength":120},"provider":{"type":"string","nullable":true,"maxLength":120},"external_ref":{"type":"string","description":"Your identifier for the appointment.","nullable":true,"maxLength":120}},"required":["case_id","location_id","starts_at"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"invalid_request, idempotency_key_required or invalid_json"},"401":{"description":"unauthorized"},"403":{"description":"missing_scope"},"404":{"description":"case_not_found or location_not_found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"idempotency_key_reused"},"429":{"description":"rate_limited"}}}},"/appointments/{id}":{"patch":{"operationId":"appointments.update","summary":"Reschedule, reassign or close an appointment","tags":["appointments"],"security":[{"apiKey":["appointments:write"]},{"oauth":["appointments:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The appointment id.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Every write (POST and PATCH) requires an Idempotency-Key header, any string unique to the attempt. A retry with the same key replays the first response instead of writing twice. The same key with a different body is refused with 409.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"starts_at":{"type":"string","format":"date-time"},"location_id":{"type":"string","format":"uuid"},"visit_type":{"type":"string","nullable":true,"maxLength":120},"provider":{"type":"string","nullable":true,"maxLength":120},"external_ref":{"type":"string","nullable":true,"maxLength":120},"status":{"type":"string","enum":["scheduled","completed","cancelled","no_show"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"case_id":{"type":"string","format":"uuid"},"location_id":{"type":"string","format":"uuid"},"starts_at":{"type":"string","format":"date-time"},"visit_type":{"type":"string","description":"Your visit type, as text.","nullable":true},"provider":{"type":"string","description":"The clinician, as text.","nullable":true},"source":{"type":"string","description":"How the appointment arrived: feed, api, or console."},"external_ref":{"type":"string","description":"Your identifier for the appointment.","nullable":true},"status":{"type":"string","enum":["scheduled","completed","cancelled","no_show"]}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"invalid_request, idempotency_key_required or invalid_json"},"401":{"description":"unauthorized"},"403":{"description":"missing_scope"},"404":{"description":"not_found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"idempotency_key_reused"},"429":{"description":"rate_limited"}}}},"/pedigrees":{"get":{"operationId":"pedigrees.list","summary":"List cases with a pedigree","description":"Most recently changed first. Fetch one by id for the family itself.","tags":["pedigrees"],"security":[{"apiKey":["pedigrees:read"]},{"oauth":["pedigrees:read"]}],"parameters":[{"name":"patient_id","in":"query","required":false,"description":"Only this patient's cases.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"description":"How many rows to return.","schema":{"type":"integer","description":"At most 200; 50 when omitted.","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"case_code":{"type":"string","description":"The human-readable case code."},"state":{"type":"string","enum":["intake_pending","intake_complete","in_review","decided","ordered","result_received","released","on_registry","not_tested"]},"patient_id":{"type":"string","format":"uuid"},"location_id":{"type":"string","nullable":true,"format":"uuid"},"people":{"type":"integer","description":"How many people are on the pedigree."},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":false}}},"additionalProperties":false}}}},"401":{"description":"unauthorized"},"403":{"description":"missing_scope"},"429":{"description":"rate_limited"}}}},"/pedigrees/{caseId}":{"get":{"operationId":"pedigrees.get","summary":"Read a pedigree","description":"Every person with their relation to the proband derived from the graph, their diagnoses and current results, and the edges between them. Reading only: the pedigree is edited in Lumagen, where its invariants are enforced.","tags":["pedigrees"],"security":[{"apiKey":["pedigrees:read"]},{"oauth":["pedigrees:read"]}],"parameters":[{"name":"caseId","in":"path","required":true,"description":"The case id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"case":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"case_code":{"type":"string"},"state":{"type":"string","enum":["intake_pending","intake_complete","in_review","decided","ordered","result_received","released","on_registry","not_tested"]},"patient_id":{"type":"string","format":"uuid"},"location_id":{"type":"string","nullable":true,"format":"uuid"},"ancestry_maternal":{"type":"array","items":{"type":"string","enum":["white","black_or_african_american","hispanic_or_latino","asian","american_indian_or_alaska_native","native_hawaiian_or_pacific_islander","middle_eastern_or_north_african","other"]}},"ancestry_paternal":{"type":"array","items":{"type":"string","enum":["white","black_or_african_american","hispanic_or_latino","asian","american_indian_or_alaska_native","native_hawaiian_or_pacific_islander","middle_eastern_or_north_african","other"]}},"ashkenazi_maternal":{"type":"string","enum":["yes","no","unknown"]},"ashkenazi_paternal":{"type":"string","enum":["yes","no","unknown"]}},"additionalProperties":false},"persons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"is_proband":{"type":"boolean"},"relation":{"type":"string","description":"Derived from the graph, such as mother, maternal aunt, half-brother."},"lineage_side":{"type":"string","description":"Which of the proband's lines this person sits on, derived.","nullable":true,"enum":["maternal","paternal","both","unknown"]},"given_name":{"type":"string","description":"A first name or initials, where recorded.","nullable":true},"sex":{"type":"string","enum":["female","male","intersex","unknown"]},"living_status":{"type":"string","enum":["living","deceased","unknown"]},"age_or_birth_year":{"type":"integer","description":"An age, or a four-digit birth year, as recorded.","nullable":true},"adopted":{"type":"boolean"},"adenoma_count":{"type":"integer","description":"Cumulative adenomatous polyps, where known.","nullable":true},"diagnoses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cancer_type":{"type":"string","enum":["breast","ovarian","fallopian_tube","primary_peritoneal","pancreatic","prostate","colorectal","endometrial","gastric","melanoma","thyroid","kidney","bladder","lung","brain","leukemia","lymphoma","sarcoma","malignant_phyllodes","stic","adrenocortical_carcinoma","cervical","testicular","other","unknown"]},"age_at_onset":{"type":"integer","description":"Age at diagnosis, where known.","nullable":true},"certainty":{"type":"string","enum":["confirmed","self_reported","suspected"]}},"additionalProperties":false}},"results":{"type":"array","description":"Current germline results, the latest per gene.","items":{"type":"object","properties":{"gene":{"type":"string","enum":["APC","ATM","BARD1","BMPR1A","BRCA1","BRCA2","CDH1","CDK4","CDKN2A","CHEK2","EPCAM","MLH1","MSH2","MSH6","MUTYH","NBN","PALB2","PMS2","PTEN","RAD51C","RAD51D","SMAD4","STK11","TP53","other"]},"classification":{"type":"string","enum":["pathogenic","likely_pathogenic","vus","likely_benign","benign","negative","not_tested"]},"reported_at":{"type":"string","format":"date"},"basis":{"type":"string","description":"report: a lab report is on file. reported: told to the clinician by the family.","nullable":true,"enum":["report","reported"]}},"additionalProperties":false}}},"additionalProperties":false}},"edges":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["parent-child","partner","sibling","half-sibling","twin"]},"from":{"type":"string","description":"For parent-child, the parent.","format":"uuid"},"to":{"type":"string","description":"For parent-child, the child.","format":"uuid"},"shared_parent_id":{"type":"string","description":"On a half-sibling edge, the parent the two share.","nullable":true,"format":"uuid"},"zygosity":{"type":"string","description":"On a twin edge.","nullable":true,"enum":["identical","fraternal","unknown"]}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"unauthorized"},"403":{"description":"missing_scope"},"404":{"description":"not_found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"rate_limited"}}}},"/eligibility/{caseId}":{"get":{"operationId":"eligibility.get","summary":"Read a case's testing criteria","description":"Evaluated on request against the current pedigree and the current guideline versions. Decision support: the clinician decides.","tags":["eligibility"],"security":[{"apiKey":["eligibility:read"]},{"oauth":["eligibility:read"]}],"parameters":[{"name":"caseId","in":"path","required":true,"description":"The case id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"case_id":{"type":"string","format":"uuid"},"evaluated_at":{"type":"string","format":"date-time"},"guidelines":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"version":{"type":"string"}},"additionalProperties":false}},"recommend_testing":{"type":"boolean","description":"True when at least one indicated criterion is met."},"met":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The rule id, such as CRIT-2-FAMILY-MEETS."},"criterion":{"type":"string","description":"The guideline's own criterion id, such as CRIT-2."},"guideline":{"type":"string"},"version":{"type":"string"},"label":{"type":"string","description":"Lumagen's restatement of the criterion."},"tier":{"type":"string","description":"The strength the source gives it.","enum":["indicated","consider","clinical_judgment","reference"]},"reason":{"type":"string","description":"Why it could not be evaluated, on the not_evaluable list only.","nullable":true}},"additionalProperties":false}},"near_miss":{"type":"array","description":"Criteria the source words as consider or clinical judgment.","items":{"type":"object","properties":{"id":{"type":"string","description":"The rule id, such as CRIT-2-FAMILY-MEETS."},"criterion":{"type":"string","description":"The guideline's own criterion id, such as CRIT-2."},"guideline":{"type":"string"},"version":{"type":"string"},"label":{"type":"string","description":"Lumagen's restatement of the criterion."},"tier":{"type":"string","description":"The strength the source gives it.","enum":["indicated","consider","clinical_judgment","reference"]},"reason":{"type":"string","description":"Why it could not be evaluated, on the not_evaluable list only.","nullable":true}},"additionalProperties":false}},"not_evaluable":{"type":"array","description":"Criteria this engine cannot decide from a pedigree, named so nobody reads a false negative.","items":{"type":"object","properties":{"id":{"type":"string","description":"The rule id, such as CRIT-2-FAMILY-MEETS."},"criterion":{"type":"string","description":"The guideline's own criterion id, such as CRIT-2."},"guideline":{"type":"string"},"version":{"type":"string"},"label":{"type":"string","description":"Lumagen's restatement of the criterion."},"tier":{"type":"string","description":"The strength the source gives it.","enum":["indicated","consider","clinical_judgment","reference"]},"reason":{"type":"string","description":"Why it could not be evaluated, on the not_evaluable list only.","nullable":true}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false}}}},"401":{"description":"unauthorized"},"403":{"description":"missing_scope"},"404":{"description":"not_found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"rate_limited"}}}},"/results":{"get":{"operationId":"results.list","summary":"List results","description":"Newest first. Findings are read on the pedigree, per person.","tags":["results"],"security":[{"apiKey":["results:read"]},{"oauth":["results:read"]}],"parameters":[{"name":"case_id","in":"query","required":false,"description":"Only this case.","schema":{"type":"string","format":"uuid"}},{"name":"released","in":"query","required":false,"description":"true for released results only.","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"How many rows to return.","schema":{"type":"integer","description":"At most 200; 50 when omitted.","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"case_id":{"type":"string","nullable":true,"format":"uuid"},"patient_id":{"type":"string","nullable":true,"format":"uuid"},"source":{"type":"string","enum":["ehr_feed","lab_api","manual_upload","api"]},"lab_name":{"type":"string","nullable":true},"lab_accession":{"type":"string","nullable":true},"reported_at":{"type":"string","nullable":true,"format":"date"},"verified_at":{"type":"string","description":"When a clinician verified the summary.","nullable":true,"format":"date-time"},"released_at":{"type":"string","description":"When it was released to the patient's record.","nullable":true,"format":"date-time"},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false}}},"additionalProperties":false}}}},"401":{"description":"unauthorized"},"403":{"description":"missing_scope"},"429":{"description":"rate_limited"}}},"post":{"operationId":"results.create","summary":"Deliver a lab result","description":"Matched to a patient by order id, record number, or name and date of birth. A result that matches nobody is held for a clinician to link, never dropped.","tags":["results"],"security":[{"apiKey":["results:write"]},{"oauth":["results:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Every write (POST and PATCH) requires an Idempotency-Key header, any string unique to the attempt. A retry with the same key replays the first response instead of writing twice. The same key with a different body is refused with 409.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lab_accession":{"type":"string","description":"The lab's accession number.","maxLength":120},"lab_name":{"type":"string","description":"The lab.","nullable":true,"maxLength":120},"reported_at":{"type":"string","description":"YYYY-MM-DD.","nullable":true,"format":"date"},"mrn":{"type":"string","description":"Your record number for the patient, the surest way to match.","nullable":true,"maxLength":120},"patient_name":{"type":"string","description":"Full name as the lab has it, used to match when there is no record number.","nullable":true,"maxLength":200},"date_of_birth":{"type":"string","description":"YYYY-MM-DD.","nullable":true,"format":"date"},"order_id":{"type":"string","description":"A Lumagen order id, when Lumagen placed the order.","nullable":true,"format":"uuid"},"findings":{"type":"array","description":"One row per gene reported.","items":{"type":"object","properties":{"gene":{"type":"string","enum":["APC","ATM","BARD1","BMPR1A","BRCA1","BRCA2","CDH1","CDK4","CDKN2A","CHEK2","EPCAM","MLH1","MSH2","MSH6","MUTYH","NBN","PALB2","PMS2","PTEN","RAD51C","RAD51D","SMAD4","STK11","TP53","other"]},"classification":{"type":"string","enum":["pathogenic","likely_pathogenic","vus","likely_benign","benign","negative","not_tested"]},"variant_hgvs":{"type":"string","description":"HGVS notation, where reported.","nullable":true,"maxLength":200}},"required":["gene","classification"],"additionalProperties":false}},"raw":{"type":"object","description":"The lab's own payload, kept as sent.","nullable":true,"properties":{},"additionalProperties":true}},"required":["lab_accession","findings"],"additionalProperties":false}}}},"responses":{"201":{"description":"Attached to a case, or held for matching.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"outcome":{"type":"string","enum":["attached","held"]},"result_id":{"type":"string","nullable":true,"format":"uuid"},"case_id":{"type":"string","nullable":true,"format":"uuid"},"unmatched_id":{"type":"string","nullable":true,"format":"uuid"},"candidate_count":{"type":"integer","nullable":true}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"invalid_request, idempotency_key_required or invalid_json"},"401":{"description":"unauthorized"},"403":{"description":"missing_scope"},"409":{"description":"idempotency_key_reused"},"429":{"description":"rate_limited"}}}},"/recontact":{"get":{"operationId":"recontact.list","summary":"List recontact items","description":"Patients the registry has flagged since their result: a reclassified variant, a family-history change, a guideline change. Open items unless a status is given.","tags":["recontact"],"security":[{"apiKey":["recontact:read"]},{"oauth":["recontact:read"]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Defaults to open.","schema":{"type":"string","enum":["open","actioned","dismissed"]}},{"name":"limit","in":"query","required":false,"description":"How many rows to return.","schema":{"type":"integer","description":"At most 500; 100 when omitted.","minimum":1,"maximum":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"case_id":{"type":"string","format":"uuid"},"case_code":{"type":"string"},"reason":{"type":"string","enum":["reclassification","management","testing_criteria"]},"status":{"type":"string","enum":["open","actioned","dismissed"]},"created_at":{"type":"string","format":"date-time"},"dispositioned_at":{"type":"string","nullable":true,"format":"date-time"}},"additionalProperties":false}}},"additionalProperties":false}}}},"401":{"description":"unauthorized"},"403":{"description":"missing_scope"},"429":{"description":"rate_limited"}}}},"/guidelines":{"get":{"operationId":"guidelines.list","summary":"List the guideline versions in force and their criteria","description":"What the eligibility endpoint evaluates against, by id, so a change in version is visible before it changes an answer.","tags":["guidelines"],"security":[{"apiKey":["guidelines:read"]},{"oauth":["guidelines:read"]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"NCCN-BOPP or NCCN-CEEG."},"name":{"type":"string"},"version":{"type":"string"},"version_date":{"type":"string","format":"date"},"criteria":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"criterion":{"type":"string"},"category":{"type":"string"},"tier":{"type":"string","enum":["indicated","consider","clinical_judgment","reference"]},"summary":{"type":"string","description":"Lumagen's restatement, never the source text."},"evaluable":{"type":"boolean","description":"False for a criterion the engine names but cannot decide from a pedigree."}},"additionalProperties":false}}},"additionalProperties":false}}},"additionalProperties":false}}}},"401":{"description":"unauthorized"},"403":{"description":"missing_scope"},"429":{"description":"rate_limited"}}}},"/locations":{"get":{"operationId":"locations.list","summary":"List sites","tags":["locations"],"security":[{"apiKey":["locations:read"]},{"oauth":["locations:read"]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"timezone":{"type":"string","description":"IANA zone, such as America/Phoenix.","nullable":true},"address":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false}}},"additionalProperties":false}}}},"401":{"description":"unauthorized"},"403":{"description":"missing_scope"},"429":{"description":"rate_limited"}}},"post":{"operationId":"locations.create","summary":"Add a site","tags":["locations"],"security":[{"apiKey":["locations:write"]},{"oauth":["locations:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Every write (POST and PATCH) requires an Idempotency-Key header, any string unique to the attempt. A retry with the same key replays the first response instead of writing twice. The same key with a different body is refused with 409.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"timezone":{"type":"string","description":"IANA zone.","nullable":true,"maxLength":64},"address":{"type":"string","nullable":true,"maxLength":400},"phone":{"type":"string","nullable":true,"maxLength":40}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"timezone":{"type":"string","description":"IANA zone, such as America/Phoenix.","nullable":true},"address":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false}},"additionalProperties":false}}}},"400":{"description":"invalid_request, idempotency_key_required or invalid_json"},"401":{"description":"unauthorized"},"403":{"description":"missing_scope"},"409":{"description":"idempotency_key_reused"},"429":{"description":"rate_limited"}}}},"/calls":{"get":{"operationId":"calls.list","summary":"List intake conversations","description":"Every chat, browser voice session or phone call a patient had with the intake agent, with whether it reached the coverage minimum. Transcripts are not exposed.","tags":["calls"],"security":[{"apiKey":["calls:read"]},{"oauth":["calls:read"]}],"parameters":[{"name":"case_id","in":"query","required":false,"description":"Only this case.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"description":"How many rows to return.","schema":{"type":"integer","description":"At most 500; 100 when omitted.","minimum":1,"maximum":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"case_id":{"type":"string","format":"uuid"},"channel":{"type":"string","enum":["chat","web_voice","phone"]},"status":{"type":"string","enum":["started","ready_for_review","abandoned"]},"attempt_number":{"type":"integer"},"started_at":{"type":"string","nullable":true,"format":"date-time"},"ended_at":{"type":"string","nullable":true,"format":"date-time"},"duration_s":{"type":"integer","description":"Seconds.","nullable":true},"minimum_met":{"type":"boolean","description":"Whether the conversation reached the coverage minimum.","nullable":true}},"additionalProperties":false}}},"additionalProperties":false}}}},"401":{"description":"unauthorized"},"403":{"description":"missing_scope"},"429":{"description":"rate_limited"}}}},"/fhir":{"post":{"operationId":"fhir.bundle","summary":"Deliver a FHIR Bundle","description":"Patient, Appointment and DiagnosticReport resources, mapped onto Lumagen's own records. Needs patients:write and appointments:write. Fields Lumagen does not hold are named in the response as ignored-field issues.","tags":["fhir"],"security":[{"apiKey":["patients:write"]},{"oauth":["patients:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Every write (POST and PATCH) requires an Idempotency-Key header, any string unique to the attempt. A retry with the same key replays the first response instead of writing twice. The same key with a different body is refused with 409.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resourceType":{"type":"string","enum":["Bundle"]},"type":{"type":"string"},"entry":{"type":"array","items":{"type":"object","properties":{"resource":{"type":"object","properties":{"resourceType":{"type":"string"}},"additionalProperties":true}},"additionalProperties":false}}},"required":["resourceType","entry"],"additionalProperties":true}}}},"responses":{"200":{"description":"Processed. Created resources and issues are listed.","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"array","items":{"type":"object","properties":{"resourceType":{"type":"string"},"id":{"type":"string","format":"uuid"}},"additionalProperties":true}},"issue":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}}},"additionalProperties":true}}}},"400":{"description":"invalid_bundle","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"unauthorized"},"403":{"description":"identity_not_permitted or insufficient_scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"idempotency_key_reused"},"429":{"description":"rate_limited"}}}},"/oauth/token":{"post":{"operationId":"oauth.token","summary":"Exchange client credentials for an access token","description":"Form-encoded or JSON: grant_type=client_credentials, client_id, client_secret, and an optional space-separated scope. Basic authentication with the client id and secret also works. Tokens last one hour.","tags":["oauth"],"security":[],"parameters":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"client_id":{"type":"string"},"client_secret":{"type":"string"},"scope":{"type":"string","description":"Space-separated, a subset of the key's scopes."}},"required":["grant_type","client_id","client_secret"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","enum":["bearer"]},"expires_in":{"type":"integer","description":"Seconds."},"scope":{"type":"string"}},"additionalProperties":false}}}},"400":{"description":"invalid_request, unsupported_grant_type or invalid_scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"invalid_client","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"rate_limited"}}}}}}