{ "components": { "parameters": { }, "schemas": { "AgentDestination": { "properties": { "kind": { "enum": [ "agent" ], "type": "string" }, "promptTemplate": { "description": "Prompt skeleton. May reference allowed placeholders: `{{patient.name}}`, `{{patient.dob}}`, `{{resource.id}}`, `{{resource.status}}`, `{{resource.type}}`, `{{event.fired_at}}`.", "maxLength": 2000, "type": "string" }, "useCase": { "description": "Slug of an enabled agent use case (see `lib/agent/use-cases`).", "example": "appointment-prep", "type": "string" } }, "required": [ "kind", "useCase", "promptTemplate" ], "type": "object" }, "AgentInvokeRequest": { "properties": { "prompt": { "example": "Pull the medication list for John Smith.", "maxLength": 4000, "minLength": 1, "type": "string" }, "selectedPatientId": { "description": "Optional canonical Patient id of a suggestion the user picked. Used as a hint in the KNOWN CONTEXT block; not authoritative.", "type": "string" }, "useCase": { "description": "Slug of an enabled agent use case. No public slug is currently accepted — this surface is marked experimental and not yet usable by external developers.", "type": "string" } }, "required": [ "prompt", "useCase" ], "type": "object" }, "AgentRun": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "delivery_id": { "type": "string" }, "event_fired_at": { "type": [ "string", "null" ] }, "event_type": { "type": [ "string", "null" ] }, "finished_at": { "format": "date-time", "type": [ "string", "null" ] }, "fire_at": { "format": "date-time", "type": "string" }, "started_at": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "Delivery row status: `pending`, `in_flight`, `succeeded`, `failed`, `cancelled`.", "type": "string" }, "subscription_id": { "type": "string" }, "tool_calls": { "items": { "$ref": "#/components/schemas/AgentToolCall" }, "type": "array" }, "transcript": { "type": [ "string", "null" ] }, "use_case": { "type": [ "string", "null" ] } }, "required": [ "delivery_id", "subscription_id", "status", "fire_at", "created_at", "use_case", "event_type", "event_fired_at", "started_at", "finished_at", "transcript", "tool_calls" ], "type": "object" }, "AgentRunsList": { "properties": { "runs": { "items": { "$ref": "#/components/schemas/AgentRun" }, "type": "array" } }, "required": [ "runs" ], "type": "object" }, "AgentToolCall": { "properties": { "args": { }, "id": { "type": "string" }, "name": { "type": "string" }, "result": { } }, "required": [ "id", "name" ], "type": "object" }, "AppointmentNoShowTrigger": { "properties": { "kind": { "enum": [ "template" ], "type": "string" }, "offsetMinutes": { "anyOf": [ { "enum": [ 15 ], "type": "number" }, { "enum": [ 60 ], "type": "number" } ] }, "template": { "enum": [ "appointment_no_show" ], "type": "string" } }, "required": [ "kind", "template", "offsetMinutes" ], "type": "object" }, "AppointmentReminderTrigger": { "properties": { "kind": { "enum": [ "template" ], "type": "string" }, "offsetMinutes": { "anyOf": [ { "enum": [ 30 ], "type": "number" }, { "enum": [ 60 ], "type": "number" }, { "enum": [ 1440 ], "type": "number" } ] }, "template": { "enum": [ "appointment_reminder" ], "type": "string" } }, "required": [ "kind", "template", "offsetMinutes" ], "type": "object" }, "Bundle": { "description": "FHIR `Bundle` of type `searchset`. Returned by all search endpoints and by `Patient/{id}/$everything`.", "properties": { "entry": { "items": { "$ref": "#/components/schemas/BundleEntry" }, "type": "array" }, "link": { "items": { "$ref": "#/components/schemas/BundleLink" }, "type": "array" }, "resourceType": { "enum": [ "Bundle" ], "type": "string" }, "total": { "minimum": 0, "type": "integer" }, "type": { "enum": [ "searchset" ], "type": "string" } }, "required": [ "resourceType", "type" ], "type": "object" }, "BundleEntry": { "properties": { "fullUrl": { "format": "uri", "type": "string" }, "resource": { "$ref": "#/components/schemas/FhirResource" }, "search": { "properties": { "mode": { "enum": [ "match", "include", "outcome" ], "type": "string" } }, "required": [ "mode" ], "type": "object" } }, "required": [ "resource" ], "type": "object" }, "BundleLink": { "properties": { "relation": { "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "relation", "url" ], "type": "object" }, "CapabilityStatement": { "properties": { "date": { "type": "string" }, "fhirVersion": { "type": "string" }, "format": { "items": { "type": "string" }, "type": "array" }, "kind": { "type": "string" }, "resourceType": { "enum": [ "CapabilityStatement" ], "type": "string" }, "rest": { "items": { }, "type": "array" }, "status": { "type": "string" } }, "required": [ "resourceType", "status", "date", "kind", "fhirVersion", "format", "rest" ], "type": "object" }, "CriteriaEvent": { "properties": { "fired_at": { "format": "date-time", "type": "string" }, "trigger": { "properties": { "kind": { "enum": [ "criteria" ], "type": "string" }, "resourceType": { "type": "string" } }, "required": [ "kind", "resourceType" ], "type": "object" }, "type": { "enum": [ "criteria.matched" ], "type": "string" } }, "required": [ "type", "fired_at", "trigger" ], "type": "object" }, "CriteriaTrigger": { "properties": { "fhirpath": { "description": "Array of boolean FHIRPath expressions, AND-combined. Parsed with the HL7-maintained fhirpath.js engine. Accepted at registration; not yet honored at runtime (lights up in a follow-up phase of GROW-68).", "example": [ "Observation.status = 'final'" ], "items": { "maxLength": 1000, "minLength": 1, "type": "string" }, "maxItems": 10, "type": "array" }, "fieldFilters": { "additionalProperties": { "type": "string" }, "description": "Deprecated. Top-level string-equality filters against fields on the resource. Use `fhirpath` for new subscriptions.", "type": "object" }, "kind": { "enum": [ "criteria" ], "type": "string" }, "resourceType": { "enum": [ "Appointment", "QuestionnaireResponse", "Patient", "Encounter", "Observation", "Communication" ], "type": "string" } }, "required": [ "kind", "resourceType" ], "type": "object" }, "CronTrigger": { "properties": { "expression": { "description": "Five-field cron expression interpreted in UTC. Validated with `cron-parser`. Accepted at registration; not yet honored at runtime (lights up in a follow-up phase of GROW-68).", "example": "*/15 * * * *", "maxLength": 120, "minLength": 1, "type": "string" }, "kind": { "enum": [ "template" ], "type": "string" }, "template": { "enum": [ "cron" ], "type": "string" } }, "required": [ "kind", "template", "expression" ], "type": "object" }, "DailyAtTrigger": { "properties": { "hourUtc": { "anyOf": [ { "enum": [ 7 ], "type": "number" }, { "enum": [ 9 ], "type": "number" }, { "enum": [ 17 ], "type": "number" } ] }, "kind": { "enum": [ "template" ], "type": "string" }, "template": { "enum": [ "daily_at" ], "type": "string" } }, "required": [ "kind", "template", "hourUtc" ], "type": "object" }, "Destination": { "description": "Where the webhook is delivered. `agent` runs an in-process LLM use case; `http` POSTs a signed body to your URL.", "discriminator": { "mapping": { "agent": "#/components/schemas/AgentDestination", "http": "#/components/schemas/HttpDestination" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/AgentDestination" }, { "$ref": "#/components/schemas/HttpDestination" } ] }, "EligibilityCheckRequest": { "properties": { "coverage_id": { "description": "Optional Coverage id. When provided, the engine looks this Coverage up directly; otherwise it picks the patient's most recent active Coverage.", "example": "cov-devon-anthem", "type": "string" }, "member_id": { "description": "Optional member id to verify against `Coverage.subscriberId`. Mismatch → `invalid_member_id` outcome.", "example": "ANTHEM87432119", "type": "string" }, "patient_id": { "description": "Canonical Patient id in the tenant chart. Required.", "example": "eb1f768e-226a-c047-0f2f-8331341167c2", "minLength": 1, "type": "string" }, "payer_id": { "description": "Optional payer hint. Currently informational only — the engine resolves payer from the Coverage.payor display.", "type": "string" } }, "required": [ "patient_id" ], "type": "object" }, "EligibilityPlan": { "properties": { "copay_usd": { "example": 35, "type": "number" }, "deductible_remaining_usd": { "example": 1250, "type": "number" }, "name": { "example": "Anthem PPO", "type": "string" }, "network": { "enum": [ "in-network", "out-of-network" ], "type": "string" } }, "required": [ "name", "network", "copay_usd", "deductible_remaining_usd" ], "type": "object" }, "EligibilityResult": { "properties": { "coverage_id": { "description": "Coverage resource id used for the check. `null` when no Coverage was on file.", "type": [ "string", "null" ] }, "member_id": { "description": "Member id from `Coverage.subscriberId`, falling back to the caller-supplied `member_id`.", "type": [ "string", "null" ] }, "message": { "description": "Human-readable summary the agent can drop straight into an SMS, email, or Slack message.", "type": "string" }, "patient_id": { "type": "string" }, "payer": { "description": "Display name of the payer from `Coverage.payor[0].display`. `null` when no Coverage was on file.", "example": "Anthem", "type": [ "string", "null" ] }, "plan": { "allOf": [ { "$ref": "#/components/schemas/EligibilityPlan" }, { "description": "Present only when `status === \"active\"`." } ] }, "reason": { "description": "Reason chip for non-active outcomes (`plan-terminated`, `invalid-member-id`, `no-coverage-on-file`). Empty string when `status === \"active\"`.", "example": "plan-terminated", "type": "string" }, "source": { "description": "Provenance marker. Always `bbe-mock-270-271` — this endpoint never speaks to a real clearinghouse.", "enum": [ "bbe-mock-270-271" ], "type": "string" }, "status": { "description": "Decision outcome. `active` means the patient is covered; the other three are failure modes with distinct follow-up paths.", "enum": [ "active", "plan_terminated", "invalid_member_id", "no_coverage_on_file" ], "type": "string" }, "transaction_id": { "description": "Mock 271 transaction id — reference in follow-up Tasks for audit.", "example": "elig-9k2pq3xy", "type": "string" } }, "required": [ "status", "patient_id", "coverage_id", "payer", "member_id", "reason", "message", "transaction_id", "source" ], "type": "object" }, "FhirResource": { "additionalProperties": { }, "description": "An opaque FHIR R4 resource. Blue Banana validates `resourceType` against the supported set but otherwise stores resources as JSON. Refer to https://hl7.org/fhir/R4/ for the canonical schema of each `resourceType`.", "properties": { "id": { "type": "string" }, "resourceType": { "$ref": "#/components/schemas/ResourceType" } }, "required": [ "resourceType" ], "type": "object" }, "HttpDestination": { "properties": { "headers": { "additionalProperties": { "type": "string" }, "description": "Static headers added to every delivery (max 8 entries). `Content-Type`, `X-Keragon-Signature`, and `X-Keragon-Delivery` are reserved.", "type": "object" }, "kind": { "enum": [ "http" ], "type": "string" }, "url": { "description": "Public HTTPS URL. Loopback and private/literal IPs are rejected.", "format": "uri", "type": "string" } }, "required": [ "kind", "url" ], "type": "object" }, "InspectorInboundBody": { "additionalProperties": { }, "type": "object" }, "IntakeFormId": { "description": "Identifier of a canned intake form. Forms are code-defined; see `lib/intake/forms.ts`.", "enum": [ "patient_intake", "appointment_request", "insurance_update" ], "type": "string" }, "IntakeSubmissionEvent": { "properties": { "fired_at": { "format": "date-time", "type": "string" }, "type": { "enum": [ "intake.submission.created" ], "type": "string" } }, "required": [ "type", "fired_at" ], "type": "object" }, "IntakeSubmissionRequest": { "additionalProperties": { }, "description": "Per-form fields validated against the form's Zod schema. Unknown fields are rejected.", "example": { "consent": true, "dob": "1989-04-22", "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "phone": "+15555550100", "reason_for_visit": "annual physical" }, "type": "object" }, "IntakeSubmissionResponse": { "properties": { "submission_id": { "example": "isub_8c2e…", "type": "string" } }, "required": [ "submission_id" ], "type": "object" }, "IntakeSubscription": { "properties": { "createdAt": { "format": "date-time", "type": "string" }, "enabled": { "type": "boolean" }, "formId": { "$ref": "#/components/schemas/IntakeFormId" }, "id": { "example": "isub_1c7a0a3e-…", "type": "string" }, "name": { "type": "string" }, "ownerUserId": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "id", "formId", "ownerUserId", "name", "enabled", "url", "createdAt", "updatedAt" ], "type": "object" }, "IntakeSubscriptionCreateRequest": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "url": { "description": "Public HTTPS URL where deliveries are POSTed. Validated at registration by the SSRF guard (`lib/webhook/url-guard.ts`); loopback and private/literal IPs are rejected.", "format": "uri", "maxLength": 2000, "minLength": 1, "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "IntakeSubscriptionPatchRequest": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" } }, "type": "object" }, "IntakeSubscriptionWithSecret": { "allOf": [ { "$ref": "#/components/schemas/IntakeSubscription" }, { "properties": { "secret": { "description": "HMAC signing secret. Returned exactly once at create — store it now.", "example": "0123abcd…", "type": "string" } }, "required": [ "secret" ], "type": "object" } ] }, "IntakeSubscriptionsList": { "properties": { "subscriptions": { "items": { "$ref": "#/components/schemas/IntakeSubscription" }, "type": "array" } }, "required": [ "subscriptions" ], "type": "object" }, "OperationOutcome": { "description": "FHIR R4 `OperationOutcome`. Every error response from `/api/fhir/r4/*` and most platform routes uses this shape.", "properties": { "issue": { "items": { "$ref": "#/components/schemas/OperationOutcomeIssue" }, "minItems": 1, "type": "array" }, "resourceType": { "enum": [ "OperationOutcome" ], "type": "string" } }, "required": [ "resourceType", "issue" ], "type": "object" }, "OperationOutcomeIssue": { "properties": { "code": { "enum": [ "invalid", "security", "forbidden", "not-found", "conflict", "too-costly", "business-rule", "throttled", "exception", "transient" ], "type": "string" }, "diagnostics": { "type": "string" }, "expression": { "items": { "type": "string" }, "type": "array" }, "severity": { "enum": [ "fatal", "error", "warning", "information" ], "type": "string" } }, "required": [ "severity", "code" ], "type": "object" }, "PatientSimEmailRequest": { "properties": { "body": { "maxLength": 40000, "minLength": 1, "type": "string" }, "from": { "maxLength": 254, "minLength": 1, "type": "string" }, "subject": { "maxLength": 256, "type": "string" }, "to": { "maxLength": 254, "minLength": 3, "type": "string" } }, "required": [ "to", "body" ], "type": "object" }, "PatientSimMessageRecorded": { "properties": { "message_id": { "example": "b0a4d7f1-…", "type": "string" }, "normalized_to": { "example": "+15551234567", "type": "string" }, "patient_id": { "example": "eb1f768e-226a-c047-0f2f-8331341167c2", "type": "string" } }, "required": [ "message_id", "patient_id", "normalized_to" ], "type": "object" }, "PatientSimSmsRequest": { "properties": { "body": { "example": "Reminder: your visit is at 2:30pm.", "maxLength": 4000, "minLength": 1, "type": "string" }, "from": { "example": "+15550100", "maxLength": 64, "minLength": 1, "type": "string" }, "to": { "example": "+15551234567", "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "to", "body" ], "type": "object" }, "ResourceType": { "description": "A FHIR R4 resource type supported by Blue Banana EHR. See the FHIR spec at https://hl7.org/fhir/R4/resourcelist.html for the canonical shapes — Blue Banana stores and returns them verbatim.", "enum": [ "Patient", "Encounter", "Observation", "Condition", "MedicationRequest", "MedicationAdministration", "AllergyIntolerance", "Immunization", "Procedure", "DiagnosticReport", "CarePlan", "CareTeam", "Goal", "Practitioner", "Organization", "Location", "Device", "ImagingStudy", "Coverage", "Claim", "ExplanationOfBenefit", "SupplyDelivery", "Appointment", "Schedule", "Slot", "DocumentReference", "Communication", "Provenance", "QuestionnaireResponse", "Task", "ServiceRequest" ], "type": "string" }, "Subscription": { "description": "A webhook subscription. Returned by all subscription endpoints.", "properties": { "created_at": { "format": "date-time", "type": "string" }, "destination": { "$ref": "#/components/schemas/Destination" }, "enabled": { "type": "boolean" }, "id": { "example": "sub_1c7a0a3e-8f99-41a9-bf8b-2f1b0d8c0a01", "type": "string" }, "name": { "maxLength": 80, "type": "string" }, "tenant": { "example": "dev-abc123", "type": "string" }, "trigger": { "$ref": "#/components/schemas/Trigger" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "tenant", "name", "enabled", "trigger", "destination", "created_at", "updated_at" ], "type": "object" }, "SubscriptionRequest": { "description": "Create or update a subscription. The HTTP secret is generated server-side and returned exactly once on the create response.", "properties": { "destination": { "$ref": "#/components/schemas/Destination" }, "enabled": { "type": "boolean" }, "name": { "maxLength": 80, "minLength": 1, "type": "string" }, "trigger": { "$ref": "#/components/schemas/Trigger" } }, "required": [ "name", "trigger", "destination" ], "type": "object" }, "SubscriptionWithSecret": { "allOf": [ { "$ref": "#/components/schemas/Subscription" }, { "properties": { "secret_view": { "description": "The webhook signing secret (hex, 64 chars). Returned ONLY on create or on agent→http transition. Capture it now — you cannot read it again.", "type": "string" } }, "type": "object" } ], "description": "A webhook subscription. Returned by all subscription endpoints." }, "SubscriptionsList": { "properties": { "subscriptions": { "items": { "$ref": "#/components/schemas/Subscription" }, "type": "array" } }, "required": [ "subscriptions" ], "type": "object" }, "TemplateEvent": { "properties": { "fired_at": { "format": "date-time", "type": "string" }, "trigger": { "anyOf": [ { "properties": { "kind": { "enum": [ "template" ], "type": "string" }, "offsetMinutes": { "type": "number" }, "template": { "enum": [ "appointment_reminder" ], "type": "string" } }, "required": [ "kind", "template", "offsetMinutes" ], "type": "object" }, { "properties": { "kind": { "enum": [ "template" ], "type": "string" }, "offsetMinutes": { "type": "number" }, "template": { "enum": [ "appointment_no_show" ], "type": "string" } }, "required": [ "kind", "template", "offsetMinutes" ], "type": "object" }, { "properties": { "hourUtc": { "type": "number" }, "kind": { "enum": [ "template" ], "type": "string" }, "template": { "enum": [ "daily_at" ], "type": "string" } }, "required": [ "kind", "template", "hourUtc" ], "type": "object" } ] }, "type": { "enum": [ "template.fired" ], "type": "string" } }, "required": [ "type", "fired_at", "trigger" ], "type": "object" }, "Trigger": { "description": "When a subscription should fire. `criteria` matches FHIR writes by `fieldFilters` (deprecated) or `fhirpath` (preferred). `template` schedules fires: `appointment_reminder` / `appointment_no_show` are anchored to an Appointment, `daily_at` fires at a fixed UTC hour, and `cron` accepts a free-form 5-field UTC schedule.", "discriminator": { "mapping": { "criteria": "#/components/schemas/CriteriaTrigger", "template": "#/components/schemas/CronTrigger" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/CriteriaTrigger" }, { "$ref": "#/components/schemas/AppointmentReminderTrigger" }, { "$ref": "#/components/schemas/AppointmentNoShowTrigger" }, { "$ref": "#/components/schemas/DailyAtTrigger" }, { "$ref": "#/components/schemas/CronTrigger" } ] }, "WebhookCriteriaPayload": { "description": "Payload for `criteria.matched` deliveries. The resource is the just-written FHIR resource, stamped with the synthetic-data extension.", "properties": { "data": { "properties": { "context": { "additionalProperties": { }, "type": "object" }, "resource": { "$ref": "#/components/schemas/FhirResource" } }, "required": [ "resource", "context" ], "type": "object" }, "delivery_id": { "type": "string" }, "event": { "$ref": "#/components/schemas/CriteriaEvent" }, "subscription_id": { "type": "string" }, "tenant": { "type": "string" } }, "required": [ "delivery_id", "subscription_id", "tenant", "event", "data" ], "type": "object" }, "WebhookIntakePayload": { "description": "Payload for `intake.submission.created` deliveries. `values` holds the validated form payload — schema depends on `form_id`.", "properties": { "data": { "properties": { "submission": { "properties": { "id": { "type": "string" }, "submitted_at": { "format": "date-time", "type": "string" }, "values": { "additionalProperties": { }, "type": "object" } }, "required": [ "id", "submitted_at", "values" ], "type": "object" } }, "required": [ "submission" ], "type": "object" }, "delivery_id": { "type": "string" }, "event": { "$ref": "#/components/schemas/IntakeSubmissionEvent" }, "form_id": { "type": "string" }, "subscription_id": { "type": "string" } }, "required": [ "delivery_id", "subscription_id", "form_id", "event", "data" ], "type": "object" }, "WebhookTemplatePayload": { "description": "Payload for `template.fired` deliveries. For Appointment-anchored templates the resource is the Appointment; for `daily_at` it is `null`.", "properties": { "data": { "properties": { "context": { "additionalProperties": { }, "type": "object" }, "resource": { "allOf": [ { "$ref": "#/components/schemas/FhirResource" }, { "type": [ "object", "null" ] } ] } }, "required": [ "resource", "context" ], "type": "object" }, "delivery_id": { "type": "string" }, "event": { "$ref": "#/components/schemas/TemplateEvent" }, "subscription_id": { "type": "string" }, "tenant": { "type": "string" } }, "required": [ "delivery_id", "subscription_id", "tenant", "event", "data" ], "type": "object" } }, "securitySchemes": { "bearerApiKey": { "bearerFormat": "bb_xxxxxxxxxxxx", "description": "Better Auth–issued API key, returned exactly once when the user mints it on `/account`. Send as `Authorization: Bearer bb_…`. The key resolves to the user's `dev-` tenant; responses echo it back as `X-EHR-Tenant-Resolved`.\n\nRate limited per key (30 req/min production, 10 req/min playground) with a 50 req/min tenant ceiling. See the top-level \"Rate limits\" section.", "scheme": "bearer", "type": "http" } } }, "info": { "contact": { "name": "Keragon", "url": "https://bluebananaehr.com" }, "description": "Blue Banana EHR is a synthetic FHIR R4 sandbox for developers building integrations. Every resource is generated by [Synthea](https://github.com/synthetichealth/synthea) and carries the `http://bluebananaehr.com/synthetic-data` extension — no real PHI.\n\n**The supported surface today is FHIR R4 CRUD plus webhook subscriptions and intake forms.** Standard CRUD at `/api/fhir/r4/*`; refer to https://hl7.org/fhir/R4/ for resource schemas — this spec describes Blue Banana-specific deltas. The Subscriptions and Intake-forms surfaces are stable: both accept bearer-API-key auth and deliver signed webhooks end-to-end.\n\nThe Agent runtime remains experimental — see the group at the bottom labeled `Experimental — Agent runtime (not currently working)`.\n\nEvery authed request needs `Authorization: Bearer bb_…` (an API key minted on `/account`). The caller's tenant is derived from the key; successful responses echo it back as `X-EHR-Tenant-Resolved`.\n\n## Rate limits\n\nTwo layers cap traffic:\n\n- **Per API key** — `30 req/min` for user-named (production) keys, `10 req/min` for playground keys auto-managed by `/docs/api`. Limits the blast radius of a leaked key.\n- **Per tenant** — `50 req/min` across all keys for the same developer tenant (`200` lifetime writes, `20 LLM calls/hour`).\n\nEvery successful response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (Unix epoch seconds when the per-key window resets). A `429` response is a FHIR `OperationOutcome` with `severity: error` / `code: throttled` and adds a `Retry-After` header (seconds until the per-key window resets).", "title": "Blue Banana EHR API", "version": "0.1.0" }, "openapi": "3.1.0", "paths": { "/api/agent": { "post": { "deprecated": true, "description": "> ⚠️ **Not currently working for external developers.** Documented for forward compatibility; endpoint either rejects bearer-API-key auth or returns a validation error against every published example. Do not build against this surface yet.\n\nStreams the agent run as Server-Sent Events. The body specifies the use case; the tenant is derived from the caller's API key. The server replies with `Content-Type: text/event-stream` and emits `text-delta`, `tool-call`, `tool-result`, and `done`/`error` frames. See [the streaming guide](/docs/streaming) for the full event grammar.\n\nThe response body type below is `text/event-stream` and renders as opaque in most OpenAPI viewers — Scalar will show a hint to use the streaming guide.", "requestBody": { "content": { "application/json": { "examples": { "default": { "summary": "Free-form prompt", "value": { "prompt": "Summarize the chart for John Smith.", "useCase": "chart-summary" } } }, "schema": { "$ref": "#/components/schemas/AgentInvokeRequest" } } } }, "responses": { "200": { "content": { "text/event-stream": { "schema": { "description": "SSE wire format. Each event is one `data: {...}\\n\\n` frame; see /docs/streaming for the JSON shapes.", "type": "string" } } }, "description": "Streaming SSE response. See `/docs/streaming` for event ordering." }, "400": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Malformed body / unknown use case." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Missing/invalid Authorization." }, "422": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Use case is disabled in v1." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate, write, or LLM quota exceeded." }, "503": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "AI Gateway not configured on the server." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Run an agent use case (SSE)", "tags": [ "Experimental — Agent runtime (not currently working)" ] } }, "/api/agent/runs": { "get": { "deprecated": true, "description": "> ⚠️ **Not currently working for external developers.** Documented for forward compatibility; endpoint either rejects bearer-API-key auth or returns a validation error against every published example. Do not build against this surface yet.\n\nSnapshot of the most recent webhook-fired agent runs for the current tenant. Used by the playground for initial-load state before subscribing to `/api/agent/runs/stream`.", "parameters": [ { "description": "Max runs to return (default 20, max 100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "default": { "summary": "Two recent runs", "value": { "runs": [ { "created_at": "2026-05-19T10:00:00.000Z", "delivery_id": "del_a1b2c3d4-0000-4444-8888-111122223333", "event_fired_at": "2026-05-19T10:00:00.000Z", "event_type": "criteria.matched", "finished_at": "2026-05-19T10:00:09.456Z", "fire_at": "2026-05-19T10:00:00.000Z", "started_at": "2026-05-19T10:00:01.123Z", "status": "succeeded", "subscription_id": "sub_2f1b0d8c-0a01-41a9-bf8b-1c7a0a3e8f99", "tool_calls": [ { "args": { "id": "eb1f768e-226a-c047-0f2f-8331341167c2" }, "id": "tc_01", "name": "read_patient", "result": { "dob": "1948-01-11", "name": "John Smith" } } ], "transcript": "Patient John Smith has an appointment in 60 minutes. Recent labs: CBC normal; A1c 6.8 (last 2025-12-04).", "use_case": "appointment-prep" }, { "created_at": "2026-05-19T10:05:00.000Z", "delivery_id": "del_d4e5f6a7-1111-4444-8888-222233334444", "event_fired_at": "2026-05-19T10:05:00.000Z", "event_type": "criteria.matched", "finished_at": null, "fire_at": "2026-05-19T10:05:00.000Z", "started_at": "2026-05-19T10:05:00.500Z", "status": "in_flight", "subscription_id": "sub_2f1b0d8c-0a01-41a9-bf8b-1c7a0a3e8f99", "tool_calls": [ ], "transcript": null, "use_case": "appointment-prep" } ] } } }, "schema": { "$ref": "#/components/schemas/AgentRunsList" } } }, "description": "Recent runs (newest first)." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Missing/invalid Authorization." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." }, "500": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Server error." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "List recent agent runs", "tags": [ "Experimental — Agent runtime (not currently working)" ] } }, "/api/agent/runs/stream": { "get": { "deprecated": true, "description": "> ⚠️ **Not currently working for external developers.** Documented for forward compatibility; endpoint either rejects bearer-API-key auth or returns a validation error against every published example. Do not build against this surface yet.\n\nLong-lived Server-Sent Events stream of webhook-fired agent runs for the current tenant. Emits `open`, `run-started`, `text-delta`, `tool-call`, `tool-result`, `run-done`, and `run-error` frames plus `: keepalive` heartbeats every 25s. See [the streaming guide](/docs/streaming) for the full grammar.", "responses": { "200": { "content": { "text/event-stream": { "schema": { "description": "SSE frames. See /docs/streaming for the JSON event shapes.", "type": "string" } } }, "description": "Streaming SSE response." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Missing/invalid Authorization." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." }, "500": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Server error." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Subscribe to live agent run events (SSE)", "tags": [ "Experimental — Agent runtime (not currently working)" ] } }, "/api/eligibility/$check": { "post": { "description": "Deterministic eligibility lookup against the patient's most recent Coverage in the tenant chart. The decision is rules-based on Coverage status + (optional) member-id match, so repeated calls for the same patient return the same answer.\n\n**Decision matrix**:\n\n- No Coverage on file → `no_coverage_on_file`\n- `Coverage.status === \"cancelled\"` → `plan_terminated`\n- `member_id` supplied AND doesn't match `Coverage.subscriberId` → `invalid_member_id`\n- otherwise → `active` (with mock plan / copay / deductible)\n\nAlways responds 200 — failure outcomes ride in the body's `status` field. The endpoint is part of the BBE live surface used by the F.1 Eligibility Running Agent (`check_eligibility` tool).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EligibilityCheckRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EligibilityResult" } } }, "description": "Decision returned. Inspect `status` for the outcome." }, "400": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Malformed body (missing `patient_id`, wrong type)." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Missing/invalid Authorization." }, "404": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Patient not found in this tenant." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." }, "500": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Server error (e.g. Coverage lookup failed)." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Run a mock 270/271 eligibility check", "tags": [ "Eligibility" ] } }, "/api/fhir/r4/Appointment": { "get": { "description": "Returns a FHIR `Bundle` of type `searchset`. Every dev tenant is seeded at signup with three near-future Appointments referencing the canonical patients — including John Smith. The prefilled `patient` parameter is John's UUID, so Try It returns those seeded rows immediately.", "parameters": [ { "description": "Filter to Appointments where any participant is this Patient. Defaults to John Smith.", "example": "eb1f768e-226a-c047-0f2f-8331341167c2", "in": "query", "name": "patient", "required": false, "schema": { "example": "eb1f768e-226a-c047-0f2f-8331341167c2", "type": "string" } }, { "description": "Filter to Appointments where any participant is this actor (Patient, Practitioner, etc.).", "in": "query", "name": "actor", "required": false, "schema": { "type": "string" } }, { "description": "Filter to Appointments performed by a given Practitioner. Accepts either a bare id (`demo-canonical-prac-chen`) or the typed reference form (`Practitioner/demo-canonical-prac-chen`).", "in": "query", "name": "practitioner", "required": false, "schema": { "type": "string" } }, { "description": "FHIR date-prefix expression (e.g. `ge2026-05-20`).", "in": "query", "name": "date", "required": false, "schema": { "type": "string" } }, { "description": "Filter by appointment status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "proposed", "pending", "booked", "arrived", "fulfilled", "cancelled", "noshow" ], "type": "string" } }, { "description": "Max entries to return.", "in": "query", "name": "_count", "required": false, "schema": { "maximum": 1000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/fhir+json": { "examples": { "emptyResult": { "summary": "No matches", "value": { "entry": [ ], "link": [ { "relation": "self", "url": "https://bluebananaehr.com/fhir/r4/Patient?family=NonExistent" } ], "resourceType": "Bundle", "total": 0, "type": "searchset" } }, "johnsAppointments": { "summary": "John Smith's upcoming Appointments", "value": { "entry": [ { "fullUrl": "https://bluebananaehr.com/fhir/r4/Appointment/demo-appt-1-abcd1234", "resource": { "description": "Demo appointment for John Smith", "end": "2026-05-20T18:08:45Z", "extension": [ { "url": "http://bluebananaehr.com/synthetic-data", "valueBoolean": true } ], "id": "demo-appt-1-abcd1234", "participant": [ { "actor": { "display": "John Smith", "reference": "Patient/eb1f768e-226a-c047-0f2f-8331341167c2" }, "status": "accepted" } ], "resourceType": "Appointment", "start": "2026-05-20T17:38:45Z", "status": "booked" }, "search": { "mode": "match" } } ], "link": [ { "relation": "self", "url": "https://bluebananaehr.com/fhir/r4/Appointment?patient=eb1f768e-226a-c047-0f2f-8331341167c2" } ], "resourceType": "Bundle", "total": 1, "type": "searchset" } } }, "schema": { "$ref": "#/components/schemas/Bundle" } } }, "description": "Searchset bundle." }, "400": { "content": { "application/fhir+json": { "examples": { "validation": { "summary": "422", "value": { "issue": [ { "code": "business-rule", "diagnostics": "criteria.resourceType must be one of: Appointment, QuestionnaireResponse, Patient, Encounter, Observation, Communication", "severity": "error" } ], "resourceType": "OperationOutcome" } } }, "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Malformed search param." }, "401": { "content": { "application/fhir+json": { "examples": { "unauthorized": { "summary": "401", "value": { "issue": [ { "code": "security", "diagnostics": "Missing Authorization header. Send `Authorization: Bearer bb_…`.", "severity": "error" } ], "resourceType": "OperationOutcome" } } }, "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Unauthorized." }, "403": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Forbidden tenant." }, "429": { "content": { "application/fhir+json": { "examples": { "throttled": { "summary": "429", "value": { "issue": [ { "code": "throttled", "diagnostics": "Visitor tenants are limited to 50 requests per minute. Try again in 30s.", "severity": "error" } ], "resourceType": "OperationOutcome" } } }, "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "List John's upcoming appointments", "tags": [ "FHIR — Appointment" ] } }, "/api/fhir/r4/Appointment/{id}": { "get": { "description": "Returns one Appointment resource. Seed Appointment IDs include a random suffix per tenant (e.g. `demo-appt-1-abcd1234`) — grab one from the search endpoint above and paste it here.", "parameters": [ { "description": "Appointment id. Get one from `GET /api/fhir/r4/Appointment?patient=…`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirResource" } } }, "description": "Appointment resource." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Unauthorized." }, "403": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Forbidden." }, "404": { "content": { "application/fhir+json": { "examples": { "notFound": { "summary": "404", "value": { "issue": [ { "code": "not-found", "diagnostics": "Patient/abc123 not found in tenant dev-xyz", "severity": "error" } ], "resourceType": "OperationOutcome" } } }, "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Not found." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Read a single Appointment", "tags": [ "FHIR — Appointment" ] } }, "/api/fhir/r4/Patient": { "get": { "description": "Returns a FHIR `Bundle` of type `searchset`. The reference patient **John Smith** is in canonical seed data, so `family=Smith` always returns at least one row. Pair `_count` with `_id` or name/birthdate filters to narrow.", "parameters": [ { "description": "Max entries to return.", "example": 5, "in": "query", "name": "_count", "required": false, "schema": { "example": 5, "maximum": 1000, "minimum": 1, "type": "integer" } }, { "description": "Filter by Patient id.", "in": "query", "name": "_id", "required": false, "schema": { "type": "string" } }, { "description": "Family name search.", "example": "Smith", "in": "query", "name": "family", "required": false, "schema": { "example": "Smith", "type": "string" } }, { "description": "Given name search.", "in": "query", "name": "given", "required": false, "schema": { "type": "string" } }, { "description": "FHIR date-prefix expression (e.g. `gt1970-01-01`).", "in": "query", "name": "birthdate", "required": false, "schema": { "type": "string" } }, { "description": "Filter by administrative gender.", "in": "query", "name": "gender", "required": false, "schema": { "enum": [ "male", "female", "other", "unknown" ], "type": "string" } } ], "responses": { "200": { "content": { "application/fhir+json": { "examples": { "emptyResult": { "summary": "No matches", "value": { "entry": [ ], "link": [ { "relation": "self", "url": "https://bluebananaehr.com/fhir/r4/Patient?family=NonExistent" } ], "resourceType": "Bundle", "total": 0, "type": "searchset" } }, "johnSmith": { "summary": "Patient?family=Smith", "value": { "entry": [ { "fullUrl": "https://bluebananaehr.com/fhir/r4/Patient/eb1f768e-226a-c047-0f2f-8331341167c2", "resource": { "birthDate": "1948-01-11", "extension": [ { "url": "http://bluebananaehr.com/synthetic-data", "valueBoolean": true } ], "gender": "male", "id": "eb1f768e-226a-c047-0f2f-8331341167c2", "name": [ { "family": "Smith", "given": [ "John" ], "use": "official" } ], "resourceType": "Patient" }, "search": { "mode": "match" } } ], "link": [ { "relation": "self", "url": "https://bluebananaehr.com/fhir/r4/Patient?family=Smith" } ], "resourceType": "Bundle", "total": 1, "type": "searchset" } } }, "schema": { "$ref": "#/components/schemas/Bundle" } } }, "description": "Searchset bundle." }, "400": { "content": { "application/fhir+json": { "examples": { "validation": { "summary": "422", "value": { "issue": [ { "code": "business-rule", "diagnostics": "criteria.resourceType must be one of: Appointment, QuestionnaireResponse, Patient, Encounter, Observation, Communication", "severity": "error" } ], "resourceType": "OperationOutcome" } } }, "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Malformed search param." }, "401": { "content": { "application/fhir+json": { "examples": { "unauthorized": { "summary": "401", "value": { "issue": [ { "code": "security", "diagnostics": "Missing Authorization header. Send `Authorization: Bearer bb_…`.", "severity": "error" } ], "resourceType": "OperationOutcome" } } }, "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Unauthorized." }, "403": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Forbidden tenant." }, "429": { "content": { "application/fhir+json": { "examples": { "throttled": { "summary": "429", "value": { "issue": [ { "code": "throttled", "diagnostics": "Visitor tenants are limited to 50 requests per minute. Try again in 30s.", "severity": "error" } ], "resourceType": "OperationOutcome" } } }, "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Search patients", "tags": [ "FHIR — Patient" ] } }, "/api/fhir/r4/Patient/{id}": { "get": { "description": "Returns one Patient resource as `application/fhir+json`. The default `id` is the reference patient John Smith — try as-is to see the seeded record, or swap with any id returned by the search endpoint above.", "parameters": [ { "description": "Patient id. Defaults to John Smith — the canonical reference patient seeded into every dev tenant.", "example": "eb1f768e-226a-c047-0f2f-8331341167c2", "in": "path", "name": "id", "required": true, "schema": { "example": "eb1f768e-226a-c047-0f2f-8331341167c2", "type": "string" } } ], "responses": { "200": { "content": { "application/fhir+json": { "examples": { "johnSmith": { "summary": "John Smith", "value": { "birthDate": "1948-01-11", "extension": [ { "url": "http://bluebananaehr.com/synthetic-data", "valueBoolean": true } ], "gender": "male", "id": "eb1f768e-226a-c047-0f2f-8331341167c2", "name": [ { "family": "Smith", "given": [ "John" ], "use": "official" } ], "resourceType": "Patient" } } }, "schema": { "$ref": "#/components/schemas/FhirResource" } } }, "description": "Patient resource." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Unauthorized." }, "403": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Forbidden." }, "404": { "content": { "application/fhir+json": { "examples": { "notFound": { "summary": "404", "value": { "issue": [ { "code": "not-found", "diagnostics": "Patient/abc123 not found in tenant dev-xyz", "severity": "error" } ], "resourceType": "OperationOutcome" } } }, "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Not found." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Read John Smith's record", "tags": [ "FHIR — Patient" ] } }, "/api/fhir/r4/Patient/{id}/$everything": { "get": { "description": "Standard FHIR Patient `$everything` operation. Returns a Bundle (searchset) containing the Patient and every resource referencing it via `subject` or `patient`. Defaulted to John Smith's full chart — multiple years of synthetic encounters, observations, conditions, and meds. See https://hl7.org/fhir/R4/operation-patient-everything.html for the canonical definition.", "parameters": [ { "description": "Patient id. Defaults to John Smith — the canonical reference patient seeded into every dev tenant.", "example": "eb1f768e-226a-c047-0f2f-8331341167c2", "in": "path", "name": "id", "required": true, "schema": { "example": "eb1f768e-226a-c047-0f2f-8331341167c2", "type": "string" } } ], "responses": { "200": { "content": { "application/fhir+json": { "examples": { "default": { "summary": "Patient with two related resources", "value": { "entry": [ { "fullUrl": "https://bluebananaehr.com/fhir/r4/Patient/eb1f768e-226a-c047-0f2f-8331341167c2", "resource": { "extension": [ { "url": "http://bluebananaehr.com/synthetic-data", "valueBoolean": true } ], "id": "eb1f768e-226a-c047-0f2f-8331341167c2", "name": [ { "family": "Smith", "given": [ "John" ] } ], "resourceType": "Patient" } }, { "fullUrl": "https://bluebananaehr.com/fhir/r4/Encounter/enc_001", "resource": { "extension": [ { "url": "http://bluebananaehr.com/synthetic-data", "valueBoolean": true } ], "id": "enc_001", "resourceType": "Encounter", "status": "finished", "subject": { "reference": "Patient/eb1f768e-226a-c047-0f2f-8331341167c2" } } }, { "fullUrl": "https://bluebananaehr.com/fhir/r4/Observation/obs_001", "resource": { "code": { "coding": [ { "code": "8480-6", "display": "Systolic BP", "system": "http://loinc.org" } ] }, "extension": [ { "url": "http://bluebananaehr.com/synthetic-data", "valueBoolean": true } ], "id": "obs_001", "resourceType": "Observation", "status": "final", "subject": { "reference": "Patient/eb1f768e-226a-c047-0f2f-8331341167c2" }, "valueQuantity": { "unit": "mmHg", "value": 128 } } } ], "resourceType": "Bundle", "total": 3, "type": "searchset" } } }, "schema": { "$ref": "#/components/schemas/Bundle" } } }, "description": "Bundle with the Patient + every related resource." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Unauthorized." }, "403": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Forbidden." }, "404": { "content": { "application/fhir+json": { "examples": { "notFound": { "summary": "404", "value": { "issue": [ { "code": "not-found", "diagnostics": "Patient/abc123 not found in tenant dev-xyz", "severity": "error" } ], "resourceType": "OperationOutcome" } } }, "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Patient not found." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Patient $everything (full chart)", "tags": [ "FHIR — Patient" ] } }, "/api/fhir/r4/metadata": { "get": { "description": "Standard FHIR `CapabilityStatement`. Lists every supported resource type, its allowed interactions, and the search params Blue Banana implements. Stamped with the synthetic-data extension.", "parameters": [ ], "responses": { "200": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/CapabilityStatement" } } }, "description": "CapabilityStatement." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Unauthorized." }, "403": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Forbidden." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "CapabilityStatement", "tags": [ "FHIR — Other resources" ] } }, "/api/fhir/r4/{resourceType}": { "get": { "description": "Returns a FHIR `Bundle` of type `searchset`. The shared search params below are the union of what Blue Banana supports — not every param is meaningful for every resource type. Unknown params return 400.\n\nResource shapes follow FHIR R4 — see https://hl7.org/fhir/R4/resourcelist.html.\n\n_Patient and Appointment have their own dedicated groups above._", "parameters": [ { "description": "FHIR R4 resource type (excluding Patient and Appointment — those have their own groups above). See https://hl7.org/fhir/R4/resourcelist.html.", "in": "path", "name": "resourceType", "required": true, "schema": { "enum": [ "Encounter", "Observation", "Condition", "MedicationRequest", "MedicationAdministration", "AllergyIntolerance", "Immunization", "Procedure", "DiagnosticReport", "CarePlan", "CareTeam", "Goal", "Practitioner", "Organization", "Location", "Device", "ImagingStudy", "Coverage", "Claim", "ExplanationOfBenefit", "SupplyDelivery", "Schedule", "Slot", "DocumentReference", "Communication", "Provenance", "QuestionnaireResponse", "Task", "ServiceRequest" ], "type": "string" } }, { "description": "Max entries to return.", "in": "query", "name": "_count", "required": false, "schema": { "maximum": 1000, "minimum": 1, "type": "integer" } }, { "description": "Filter by resource id.", "in": "query", "name": "_id", "required": false, "schema": { "type": "string" } }, { "description": "FHIR date-prefix expression (e.g. `gt2026-01-01`).", "in": "query", "name": "_lastUpdated", "required": false, "schema": { "type": "string" } }, { "description": "Forward include reference (e.g. `Observation:subject`).", "in": "query", "name": "_include", "required": false, "schema": { "type": "string" } }, { "description": "Reverse include reference.", "in": "query", "name": "_revinclude", "required": false, "schema": { "type": "string" } }, { "description": "Filter to resources where `subject` or `patient` references this Patient id.", "in": "query", "name": "patient", "required": false, "schema": { "type": "string" } }, { "description": "Alias for `patient` on resources that use `subject`.", "in": "query", "name": "subject", "required": false, "schema": { "type": "string" } }, { "description": "Token search against the resource code (e.g. LOINC, SNOMED).", "in": "query", "name": "code", "required": false, "schema": { "type": "string" } }, { "description": "Token search against the resource category.", "in": "query", "name": "category", "required": false, "schema": { "type": "string" } }, { "description": "Token search against the resource status.", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/fhir+json": { "examples": { "emptyResult": { "summary": "No matches", "value": { "entry": [ ], "link": [ { "relation": "self", "url": "https://bluebananaehr.com/fhir/r4/Patient?family=NonExistent" } ], "resourceType": "Bundle", "total": 0, "type": "searchset" } } }, "schema": { "$ref": "#/components/schemas/Bundle" } } }, "description": "Searchset bundle." }, "400": { "content": { "application/fhir+json": { "examples": { "validation": { "summary": "422", "value": { "issue": [ { "code": "business-rule", "diagnostics": "criteria.resourceType must be one of: Appointment, QuestionnaireResponse, Patient, Encounter, Observation, Communication", "severity": "error" } ], "resourceType": "OperationOutcome" } } }, "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Malformed search param." }, "401": { "content": { "application/fhir+json": { "examples": { "unauthorized": { "summary": "401", "value": { "issue": [ { "code": "security", "diagnostics": "Missing Authorization header. Send `Authorization: Bearer bb_…`.", "severity": "error" } ], "resourceType": "OperationOutcome" } } }, "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Unauthorized." }, "403": { "content": { "application/fhir+json": { "examples": { "forbidden": { "summary": "403", "value": { "issue": [ { "code": "forbidden", "diagnostics": "Your API key resolves but is not authorized for tenant `qa-acme`.", "severity": "error" } ], "resourceType": "OperationOutcome" } } }, "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Forbidden tenant." }, "404": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Unknown resource type." }, "429": { "content": { "application/fhir+json": { "examples": { "throttled": { "summary": "429", "value": { "issue": [ { "code": "throttled", "diagnostics": "Visitor tenants are limited to 50 requests per minute. Try again in 30s.", "severity": "error" } ], "resourceType": "OperationOutcome" } } }, "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Search resources of a given type", "tags": [ "FHIR — Other resources" ] }, "post": { "description": "Create a new resource of the given type. The server assigns an `id` if you do not supply one, stamps the synthetic-data extension, and returns the created resource plus a `Location: /fhir/r4/{Type}/{id}` header. Triggers any matching subscription `criteria` and (for `Appointment`, see the dedicated group above) spawns time-anchored `template` deliveries.\n\nThe example bodies reference the canonical John Smith — `Patient/eb1f768e-…` — so a POST against any of them links the new resource to the seed patient.", "parameters": [ { "description": "FHIR R4 resource type (excluding Patient and Appointment — those have their own groups above). See https://hl7.org/fhir/R4/resourcelist.html.", "in": "path", "name": "resourceType", "required": true, "schema": { "enum": [ "Encounter", "Observation", "Condition", "MedicationRequest", "MedicationAdministration", "AllergyIntolerance", "Immunization", "Procedure", "DiagnosticReport", "CarePlan", "CareTeam", "Goal", "Practitioner", "Organization", "Location", "Device", "ImagingStudy", "Coverage", "Claim", "ExplanationOfBenefit", "SupplyDelivery", "Schedule", "Slot", "DocumentReference", "Communication", "Provenance", "QuestionnaireResponse", "Task", "ServiceRequest" ], "type": "string" } } ], "requestBody": { "content": { "application/fhir+json": { "examples": { "allergyIntolerance": { "summary": "AllergyIntolerance (penicillin for John)", "value": { "clinicalStatus": { "coding": [ { "code": "active", "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical" } ] }, "code": { "coding": [ { "code": "763875007", "display": "Penicillin", "system": "http://snomed.info/sct" } ] }, "patient": { "reference": "Patient/eb1f768e-226a-c047-0f2f-8331341167c2" }, "recordedDate": "2026-05-19", "resourceType": "AllergyIntolerance" } }, "condition": { "summary": "Condition (type 2 diabetes for John)", "value": { "clinicalStatus": { "coding": [ { "code": "active", "system": "http://terminology.hl7.org/CodeSystem/condition-clinical" } ] }, "code": { "coding": [ { "code": "44054006", "display": "Type 2 diabetes mellitus", "system": "http://snomed.info/sct" } ] }, "recordedDate": "2026-05-19", "resourceType": "Condition", "subject": { "reference": "Patient/eb1f768e-226a-c047-0f2f-8331341167c2" } } }, "encounter": { "summary": "Encounter (ambulatory for John)", "value": { "class": { "code": "AMB", "display": "ambulatory", "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode" }, "period": { "end": "2026-05-19T09:30:00Z", "start": "2026-05-19T09:00:00Z" }, "resourceType": "Encounter", "status": "finished", "subject": { "reference": "Patient/eb1f768e-226a-c047-0f2f-8331341167c2" } } }, "immunization": { "summary": "Immunization (COVID mRNA for John)", "value": { "occurrenceDateTime": "2026-04-15", "patient": { "reference": "Patient/eb1f768e-226a-c047-0f2f-8331341167c2" }, "resourceType": "Immunization", "status": "completed", "vaccineCode": { "coding": [ { "code": "208", "display": "COVID-19 mRNA", "system": "http://hl7.org/fhir/sid/cvx" } ] } } }, "medicationRequest": { "summary": "MedicationRequest (metformin for John)", "value": { "authoredOn": "2026-05-19", "intent": "order", "medicationCodeableConcept": { "coding": [ { "code": "860975", "display": "metformin 500 MG Oral Tablet", "system": "http://www.nlm.nih.gov/research/umls/rxnorm" } ] }, "resourceType": "MedicationRequest", "status": "active", "subject": { "reference": "Patient/eb1f768e-226a-c047-0f2f-8331341167c2" } } }, "observation": { "summary": "Observation (A1c for John)", "value": { "code": { "coding": [ { "code": "4548-4", "display": "Hemoglobin A1c", "system": "http://loinc.org" } ] }, "effectiveDateTime": "2026-05-19T10:00:00Z", "resourceType": "Observation", "status": "final", "subject": { "reference": "Patient/eb1f768e-226a-c047-0f2f-8331341167c2" }, "valueQuantity": { "unit": "%", "value": 6.8 } } } }, "schema": { "$ref": "#/components/schemas/FhirResource" } } } }, "responses": { "201": { "content": { "application/fhir+json": { "examples": { "observation": { "summary": "Observation created", "value": { "code": { "coding": [ { "code": "4548-4", "display": "Hemoglobin A1c", "system": "http://loinc.org" } ] }, "effectiveDateTime": "2026-05-19T10:00:00Z", "extension": [ { "url": "http://bluebananaehr.com/synthetic-data", "valueBoolean": true } ], "id": "0e9d1a8a-aaaa-4b2b-9b1c-001122334455", "resourceType": "Observation", "status": "final", "subject": { "reference": "Patient/eb1f768e-226a-c047-0f2f-8331341167c2" }, "valueQuantity": { "unit": "%", "value": 6.8 } } } }, "schema": { "$ref": "#/components/schemas/FhirResource" } } }, "description": "Created.", "headers": { "Location": { "description": "Relative URL of the created resource.", "schema": { "type": "string" } } } }, "400": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Malformed body / resourceType mismatch." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Unauthorized." }, "403": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Forbidden tenant." }, "409": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Duplicate id." }, "422": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Validation failure." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate or write-quota exceeded." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Create a resource", "tags": [ "FHIR — Other resources" ] } }, "/api/fhir/r4/{resourceType}/{id}": { "delete": { "description": "Tombstones canonical resources (inserts a `deleted=true` row in the tenant overlay so subsequent reads return 404) and hard-deletes tenant-only resources.", "parameters": [ { "description": "FHIR R4 resource type (excluding Patient and Appointment — those have their own groups above). See https://hl7.org/fhir/R4/resourcelist.html.", "in": "path", "name": "resourceType", "required": true, "schema": { "enum": [ "Encounter", "Observation", "Condition", "MedicationRequest", "MedicationAdministration", "AllergyIntolerance", "Immunization", "Procedure", "DiagnosticReport", "CarePlan", "CareTeam", "Goal", "Practitioner", "Organization", "Location", "Device", "ImagingStudy", "Coverage", "Claim", "ExplanationOfBenefit", "SupplyDelivery", "Schedule", "Slot", "DocumentReference", "Communication", "Provenance", "QuestionnaireResponse", "Task", "ServiceRequest" ], "type": "string" } }, { "description": "Resource id. UUID for tenant-created rows; Synthea-style strings for canonical.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Unauthorized." }, "403": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Forbidden tenant." }, "404": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Not found." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate or write-quota exceeded." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Delete a resource", "tags": [ "FHIR — Other resources" ] }, "get": { "description": "Returns the resource as `application/fhir+json`. Stamped with the synthetic-data extension on the way out.", "parameters": [ { "description": "FHIR R4 resource type (excluding Patient and Appointment — those have their own groups above). See https://hl7.org/fhir/R4/resourcelist.html.", "in": "path", "name": "resourceType", "required": true, "schema": { "enum": [ "Encounter", "Observation", "Condition", "MedicationRequest", "MedicationAdministration", "AllergyIntolerance", "Immunization", "Procedure", "DiagnosticReport", "CarePlan", "CareTeam", "Goal", "Practitioner", "Organization", "Location", "Device", "ImagingStudy", "Coverage", "Claim", "ExplanationOfBenefit", "SupplyDelivery", "Schedule", "Slot", "DocumentReference", "Communication", "Provenance", "QuestionnaireResponse", "Task", "ServiceRequest" ], "type": "string" } }, { "description": "Resource id. UUID for tenant-created rows; Synthea-style strings for canonical.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirResource" } } }, "description": "Resource." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Unauthorized." }, "403": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Forbidden." }, "404": { "content": { "application/fhir+json": { "examples": { "notFound": { "summary": "404", "value": { "issue": [ { "code": "not-found", "diagnostics": "Patient/abc123 not found in tenant dev-xyz", "severity": "error" } ], "resourceType": "OperationOutcome" } } }, "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Not found." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Read a single resource", "tags": [ "FHIR — Other resources" ] }, "put": { "description": "Upsert semantics: if the id exists in this tenant overlay, update it; otherwise insert. Always returns 200 in v1. The id in the URL wins over any id in the body.", "parameters": [ { "description": "FHIR R4 resource type (excluding Patient and Appointment — those have their own groups above). See https://hl7.org/fhir/R4/resourcelist.html.", "in": "path", "name": "resourceType", "required": true, "schema": { "enum": [ "Encounter", "Observation", "Condition", "MedicationRequest", "MedicationAdministration", "AllergyIntolerance", "Immunization", "Procedure", "DiagnosticReport", "CarePlan", "CareTeam", "Goal", "Practitioner", "Organization", "Location", "Device", "ImagingStudy", "Coverage", "Claim", "ExplanationOfBenefit", "SupplyDelivery", "Schedule", "Slot", "DocumentReference", "Communication", "Provenance", "QuestionnaireResponse", "Task", "ServiceRequest" ], "type": "string" } }, { "description": "Resource id. UUID for tenant-created rows; Synthea-style strings for canonical.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirResource" } } } }, "responses": { "200": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirResource" } } }, "description": "Updated resource.", "headers": { "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Malformed body." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Unauthorized." }, "403": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Forbidden tenant." }, "422": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Validation failure." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate or write-quota exceeded." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Update (upsert) a resource", "tags": [ "FHIR — Other resources" ] } }, "/api/inspector/{tenant}/{token}": { "post": { "description": "Accepts any JSON or form-encoded body and stores it in `inspector_events` for live tail in the BlueBananaEHR simulator. Authentication is the token in the URL — minted per tenant on first simulator visit and rotated by the dev. A stale token returns `404`. No standard rate-limit headers — this endpoint is intentionally permissive so the existing HTTP webhook adapter can deliver into it end-to-end.", "parameters": [ { "description": "Tenant id this inspector belongs to (e.g. `dev-1a2b3c`).", "example": "dev-1a2b3c", "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "description": "Per-tenant inspector token (rotates on `Reset session`).", "example": "gJtKvT...", "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectorInboundBody" } } } }, "responses": { "204": { "description": "Stored." }, "404": { "description": "Tenant unknown or token stale (after Reset session)." }, "413": { "description": "Payload too large." }, "500": { "description": "Server error." } }, "summary": "Capture a webhook delivery in the simulator's inspector", "tags": [ "Simulator sandbox" ] } }, "/api/intake/{formId}/submissions": { "post": { "description": "Public, anonymous submission endpoint. Validates against the form's strict schema, rate-limits per IP, and records the submission. Every enabled subscriber on the form receives a signed POST shortly after.\n\n**Per-form schemas differ.** Only `patient_intake` accepts the example body shown here; `appointment_request` and `insurance_update` require different fields (e.g. `patient_name`) which are not yet documented.", "parameters": [ { "description": "Identifier of the canned intake form.", "example": "patient_intake", "in": "path", "name": "formId", "required": true, "schema": { "enum": [ "patient_intake", "appointment_request", "insurance_update" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeSubmissionRequest" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeSubmissionResponse" } } }, "description": "Submission recorded." }, "400": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Malformed body." }, "404": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Unknown form_id." }, "422": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Validation failed." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." }, "500": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Server error." } }, "summary": "Submit an intake form (anonymous)", "tags": [ "Intake forms" ] } }, "/api/intake/{formId}/subscriptions": { "get": { "description": "Accepts both Better-Auth session cookies and bearer API keys. The owner of a subscription is the resolved user from either auth method. Bearer-key responses carry the standard `X-RateLimit-*` headers and may return `429`.", "parameters": [ { "description": "Identifier of the canned intake form.", "example": "patient_intake", "in": "path", "name": "formId", "required": true, "schema": { "enum": [ "patient_intake", "appointment_request", "insurance_update" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeSubscriptionsList" } } }, "description": "List." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Missing/invalid session." }, "404": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Unknown form_id." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited (bearer-key path)." }, "500": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Server error." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "List my subscriptions on this form", "tags": [ "Intake forms" ] }, "post": { "description": "Server generates the HMAC signing secret and returns it exactly once. URL is validated against the SSRF guard at registration.\n\nAccepts both Better-Auth session cookies and bearer API keys. The owner of a subscription is the resolved user from either auth method. Bearer-key responses carry the standard `X-RateLimit-*` headers and may return `429`.", "parameters": [ { "description": "Identifier of the canned intake form.", "example": "patient_intake", "in": "path", "name": "formId", "required": true, "schema": { "enum": [ "patient_intake", "appointment_request", "insurance_update" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeSubscriptionCreateRequest" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeSubscriptionWithSecret" } } }, "description": "Created." }, "400": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Malformed body." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Missing/invalid session." }, "404": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Unknown form_id." }, "422": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Validation failed (URL unsafe / name too long)." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited (bearer-key path)." }, "500": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Server error." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Create a webhook subscription for this form", "tags": [ "Intake forms" ] } }, "/api/intake/{formId}/subscriptions/{id}": { "delete": { "description": "Accepts both Better-Auth session cookies and bearer API keys. Owner-scoped — cross-user access returns 404. Bearer-key responses carry the standard `X-RateLimit-*` headers and may return `429`.", "parameters": [ { "description": "Identifier of the canned intake form.", "example": "patient_intake", "in": "path", "name": "formId", "required": true, "schema": { "enum": [ "patient_intake", "appointment_request", "insurance_update" ], "type": "string" } }, { "description": "Intake subscription id (`isub_…`).", "example": "isub_1c7a0a3e-8f99-41a9-bf8b-2f1b0d8c0a01", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Missing/invalid session." }, "404": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Not found." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited (bearer-key path)." }, "500": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Server error." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Delete a subscription", "tags": [ "Intake forms" ] }, "patch": { "description": "Accepts both Better-Auth session cookies and bearer API keys. Owner-scoped — cross-user access returns 404. At least one of `name` or `enabled` must be provided. Bearer-key responses carry the standard `X-RateLimit-*` headers and may return `429`.", "parameters": [ { "description": "Identifier of the canned intake form.", "example": "patient_intake", "in": "path", "name": "formId", "required": true, "schema": { "enum": [ "patient_intake", "appointment_request", "insurance_update" ], "type": "string" } }, { "description": "Intake subscription id (`isub_…`).", "example": "isub_1c7a0a3e-8f99-41a9-bf8b-2f1b0d8c0a01", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeSubscriptionPatchRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeSubscription" } } }, "description": "Updated." }, "400": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Malformed body." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Missing/invalid session." }, "404": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Not found." }, "422": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Validation failed (e.g. neither `name` nor `enabled` supplied, or name too long)." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited (bearer-key path)." }, "500": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Server error." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Rename or toggle a subscription", "tags": [ "Intake forms" ] } }, "/api/patient-sim/email": { "post": { "description": "Twin of `POST /api/patient-sim/sms` for the email channel. `to` is lowercased + trimmed before lookup; `subject` is stored alongside the body. HTML bodies are accepted but rendered as plain text in the simulator UI.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientSimEmailRequest" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientSimMessageRecorded" } } }, "description": "Recorded." }, "400": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Malformed body." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Missing/invalid API key." }, "404": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "No patient matched the normalized `to`." }, "422": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Validation failed." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." }, "500": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Server error." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Simulate an inbound email to a patient", "tags": [ "Simulator sandbox" ] } }, "/api/patient-sim/sms": { "post": { "description": "Routes the message to the Patient in (canonical ∪ caller-tenant) whose `telecom[*].value` matches the normalized `to`. Multi-match ties break to the simulator's active patient; zero matches return `404` with the normalized form echoed. Inserts into `patient_sim_messages` and pushes to any open `/api/patient-sim/messages/stream` listener.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientSimSmsRequest" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientSimMessageRecorded" } } }, "description": "Recorded." }, "400": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Malformed body." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Missing/invalid API key." }, "404": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "No patient matched the normalized `to`." }, "422": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Validation failed." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." }, "500": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Server error." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Simulate an inbound SMS to a patient", "tags": [ "Simulator sandbox" ] } }, "/api/subscriptions": { "get": { "description": "List every subscription on the current tenant (ordered newest-first). HTTP secrets are never returned by list/read — only by create.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionsList" } } }, "description": "List of subscriptions." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Missing/invalid Authorization." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." }, "500": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Server error." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "List subscriptions for the tenant", "tags": [ "Subscriptions" ] }, "post": { "description": "Create a subscription. The webhook signing secret (`secret_view` on the response) is generated server-side and returned EXACTLY ONCE — capture it immediately.", "requestBody": { "content": { "application/json": { "examples": { "agent": { "summary": "Agent destination", "value": { "destination": { "kind": "agent", "promptTemplate": "Draft a 3-bullet prep brief for the upcoming appointment with {{patient.name}} (id {{resource.id}}). Focus on the chart.", "useCase": "appointment-prep" }, "enabled": true, "name": "Prep brief on appointment booked", "trigger": { "fieldFilters": { "status": "booked" }, "kind": "criteria", "resourceType": "Appointment" } } }, "http": { "summary": "HTTP destination", "value": { "destination": { "headers": { "X-Customer-Id": "acme-123" }, "kind": "http", "url": "https://example.com/keragon" }, "enabled": true, "name": "Forward new observations", "trigger": { "kind": "criteria", "resourceType": "Observation" } } } }, "schema": { "$ref": "#/components/schemas/SubscriptionRequest" } } } }, "responses": { "201": { "content": { "application/json": { "examples": { "agent": { "summary": "Agent destination response", "value": { "created_at": "2026-05-19T10:00:00.000Z", "destination": { "kind": "agent", "promptTemplate": "Draft a 3-bullet prep brief for the upcoming appointment with {{patient.name}} (id {{resource.id}}). Focus on the chart.", "useCase": "appointment-prep" }, "enabled": true, "id": "sub_2f1b0d8c-0a01-41a9-bf8b-1c7a0a3e8f99", "name": "Prep brief on appointment booked", "tenant": "0d24f9c4-2c4f-4a8e-9c7e-1c2dd2af0bf7", "trigger": { "fieldFilters": { "status": "booked" }, "kind": "criteria", "resourceType": "Appointment" }, "updated_at": "2026-05-19T10:00:00.000Z" } }, "http": { "summary": "HTTP destination response with secret_view", "value": { "created_at": "2026-05-19T10:02:00.000Z", "destination": { "headers": { "X-Customer-Id": "acme-123" }, "kind": "http", "url": "https://example.com/keragon" }, "enabled": true, "id": "sub_a23c91f0-7b15-4e2d-9aac-44e3c0e0d111", "name": "Forward new observations", "secret_view": "ad8cf3ba1f56e7e0c1f2a9b6e4a3b9d0fa67e1c5b7f9a0b2c4d6e8a0b2c4d6e8", "tenant": "qa-acme", "trigger": { "kind": "criteria", "resourceType": "Observation" }, "updated_at": "2026-05-19T10:02:00.000Z" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionWithSecret" } } }, "description": "Created. `secret_view` is present iff `destination.kind === \"http\"`." }, "400": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Malformed body." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Missing/invalid Authorization." }, "422": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Validation failed (trigger/destination)." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." }, "500": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Server error." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Create a subscription", "tags": [ "Subscriptions" ] } }, "/api/subscriptions/{id}": { "delete": { "description": "Cascade-deletes the subscription and any pending deliveries.", "parameters": [ { "description": "Subscription id (`sub_…`).", "example": "sub_1c7a0a3e-8f99-41a9-bf8b-2f1b0d8c0a01", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Missing/invalid Authorization." }, "404": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Not found." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." }, "500": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Server error." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Delete a subscription", "tags": [ "Subscriptions" ] }, "get": { "description": "Read a single subscription. Cross-tenant access returns 404 (no existence oracle).", "parameters": [ { "description": "Subscription id (`sub_…`).", "example": "sub_1c7a0a3e-8f99-41a9-bf8b-2f1b0d8c0a01", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } }, "description": "Subscription." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Missing/invalid Authorization." }, "404": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Not found." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." }, "500": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Server error." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Read a subscription", "tags": [ "Subscriptions" ] }, "put": { "description": "Full replacement of the four mutable fields (name, enabled, trigger, destination). Secret lifecycle: preserved across http→http; minted fresh on agent→http (returned as `secret_view`); dropped on http→agent.", "parameters": [ { "description": "Subscription id (`sub_…`).", "example": "sub_1c7a0a3e-8f99-41a9-bf8b-2f1b0d8c0a01", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionWithSecret" } } }, "description": "Updated subscription." }, "400": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Malformed body." }, "401": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Missing/invalid Authorization." }, "404": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Not found." }, "422": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Validation failed." }, "429": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Rate-limited." }, "500": { "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/OperationOutcome" } } }, "description": "Server error." } }, "security": [ { "bearerApiKey": [ ] } ], "summary": "Replace a subscription", "tags": [ "Subscriptions" ] } } }, "servers": [ { "description": "Production", "url": "https://bluebananaehr.com" }, { "description": "Local dev", "url": "http://localhost:3000" } ], "tags": [ { "description": "Patient is the spine of every FHIR record. The default `id` on these endpoints is **John Smith**, the canonical reference patient seeded into every dev tenant — Try It works out of the box.", "name": "FHIR — Patient" }, { "description": "Appointment endpoints. Every new dev tenant gets three near-future Appointments seeded at signup (`now + 2/7/32 min`), each referencing a canonical patient including John Smith.", "name": "FHIR — Appointment" }, { "description": "CRUD on every supported FHIR R4 resource type apart from Patient and Appointment (which have their own groups above). Standard verbs: search, read, create, update, delete, plus the CapabilityStatement at `/metadata`.", "name": "FHIR — Other resources" }, { "description": "Register webhook subscriptions and receive signed deliveries when FHIR resources match a `criteria` trigger or a time-anchored `template` trigger fires. Delivery payloads are documented under the `criteria.matched` and `template.fired` webhooks in this spec; signing uses `X-Keragon-Signature` (HMAC SHA-256). The HTTP signing secret is returned exactly once by `POST /api/subscriptions`.", "name": "Subscriptions" }, { "description": "Anonymous form-submission endpoint plus webhook subscription management for the canned forms (`patient_intake`, `appointment_request`, `insurance_update`). Subscription management accepts both Better-Auth session cookies and bearer API keys; submissions are public and rate-limited per IP. Delivery payloads are documented under the `intake.submission.created` webhook.", "name": "Intake forms" }, { "description": "Passive sandbox endpoints powering the 360° patient simulator at `/app/simulator`. Inbound `POST /api/patient-sim/sms` and `/email` route a message to the Patient whose `telecom[*].value` matches; `POST /api/inspector/{tenant}/{token}` is the built-in webhook inspector that auto-registers on first simulator visit. No orchestration here — Keragon's workflow product owns chaining these together.", "name": "Simulator sandbox" }, { "description": "⚠️ **Not currently working for external developers.** Every `useCase` value documented here returns `400 unknown use case`, including the `chart-summary` example in the streaming guide. The endpoints are documented for forward compatibility — build against the FHIR surface for now.", "name": "Experimental — Agent runtime (not currently working)" } ], "webhooks": { "criteria.matched": { "post": { "description": "POSTed to your subscription `http` URL immediately after a FHIR write that matched a `criteria` trigger. Body shape: `WebhookCriteriaPayload`.", "parameters": [ { "description": "Stripe-shape HMAC SHA-256 signature: `t=,v1=`. Compute `HMAC(secret, \"${t}.${rawBody}\")` and constant-time compare.", "in": "header", "name": "X-Keragon-Signature", "required": true, "schema": { "description": "Stripe-shape HMAC SHA-256 signature: `t=,v1=`. Compute `HMAC(secret, \"${t}.${rawBody}\")` and constant-time compare.", "example": "t=1716113700,v1=3a5b…", "type": "string" } }, { "description": "Stable id of the delivery attempt (`del_…`).", "in": "header", "name": "X-Keragon-Delivery", "required": true, "schema": { "description": "Stable id of the delivery attempt (`del_…`).", "example": "del_a1b2c3d4-0000-4444-8888-111122223333", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "observation": { "summary": "Observation", "value": { "data": { "context": { }, "resource": { "code": { "coding": [ { "code": "4548-4", "system": "http://loinc.org" } ] }, "extension": [ { "url": "http://bluebananaehr.com/synthetic-data", "valueBoolean": true } ], "id": "obs_001", "resourceType": "Observation", "status": "final", "subject": { "reference": "Patient/eb1f768e-226a-c047-0f2f-8331341167c2" }, "valueQuantity": { "unit": "%", "value": 6.8 } } }, "delivery_id": "del_b2c3d4e5-1111-4444-8888-222233334444", "event": { "fired_at": "2026-05-19T10:05:00.000Z", "trigger": { "kind": "criteria", "resourceType": "Observation" }, "type": "criteria.matched" }, "subscription_id": "sub_3c4d5e6f-7890-12ab-cdef-1234567890ab", "tenant": "qa-acme" } }, "patient": { "summary": "New Patient", "value": { "data": { "context": { }, "resource": { "extension": [ { "url": "http://bluebananaehr.com/synthetic-data", "valueBoolean": true } ], "id": "pt_new_xyz", "name": [ { "family": "Lopez", "given": [ "Maria" ] } ], "resourceType": "Patient" } }, "delivery_id": "del_a1b2c3d4-0000-4444-8888-111122223333", "event": { "fired_at": "2026-05-19T10:00:00.000Z", "trigger": { "kind": "criteria", "resourceType": "Patient" }, "type": "criteria.matched" }, "subscription_id": "sub_2f1b0d8c-0a01-41a9-bf8b-1c7a0a3e8f99", "tenant": "qa-acme" } } }, "schema": { "$ref": "#/components/schemas/WebhookCriteriaPayload" } } } }, "responses": { "200": { "description": "Accepted — Blue Banana treats any 2xx as success." }, "400": { "description": "Your endpoint rejected the payload — Blue Banana retries." }, "410": { "description": "Permanent failure — Blue Banana stops retrying after the 5th attempt regardless." }, "500": { "description": "Treated as transient — retried with exponential backoff." } }, "summary": "Criteria-trigger delivery" } }, "intake.submission.created": { "post": { "description": "POSTed to your intake-subscription URL each time someone submits a form you subscribed to. Same `X-Keragon-Signature` + `X-Keragon-Delivery` envelope as FHIR webhooks.", "parameters": [ { "description": "Stripe-shape HMAC SHA-256 signature: `t=,v1=`. Compute `HMAC(secret, \"${t}.${rawBody}\")` and constant-time compare.", "in": "header", "name": "X-Keragon-Signature", "required": true, "schema": { "description": "Stripe-shape HMAC SHA-256 signature: `t=,v1=`. Compute `HMAC(secret, \"${t}.${rawBody}\")` and constant-time compare.", "example": "t=1716113700,v1=3a5b…", "type": "string" } }, { "description": "Stable id of the delivery attempt (`del_…`).", "in": "header", "name": "X-Keragon-Delivery", "required": true, "schema": { "description": "Stable id of the delivery attempt (`del_…`).", "example": "del_a1b2c3d4-0000-4444-8888-111122223333", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "patientIntake": { "summary": "patient_intake submission", "value": { "data": { "submission": { "id": "isub_8c2e1a06-58b1-4cc1-a4b5-1f6d4a2e8c10", "submitted_at": "2026-05-19T18:00:00.000Z", "values": { "consent": true, "dob": "1989-04-22", "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "phone": "+15555550100", "reason_for_visit": "annual physical" } } }, "delivery_id": "del_a1b2c3d4-0000-4444-8888-111122223333", "event": { "fired_at": "2026-05-19T18:00:00.000Z", "type": "intake.submission.created" }, "form_id": "patient_intake", "subscription_id": "isub_2f1b0d8c-0a01-41a9-bf8b-1c7a0a3e8f99" } } }, "schema": { "$ref": "#/components/schemas/WebhookIntakePayload" } } } }, "responses": { "200": { "description": "Accepted." }, "500": { "description": "Treated as transient — retried." } }, "summary": "Intake-form submission delivery" } }, "template.fired": { "post": { "description": "POSTed to your subscription `http` URL when a time-anchored trigger fires. Body shape: `WebhookTemplatePayload`. Retry policy and headers identical to `criteria.matched`.", "parameters": [ { "description": "Stripe-shape HMAC SHA-256 signature: `t=,v1=`. Compute `HMAC(secret, \"${t}.${rawBody}\")` and constant-time compare.", "in": "header", "name": "X-Keragon-Signature", "required": true, "schema": { "description": "Stripe-shape HMAC SHA-256 signature: `t=,v1=`. Compute `HMAC(secret, \"${t}.${rawBody}\")` and constant-time compare.", "example": "t=1716113700,v1=3a5b…", "type": "string" } }, { "description": "Stable id of the delivery attempt (`del_…`).", "in": "header", "name": "X-Keragon-Delivery", "required": true, "schema": { "description": "Stable id of the delivery attempt (`del_…`).", "example": "del_a1b2c3d4-0000-4444-8888-111122223333", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "appointmentNoShow": { "summary": "appointment_no_show 15min after", "value": { "data": { "context": { "offsetMinutes": 15 }, "resource": { "extension": [ { "url": "http://bluebananaehr.com/synthetic-data", "valueBoolean": true } ], "id": "appt_001", "resourceType": "Appointment", "start": "2026-05-20T15:00:00Z", "status": "booked" } }, "delivery_id": "del_d4e5f6a7-3333-4444-8888-444455556666", "event": { "fired_at": "2026-05-20T15:15:00.000Z", "trigger": { "kind": "template", "offsetMinutes": 15, "template": "appointment_no_show" }, "type": "template.fired" }, "subscription_id": "sub_bbbb2222-3333-4444-5555-66667777aaaa", "tenant": "qa-acme" } }, "appointmentReminder": { "summary": "appointment_reminder 60min before", "value": { "data": { "context": { "offsetMinutes": 60 }, "resource": { "end": "2026-05-20T15:30:00Z", "extension": [ { "url": "http://bluebananaehr.com/synthetic-data", "valueBoolean": true } ], "id": "appt_001", "resourceType": "Appointment", "start": "2026-05-20T15:00:00Z", "status": "booked" } }, "delivery_id": "del_c3d4e5f6-2222-4444-8888-333344445555", "event": { "fired_at": "2026-05-20T14:00:00.000Z", "trigger": { "kind": "template", "offsetMinutes": 60, "template": "appointment_reminder" }, "type": "template.fired" }, "subscription_id": "sub_aaaa1111-2222-3333-4444-555566667777", "tenant": "qa-acme" } }, "dailyAt": { "summary": "daily_at 09:00 UTC", "value": { "data": { "context": { }, "resource": null }, "delivery_id": "del_e5f6a7b8-4444-4444-8888-555566667777", "event": { "fired_at": "2026-05-19T09:00:00.000Z", "trigger": { "hourUtc": 9, "kind": "template", "template": "daily_at" }, "type": "template.fired" }, "subscription_id": "sub_cccc3333-4444-5555-6666-7777aaaabbbb", "tenant": "qa-acme" } } }, "schema": { "$ref": "#/components/schemas/WebhookTemplatePayload" } } } }, "responses": { "200": { "description": "Accepted." }, "500": { "description": "Treated as transient — retried." } }, "summary": "Template-trigger delivery" } } } }