{ "openapi": "3.1.0", "info": { "title": "Health Record Relay API", "version": "1.0.0", "description": "API v1 for organization-scoped secure record transfers, record requests, lifecycle events, recipient endpoints, and signed outbound webhooks. Do not put API keys in browser/client-side code." }, "servers": [ { "url": "https://healthrecordrelay.com/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Transfers" }, { "name": "Record Requests" }, { "name": "Recipients" }, { "name": "Webhooks" } ], "paths": { "/transfers": { "get": { "summary": "List transfers", "tags": [ "Transfers" ], "x-hrr-required-scope": "transfers:read", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transfer" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "external_system", "in": "query", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } } ] }, "post": { "summary": "Create a transfer", "tags": [ "Transfers" ], "x-hrr-required-scope": "transfers:create", "responses": { "201": { "description": "Created", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Transfer" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient_endpoint_id": { "type": [ "integer", "null" ] }, "external_system": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "patient_reference": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "patient_consent": { "$ref": "#/components/schemas/PatientConsentInput" } } } } } } } }, "/transfers/{transfer}": { "get": { "summary": "Get a transfer", "tags": [ "Transfers" ], "x-hrr-required-scope": "transfers:read", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Transfer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "transfer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/transfers/{transfer}/files": { "post": { "summary": "Upload a transfer file", "tags": [ "Transfers" ], "x-hrr-required-scope": "transfers:files", "responses": { "202": { "description": "Accepted for malware scanning", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TransferFile" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "transfer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } } } }, "/transfers/{transfer}/send": { "post": { "summary": "Send a transfer", "tags": [ "Transfers" ], "x-hrr-required-scope": "transfers:send", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Transfer" } } } } } }, "202": { "description": "Accepted/pending consent", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Transfer" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "transfer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient_endpoint_id": { "type": [ "integer", "null" ] }, "expires_in_hours": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 72 } } } } } } } }, "/transfers/{transfer}/events": { "get": { "summary": "List transfer events", "tags": [ "Transfers" ], "x-hrr-required-scope": "events:read", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "transfer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } } ] } }, "/recipient-endpoints": { "get": { "summary": "List recipient endpoints", "tags": [ "Recipients" ], "x-hrr-required-scope": "recipients:read", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientEndpoint" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "org_inbox", "email", "fax" ] } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 100 } } ] } }, "/record-requests": { "get": { "summary": "List record requests", "tags": [ "Record Requests" ], "x-hrr-required-scope": "record_requests:read", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecordRequest" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "incoming", "outgoing" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "external_system", "in": "query", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "due_before", "in": "query", "schema": { "type": "string", "format": "date-time" } } ] }, "post": { "summary": "Create a record request", "tags": [ "Record Requests" ], "x-hrr-required-scope": "record_requests:create", "responses": { "201": { "description": "Created", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RecordRequest" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "recipient_endpoint_id" ], "properties": { "recipient_endpoint_id": { "type": "integer" }, "external_system": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "patient_reference": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "requested_records": { "type": "array", "maxItems": 50, "items": { "type": "string" } }, "due_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "/record-requests/{recordRequest}": { "get": { "summary": "Get a record request", "tags": [ "Record Requests" ], "x-hrr-required-scope": "record_requests:read", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RecordRequest" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "recordRequest", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/record-requests/{recordRequest}/events": { "get": { "summary": "List record request events", "tags": [ "Record Requests" ], "x-hrr-required-scope": "record_requests:read", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "recordRequest", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "type", "in": "query", "schema": { "type": "string" } } ] } }, "/record-requests/{recordRequest}/view": { "post": { "summary": "View a record request", "tags": [ "Record Requests" ], "x-hrr-required-scope": "record_requests:respond", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RecordRequest" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "recordRequest", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/record-requests/{recordRequest}/accept": { "post": { "summary": "Accept a record request", "tags": [ "Record Requests" ], "x-hrr-required-scope": "record_requests:respond", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RecordRequest" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "recordRequest", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/record-requests/{recordRequest}/reject": { "post": { "summary": "Reject a record request", "tags": [ "Record Requests" ], "x-hrr-required-scope": "record_requests:respond", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RecordRequest" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "recordRequest", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "maxLength": 1000 } } } } } } } }, "/record-requests/{recordRequest}/cancel": { "post": { "summary": "Cancel a record request", "tags": [ "Record Requests" ], "x-hrr-required-scope": "record_requests:create", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RecordRequest" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "recordRequest", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/record-requests/{recordRequest}/fulfill": { "post": { "summary": "Fulfill a record request", "tags": [ "Record Requests" ], "x-hrr-required-scope": "record_requests:respond", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RecordRequest" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "recordRequest", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "patient_consent": { "$ref": "#/components/schemas/PatientConsentInput" } } } } } } } }, "/webhook-endpoints": { "get": { "summary": "List webhook endpoints", "tags": [ "Webhooks" ], "x-hrr-required-scope": "webhooks:manage", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "active", "in": "query", "schema": { "type": "boolean" } } ] }, "post": { "summary": "Create a webhook endpoint", "tags": [ "Webhooks" ], "x-hrr-required-scope": "webhooks:manage", "responses": { "201": { "description": "Created. Response also includes one-time secret.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } } } } } } } } }, "/webhook-endpoints/{webhookEndpoint}": { "patch": { "summary": "Update a webhook endpoint", "tags": [ "Webhooks" ], "x-hrr-required-scope": "webhooks:manage", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "webhookEndpoint", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" } } } } } } }, "delete": { "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ], "x-hrr-required-scope": "webhooks:manage", "responses": { "200": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "webhookEndpoint", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/webhook-endpoints/{webhookEndpoint}/deliveries": { "get": { "summary": "List webhook deliveries", "tags": [ "Webhooks" ], "x-hrr-required-scope": "webhooks:manage", "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "webhookEndpoint", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "event", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "retrying", "delivered", "failed" ] } } ] } }, "/webhook-endpoints/{webhookEndpoint}/rotate-secret": { "post": { "summary": "Rotate webhook signing secret", "tags": [ "Webhooks" ], "x-hrr-required-scope": "webhooks:manage", "responses": { "200": { "description": "Secret rotated. The new secret is shown once." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "webhookEndpoint", "in": "path", "required": true, "schema": { "type": "integer" } } ] } }, "/webhook-endpoints/{webhookEndpoint}/test": { "post": { "summary": "Queue a webhook.test event", "tags": [ "Webhooks" ], "x-hrr-required-scope": "webhooks:manage", "responses": { "202": { "description": "Test event queued" }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "webhookEndpoint", "in": "path", "required": true, "schema": { "type": "integer" } } ] } } }, "webhooks": { "hrrLifecycleEvent": { "post": { "summary": "Health Record Relay lifecycle webhook", "description": "HRR sends JSON with HRR-Webhook-Id, HRR-Webhook-Timestamp, HRR-Webhook-Signature, and HRR-Webhook-Attempt headers. Verify the HMAC-SHA256 signature using timestamp + '.' + raw request body and reject stale timestamps.", "parameters": [ { "name": "HRR-Webhook-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "HRR-Webhook-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "HRR-Webhook-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "HRR-Webhook-Attempt", "in": "header", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventEnvelope" } } } }, "responses": { "200": { "description": "Receiver accepted event" }, "204": { "description": "Receiver accepted event" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "HRR API key" } }, "parameters": { "RequestId": { "name": "X-Request-ID", "in": "header", "required": false, "description": "Optional caller correlation ID. Valid IDs are echoed back. Invalid values are replaced with an HRR-generated request ID.", "schema": { "type": "string", "maxLength": 128 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required on supported write operations. Reusing the same key with the same request replays the original response; reusing it with a different request returns 409.", "schema": { "type": "string", "maxLength": 255 } }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 512 } } }, "headers": { "RequestId": { "description": "Request correlation ID.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Bad request", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Missing, invalid, revoked, or expired API key", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "API key lacks required scope", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found or not visible to the authenticated organization", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "Request conflicts with resource state or idempotency state", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ValidationError": { "description": "Validation failed", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Rate limit exceeded", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "errors", "request_id" ], "properties": { "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } }, "request_id": { "type": "string", "examples": [ "req_01k7example" ] } } }, "PaginationMeta": { "type": "object", "required": [ "limit", "count", "has_more", "next_cursor" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "count": { "type": "integer", "minimum": 0 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "PatientConsentInput": { "type": "object", "properties": { "required": { "type": "boolean" }, "channel": { "type": [ "string", "null" ], "enum": [ "sms", "email", null ] }, "patient_name": { "type": [ "string", "null" ], "maxLength": 190 }, "patient_email": { "type": [ "string", "null" ], "format": "email" }, "patient_phone": { "type": [ "string", "null" ], "maxLength": 40 } } }, "TransferFile": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "mime_type": { "type": [ "string", "null" ] }, "size_bytes": { "type": "integer" }, "sha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "scan_status": { "type": "string", "enum": [ "pending", "clean", "infected", "error" ] }, "scanned_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Transfer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "display_code": { "type": "string" }, "status": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "patient_reference": { "type": [ "string", "null" ] }, "external_system": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "recipient_endpoint_id": { "type": [ "integer", "null" ] }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/TransferFile" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "RecordRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "display_code": { "type": "string" }, "status": { "type": "string" }, "direction": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "subject": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "patient_reference": { "type": [ "string", "null" ] }, "requested_records": { "type": "array", "items": { "type": "string" } }, "external_system": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "fulfillment_transfer_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Event": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "entity_type": { "type": [ "string", "null" ] }, "entity_id": { "type": [ "integer", "null" ] }, "actor": { "type": "object" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "RecipientEndpoint": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "org_inbox", "email", "fax" ] }, "email": { "type": "string", "format": "email" }, "fax_number": { "type": "string" }, "target_organization_id": { "type": "integer" } } }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "integer" }, "event_id": { "type": "string" }, "event": { "type": "string" }, "attempt_number": { "type": "integer" }, "response_status": { "type": [ "integer", "null" ] }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookEventEnvelope": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "organization_id": { "type": "integer" }, "data": { "type": "object", "additionalProperties": true } } } } } }