{"openapi":"3.1.0","info":{"title":"Authora API","version":"1.0.0","description":"Authora is a prior-authorization platform built directly against the HL7 Da Vinci PAS / CRD / DTR implementation guides, US Core 6.1.0, SMART on FHIR 2.2, CDS Hooks 2.0, and X12 005010X217/X216. This document covers every public endpoint exposed by the Authora platform. Every example response is produced by the same handlers that serve production traffic.","contact":{"name":"Authora Standards & Conformance","email":"interop@authora.health","url":"https://authora.health/conformance"},"license":{"name":"Authora Commercial","url":"https://authora.health/legal/api-terms"}},"servers":[{"url":"https://authora-pa.netlify.app/api","description":"Sandbox"},{"url":"https://authora.health/api","description":"Production"}],"tags":[{"name":"Authentication","description":"Service health and identity."},{"name":"Cases","description":"Authora case worklist and detail."},{"name":"Da Vinci CRD","description":"Coverage Requirements Discovery via CDS Hooks 2.0 at order-sign and order-select."},{"name":"Da Vinci DTR","description":"Documentation Templates and Rules — Questionnaire delivery and $populate operation."},{"name":"Da Vinci PAS","description":"Prior Authorization Support — request Bundle preview and $submit."},{"name":"Runs","description":"Authora agent run inspection and live event stream (Server-Sent Events)."},{"name":"Conformance","description":"Inferno-style PAS Bundle validator — surface live pass/fail reports."},{"name":"Public Data","description":"Pass-through helpers for NPPES, openFDA / RxNav, NLM ICD-10, ClinicalTrials.gov."},{"name":"Media","description":"Open Graph image generation."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"SMART on FHIR / Authora-issued JWT. Required on every endpoint that touches PHI or persists state."},"apiKey":{"type":"apiKey","in":"header","name":"X-Authora-Key","description":"Tenant-scoped service key for backend-to-backend integrations (CDS Hooks, batch ingestion)."}},"schemas":{"FhirBundle":{"type":"object","description":"FHIR R4 Bundle.","properties":{"resourceType":{"type":"string","example":"Bundle"},"id":{"type":"string"},"type":{"type":"string","example":"collection"},"entry":{"type":"array","items":{"type":"object","properties":{"fullUrl":{"type":"string"},"resource":{"type":"object","description":"Generic FHIR R4 resource shape.","properties":{"resourceType":{"type":"string","example":"Bundle"},"id":{"type":"string"}},"additionalProperties":true}}}}},"required":["resourceType","type"]},"FhirResource":{"type":"object","description":"Generic FHIR R4 resource shape.","properties":{"resourceType":{"type":"string","example":"Bundle"},"id":{"type":"string"}},"additionalProperties":true},"ValidationFinding":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning","info"]},"path":{"type":"string","example":"Bundle.entry[Claim].use"},"message":{"type":"string"},"expected":{"type":"string"},"actual":{"type":"string"},"check":{"type":"string","example":"PAS-CLAIM-USE-PREAUTH"}},"required":["severity","path","message","check"]},"ValidationReport":{"type":"object","properties":{"bundleId":{"type":"string"},"bundleType":{"type":"string"},"ranAt":{"type":"string","format":"date-time"},"durationMs":{"type":"number"},"totalChecks":{"type":"integer","example":15},"passed":{"type":"integer","example":15},"failed":{"type":"integer","example":0},"warnings":{"type":"integer","example":0},"overallStatus":{"type":"string","enum":["pass","fail","warn"]},"validatorVersion":{"type":"string","example":"authora-inferno v0.9.4"},"igVersion":{"type":"string","example":"hl7.fhir.us.davinci-pas#2.1.0"},"findings":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning","info"]},"path":{"type":"string","example":"Bundle.entry[Claim].use"},"message":{"type":"string"},"expected":{"type":"string"},"actual":{"type":"string"},"check":{"type":"string","example":"PAS-CLAIM-USE-PREAUTH"}},"required":["severity","path","message","check"]}}}},"CdsCard":{"type":"object","description":"CDS Hooks 2.0 Card.","properties":{"summary":{"type":"string"},"indicator":{"type":"string","enum":["info","warning","critical"]},"detail":{"type":"string"},"source":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string"}}},"links":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string"},"type":{"type":"string","enum":["absolute","smart"]},"appContext":{"type":"string"}}}}}}}},"paths":{"/health":{"get":{"tags":["Authentication"],"summary":"Service liveness probe","description":"Returns the build identity, current commit, and database connectivity status. Used by uptime monitors and synthetic checks.","operationId":"getHealth","responses":{"200":{"description":"Service is healthy.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"version":{"type":"string","example":"1.0.0"},"buildId":{"type":"string","example":"build-482"},"timestamp":{"type":"string","format":"date-time"}}}}}}}}},"/cases":{"get":{"tags":["Cases"],"summary":"List worklist cases","description":"Returns the active case worklist for the authenticated tenant. Cases are returned in SLA-pressure order by default.","operationId":"listCases","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Filter by CaseStatus (comma-separated for multi-select).","schema":{"type":"string","example":"in_review,info_requested"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","example":50}}],"responses":{"200":{"description":"Worklist case array.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FhirResource"}}}}}}}},"/cds-services":{"get":{"tags":["Da Vinci CRD"],"summary":"CDS Hooks service discovery","description":"CDS Hooks 2.0 discovery document. Lists the order-sign and order-select services Authora exposes for Coverage Requirements Discovery.","operationId":"discoverCdsServices","responses":{"200":{"description":"Service discovery document.","content":{"application/json":{"schema":{"type":"object","properties":{"services":{"type":"array","items":{"type":"object","properties":{"hook":{"type":"string","example":"order-sign"},"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"prefetch":{"type":"object","additionalProperties":{"type":"string"}}}}}}}}}}}}},"/cds-services/authora-crd-order-sign":{"post":{"tags":["Da Vinci CRD"],"summary":"CRD order-sign Card","description":"Returns one or more CDS Hooks Cards at order-sign time. Surfaces PA requirement, payer policy citation, and a SMART launch URL into Authora DTR.","operationId":"crdOrderSign","requestBody":{"required":false,"description":"CDS Hooks 2.0 hook request body (context + prefetch).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"CDS Hooks card array.","content":{"application/json":{"schema":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/CdsCard"}},"systemActions":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/dtr/questionnaire":{"get":{"tags":["Da Vinci DTR"],"summary":"Fetch DTR Questionnaire by procedure code","description":"Returns the FHIR R4 Questionnaire that maps the relevant payer policy criteria to fillable items. Each item carries an SDC initialExpression (CQL) so DTR apps can auto-populate from EHR data.","operationId":"getDtrQuestionnaire","parameters":[{"name":"cpt","in":"query","required":false,"description":"CPT code, e.g. 72148 (MRI lumbar spine).","schema":{"type":"string","example":"72148"}},{"name":"hcpcs","in":"query","required":false,"description":"HCPCS code, used for DME items.","schema":{"type":"string","example":"E2102"}}],"responses":{"200":{"description":"FHIR Questionnaire (DTR profile).","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirResource"}}}},"400":{"description":"Missing cpt or hcpcs parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FhirResource"}}}},"404":{"description":"No registered Questionnaire for the supplied code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FhirResource"}}}}}}},"/dtr/populate":{"post":{"tags":["Da Vinci DTR"],"summary":"Populate a DTR QuestionnaireResponse","description":"Executes the DTR $populate operation against an Authora-hosted Questionnaire and returns the resulting QuestionnaireResponse with answers derived from the EHR.","operationId":"populateDtrQuestionnaire","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"questionnaireUrl":{"type":"string","example":"https://authora.health/Questionnaire/authora-dtr-72148"},"patientId":{"type":"string","example":"pt-park"},"claimId":{"type":"string","example":"AUT-2026-00187"},"caseId":{"type":"string","example":"case-001"}},"required":["questionnaireUrl"]}}}},"responses":{"200":{"description":"FHIR QuestionnaireResponse.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirResource"}}}},"404":{"description":"Unknown questionnaire URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FhirResource"}}}}}}},"/pas/preview":{"get":{"tags":["Da Vinci PAS"],"summary":"Preview a PAS request Bundle","description":"Materializes the PAS request Bundle that would be submitted to the payer for the supplied case. Useful for evidence review, validator runs, and audit replay.","operationId":"previewPasBundle","parameters":[{"name":"caseId","in":"query","required":false,"description":"Authora case id. Defaults to case-001.","schema":{"type":"string","example":"case-001"}}],"responses":{"200":{"description":"FHIR Bundle (PAS request).","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}}},"404":{"description":"Unknown caseId."}}}},"/pas/submit":{"post":{"tags":["Da Vinci PAS"],"summary":"Submit a PAS request Bundle","description":"Submits a Da Vinci PAS request Bundle. Returns a synthesized ClaimResponse with preAuthRef. In production this proxies to the payer's PAS endpoint via the configured connector.","operationId":"submitPasBundle","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}}},"responses":{"200":{"description":"ClaimResponse.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirResource"}}}}}}},"/runs/{caseId}":{"get":{"tags":["Runs"],"summary":"Get an agent run by case id","description":"Returns the agent-run record (or live snapshot) for the supplied case id, including per-agent timing, token counts, decision, and conformance metadata.","operationId":"getRun","security":[{"bearerAuth":[]}],"parameters":[{"name":"caseId","in":"path","required":true,"schema":{"type":"string","example":"case-001"}}],"responses":{"200":{"description":"AgentRun record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FhirResource"}}}},"404":{"description":"Unknown caseId."}}}},"/runs/stream":{"get":{"tags":["Runs"],"summary":"Server-Sent Events stream of run lifecycle events","description":"Returns a long-lived text/event-stream emitting case-created, evidence-extracted, criteria-evaluated, submitted, payer-acknowledged, and decision-rendered events as they happen. Clients should reconnect with Last-Event-ID on disconnect.","operationId":"streamRuns","security":[{"bearerAuth":[]}],"parameters":[{"name":"caseId","in":"query","required":false,"description":"Restrict stream to a single case.","schema":{"type":"string","example":"case-001"}}],"responses":{"200":{"description":"Server-Sent Events stream.","content":{"text/event-stream":{"schema":{"type":"string"}}}}}}},"/inferno/run":{"get":{"tags":["Conformance"],"summary":"Validate the PAS Bundle for a seed case","description":"Runs the Authora Inferno-style structural validator against the PAS request Bundle materialized from the supplied case id. Returns a per-check finding report.","operationId":"infernoRunGet","parameters":[{"name":"caseId","in":"query","required":false,"schema":{"type":"string","example":"case-001"}}],"responses":{"200":{"description":"Validation report.","content":{"application/json":{"schema":{"type":"object","properties":{"caseId":{"type":"string"},"bundleId":{"type":"string"},"report":{"$ref":"#/components/schemas/ValidationReport"}}}}}}}},"post":{"tags":["Conformance"],"summary":"Validate an arbitrary FHIR Bundle","description":"Accepts any FHIR Bundle and returns the Authora Inferno-style validation report against the Da Vinci PAS request profile.","operationId":"infernoRunPost","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bundle":{"$ref":"#/components/schemas/FhirBundle"},"caseId":{"type":"string"}},"required":["bundle"]}}}},"responses":{"200":{"description":"Validation report.","content":{"application/json":{"schema":{"type":"object","properties":{"bundleId":{"type":"string"},"report":{"$ref":"#/components/schemas/ValidationReport"}}}}}},"400":{"description":"Missing or invalid bundle."}}}},"/npi":{"get":{"tags":["Public Data"],"summary":"NPPES NPI Registry lookup","description":"Pass-through to the NPPES NPI Registry. Returns a normalized provider record including taxonomy, license state, and active status.","operationId":"lookupNpi","parameters":[{"name":"number","in":"query","required":true,"description":"10-digit NPI.","schema":{"type":"string","example":"1376633768"}}],"responses":{"200":{"description":"NPI record.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/drug":{"get":{"tags":["Public Data"],"summary":"Drug lookup (openFDA + RxNav)","description":"Resolves a drug query to RxNorm + openFDA label data: indications, contraindications, black-box warnings, and dosage forms.","operationId":"lookupDrug","parameters":[{"name":"q","in":"query","required":true,"description":"Drug name or RxNorm CUI.","schema":{"type":"string","example":"pembrolizumab"}}],"responses":{"200":{"description":"Drug record.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/icd10":{"get":{"tags":["Public Data"],"summary":"ICD-10-CM autocomplete","description":"Pass-through to NLM Clinical Tables ICD-10-CM autocomplete. Returns up to 7 candidate codes per query.","operationId":"lookupIcd10","parameters":[{"name":"q","in":"query","required":true,"description":"Free-text query.","schema":{"type":"string","example":"lumbar radiculopathy"}}],"responses":{"200":{"description":"Code list.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/clinicaltrials":{"get":{"tags":["Public Data"],"summary":"ClinicalTrials.gov v2 search","description":"Searches ClinicalTrials.gov v2 by condition + intervention. Used for evidence-supporting links in oncology and rare-disease PAs.","operationId":"searchTrials","parameters":[{"name":"condition","in":"query","required":true,"schema":{"type":"string","example":"NSCLC"}},{"name":"intervention","in":"query","required":false,"schema":{"type":"string","example":"pembrolizumab"}}],"responses":{"200":{"description":"Trials list.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/og":{"get":{"tags":["Media"],"summary":"Open Graph image","description":"Generates a 1200×630 PNG Open Graph card. Used by /press, /customers, and per-case shareable links.","operationId":"getOgImage","parameters":[{"name":"title","in":"query","required":false,"schema":{"type":"string"}},{"name":"subtitle","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"PNG image.","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}}}}}}}