{"id":"graphql-transport-contract","title":"GraphQL transport contract","description":"Connect to the shared GraphQL transport with bearer authentication and tenant scoping, without publishing the full schema or operation inventory.","lastUpdated":"2026-04-22","sections":[{"id":"graphql-transport","title":"POST /graphql · Use the shared GraphQL transport","content":"Route: POST /graphql\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nConnect to the GraphQL endpoint with bearer tokens and tenant scoping, while operation bundles remain curated and access-controlled.\n\nIntegration notes:\n- Public documentation covers transport, headers, tenancy, and error handling only.\n- Schema dumps, playground access, introspection guidance, and unpublished operations are excluded from the public contract.\n- Approved partners receive curated operation bundles tied to explicit integration workflows.","codeExamples":[{"language":"bash","code":"curl -X POST https://api.knogin.com/graphql \\\n  -H \"Authorization: Bearer <access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Tenant-ID: <tenant-id>\" \\\n  -d '{\n    \"query\": \"<approved GraphQL document>\",\n    \"variables\": {}\n  }'","description":"Request example"},{"language":"json","code":"{\n  \"data\": {\n    \"result\": \"Returned for your approved operation bundle\"\n  }\n}","description":"Response example"}]},{"id":"epcr-encounter-get","title":"GET /api/v1/epcr/encounters/{encounterId} · Fetch an ePCR encounter","content":"Route: GET /api/v1/epcr/encounters/{encounterId}\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nRetrieve the partner-facing summary of an electronic patient care record encounter, or a FHIR R4 Bundle when ?format=fhir.\n\nIntegration notes:\n- Partners receive a de-identified projection; full PII (DOB, NOK contact, street address) remain internal.\n- Pass ?format=fhir for an interoperability-ready FHIR R4 transaction Bundle.","codeExamples":[{"language":"bash","code":"curl https://api.knogin.com/api/v1/epcr/encounters/enc_123 \\\n  -H \"Authorization: Bearer <access-token>\"","description":"Request example"},{"language":"json","code":"{\n  \"id\": \"enc_123\",\n  \"organization_id\": \"org_1\",\n  \"care_model\": \"prehospital_emergency\",\n  \"status\": \"in_progress\"\n}","description":"Response example"}]},{"id":"epcr-encounter-fhir","title":"GET /api/v1/epcr/encounters/{encounterId}/fhir-bundle · Export encounter as FHIR R4 Bundle","content":"Route: GET /api/v1/epcr/encounters/{encounterId}/fhir-bundle\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nReturn a FHIR R4 transaction Bundle for an ePCR encounter, suitable for handover into hospital EHRs.\n\nIntegration notes:\n- Bundle contains Patient, Encounter, Observation, Procedure, MedicationAdministration, and Composition resources.","codeExamples":[{"language":"bash","code":"curl https://api.knogin.com/api/v1/epcr/encounters/enc_123/fhir-bundle \\\n  -H \"Authorization: Bearer <access-token>\"","description":"Request example"},{"language":"json","code":"{\n  \"resourceType\": \"Bundle\",\n  \"type\": \"transaction\",\n  \"entry\": []\n}","description":"Response example"}]},{"id":"epcr-encounter-create","title":"POST /api/v1/epcr/encounters · Create an ePCR encounter","content":"Route: POST /api/v1/epcr/encounters\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nCreate a new ePCR encounter from an external CAD-to-ePCR integration, scoped to the caller's organisation.\n\nIntegration notes:\n- Requires the argus:epcr:write scope on the calling service token.","codeExamples":[{"language":"bash","code":"curl -X POST https://api.knogin.com/api/v1/epcr/encounters \\\n  -H \"Authorization: Bearer <access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"care_model\": \"prehospital_emergency\",\n    \"vehicle_id\": \"AMB-42\",\n    \"crew_ids\": [\"usr_1\"],\n    \"cad_incident_id\": \"cad_999\"\n  }'","description":"Request example"},{"language":"json","code":"{\n  \"id\": \"enc_123\",\n  \"status\": \"in_progress\"\n}","description":"Response example"}]},{"id":"medical-devices-list","title":"GET /api/v1/devices · List medical devices","content":"Route: GET /api/v1/devices\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nList IEEE 11073 PHD-enrolled medical devices for the caller's organisation, optionally filtered by vehicle.\n\nIntegration notes:\n- Supported device classes: defib, ecg, oximeter, bp, glucose, etco2, thermometer, multiparameter.","codeExamples":[{"language":"bash","code":"curl \"https://api.knogin.com/api/v1/devices?vehicle_id=AMB-42\" \\\n  -H \"Authorization: Bearer <access-token>\"","description":"Request example"},{"language":"text","code":"[\n  {\n    \"id\": \"dev_1\",\n    \"serial_number\": \"SN-0001\",\n    \"device_class\": \"defib\",\n    \"status\": \"active\"\n  }\n]","description":"Response example"}]},{"id":"medical-devices-enrol","title":"POST /api/v1/devices/enrol · Enrol a medical device","content":"Route: POST /api/v1/devices/enrol\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nEnrol (or re-enrol) a medical device for this organisation so it can emit IEEE 11073 PHD observations.\n\nIntegration notes:\n- Requires the argus:devices:write scope on the calling service token.","codeExamples":[{"language":"bash","code":"curl -X POST https://api.knogin.com/api/v1/devices/enrol \\\n  -H \"Authorization: Bearer <access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"serial_number\": \"SN-0001\",\n    \"device_class\": \"defib\",\n    \"manufacturer\": \"ACME\"\n  }'","description":"Request example"},{"language":"json","code":"{\n  \"id\": \"dev_1\",\n  \"serial_number\": \"SN-0001\",\n  \"device_class\": \"defib\",\n  \"status\": \"active\"\n}","description":"Response example"}]},{"id":"medical-devices-ingest-observation","title":"POST /api/v1/devices/{deviceId}/observations · Submit a PHD observation","content":"Route: POST /api/v1/devices/{deviceId}/observations\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nSubmit a single IEEE 11073 PHD observation (MDC metric code + UCUM unit) from an enrolled device.\n\nIntegration notes:\n- Use mdc_code from ISO/IEEE 11073-10101 and unit_code from UCUM.\n- Optionally link the observation to an ePCR encounter via encounter_id.","codeExamples":[{"language":"bash","code":"curl -X POST https://api.knogin.com/api/v1/devices/dev_1/observations \\\n  -H \"Authorization: Bearer <access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"mdc_code\": \"MDC_PULS_OXIM_SAT_O2\",\n    \"value\": 98.0,\n    \"unit_code\": \"%\"\n  }'","description":"Request example"},{"language":"json","code":"{\n  \"id\": \"obs_1\",\n  \"device_id\": \"dev_1\",\n  \"mdc_code\": \"MDC_PULS_OXIM_SAT_O2\",\n  \"value\": 98.0,\n  \"unit_code\": \"%\"\n}","description":"Response example"}]},{"id":"acqi-metrics","title":"query acqiMetrics(fromDate, toDate) · Query ACQI metrics","content":"Route: query acqiMetrics(fromDate, toDate)\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nRetrieve Ambulance Clinical Quality Indicator metrics with sparkline trend data over a date range (GraphQL).\n\nIntegration notes:\n- Requires the argus:acqi:read scope on the calling service token.","codeExamples":[{"language":"bash","code":"curl -X POST https://api.knogin.com/graphql \\\n  -H \"Authorization: Bearer <access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"query($from: DateTime!, $to: DateTime!) { acqiMetrics(fromDate: $from, toDate: $to) { name value numerator denominator unit } }\",\n    \"variables\": { \"from\": \"2026-04-01T00:00:00Z\", \"to\": \"2026-04-17T00:00:00Z\" }\n  }'","description":"Request example"},{"language":"json","code":"{\n  \"data\": {\n    \"acqiMetrics\": [\n      {\n        \"name\": \"rosc_survival\",\n        \"value\": 0.32\n      }\n    ]\n  }\n}","description":"Response example"}]}],"relatedTopics":["identity-app-registration","oauth-service-tokens","jwks-token-verification","event-delivery-webhooks"],"markdown":"# GraphQL transport contract\n\nConnect to the shared GraphQL transport with bearer authentication and tenant scoping, without publishing the full schema or operation inventory.\n\n## POST /graphql · Use the shared GraphQL transport\n\nRoute: POST /graphql\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nConnect to the GraphQL endpoint with bearer tokens and tenant scoping, while operation bundles remain curated and access-controlled.\n\nIntegration notes:\n- Public documentation covers transport, headers, tenancy, and error handling only.\n- Schema dumps, playground access, introspection guidance, and unpublished operations are excluded from the public contract.\n- Approved partners receive curated operation bundles tied to explicit integration workflows.\n\nRequest example\n\n```bash\ncurl -X POST https://api.knogin.com/graphql \\\n  -H \"Authorization: Bearer <access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Tenant-ID: <tenant-id>\" \\\n  -d '{\n    \"query\": \"<approved GraphQL document>\",\n    \"variables\": {}\n  }'\n```\n\nResponse example\n\n```json\n{\n  \"data\": {\n    \"result\": \"Returned for your approved operation bundle\"\n  }\n}\n```\n\n## GET /api/v1/epcr/encounters/{encounterId} · Fetch an ePCR encounter\n\nRoute: GET /api/v1/epcr/encounters/{encounterId}\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nRetrieve the partner-facing summary of an electronic patient care record encounter, or a FHIR R4 Bundle when ?format=fhir.\n\nIntegration notes:\n- Partners receive a de-identified projection; full PII (DOB, NOK contact, street address) remain internal.\n- Pass ?format=fhir for an interoperability-ready FHIR R4 transaction Bundle.\n\nRequest example\n\n```bash\ncurl https://api.knogin.com/api/v1/epcr/encounters/enc_123 \\\n  -H \"Authorization: Bearer <access-token>\"\n```\n\nResponse example\n\n```json\n{\n  \"id\": \"enc_123\",\n  \"organization_id\": \"org_1\",\n  \"care_model\": \"prehospital_emergency\",\n  \"status\": \"in_progress\"\n}\n```\n\n## GET /api/v1/epcr/encounters/{encounterId}/fhir-bundle · Export encounter as FHIR R4 Bundle\n\nRoute: GET /api/v1/epcr/encounters/{encounterId}/fhir-bundle\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nReturn a FHIR R4 transaction Bundle for an ePCR encounter, suitable for handover into hospital EHRs.\n\nIntegration notes:\n- Bundle contains Patient, Encounter, Observation, Procedure, MedicationAdministration, and Composition resources.\n\nRequest example\n\n```bash\ncurl https://api.knogin.com/api/v1/epcr/encounters/enc_123/fhir-bundle \\\n  -H \"Authorization: Bearer <access-token>\"\n```\n\nResponse example\n\n```json\n{\n  \"resourceType\": \"Bundle\",\n  \"type\": \"transaction\",\n  \"entry\": []\n}\n```\n\n## POST /api/v1/epcr/encounters · Create an ePCR encounter\n\nRoute: POST /api/v1/epcr/encounters\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nCreate a new ePCR encounter from an external CAD-to-ePCR integration, scoped to the caller's organisation.\n\nIntegration notes:\n- Requires the argus:epcr:write scope on the calling service token.\n\nRequest example\n\n```bash\ncurl -X POST https://api.knogin.com/api/v1/epcr/encounters \\\n  -H \"Authorization: Bearer <access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"care_model\": \"prehospital_emergency\",\n    \"vehicle_id\": \"AMB-42\",\n    \"crew_ids\": [\"usr_1\"],\n    \"cad_incident_id\": \"cad_999\"\n  }'\n```\n\nResponse example\n\n```json\n{\n  \"id\": \"enc_123\",\n  \"status\": \"in_progress\"\n}\n```\n\n## GET /api/v1/devices · List medical devices\n\nRoute: GET /api/v1/devices\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nList IEEE 11073 PHD-enrolled medical devices for the caller's organisation, optionally filtered by vehicle.\n\nIntegration notes:\n- Supported device classes: defib, ecg, oximeter, bp, glucose, etco2, thermometer, multiparameter.\n\nRequest example\n\n```bash\ncurl \"https://api.knogin.com/api/v1/devices?vehicle_id=AMB-42\" \\\n  -H \"Authorization: Bearer <access-token>\"\n```\n\nResponse example\n\n```text\n[\n  {\n    \"id\": \"dev_1\",\n    \"serial_number\": \"SN-0001\",\n    \"device_class\": \"defib\",\n    \"status\": \"active\"\n  }\n]\n```\n\n## POST /api/v1/devices/enrol · Enrol a medical device\n\nRoute: POST /api/v1/devices/enrol\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nEnrol (or re-enrol) a medical device for this organisation so it can emit IEEE 11073 PHD observations.\n\nIntegration notes:\n- Requires the argus:devices:write scope on the calling service token.\n\nRequest example\n\n```bash\ncurl -X POST https://api.knogin.com/api/v1/devices/enrol \\\n  -H \"Authorization: Bearer <access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"serial_number\": \"SN-0001\",\n    \"device_class\": \"defib\",\n    \"manufacturer\": \"ACME\"\n  }'\n```\n\nResponse example\n\n```json\n{\n  \"id\": \"dev_1\",\n  \"serial_number\": \"SN-0001\",\n  \"device_class\": \"defib\",\n  \"status\": \"active\"\n}\n```\n\n## POST /api/v1/devices/{deviceId}/observations · Submit a PHD observation\n\nRoute: POST /api/v1/devices/{deviceId}/observations\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nSubmit a single IEEE 11073 PHD observation (MDC metric code + UCUM unit) from an enrolled device.\n\nIntegration notes:\n- Use mdc_code from ISO/IEEE 11073-10101 and unit_code from UCUM.\n- Optionally link the observation to an ePCR encounter via encounter_id.\n\nRequest example\n\n```bash\ncurl -X POST https://api.knogin.com/api/v1/devices/dev_1/observations \\\n  -H \"Authorization: Bearer <access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"mdc_code\": \"MDC_PULS_OXIM_SAT_O2\",\n    \"value\": 98.0,\n    \"unit_code\": \"%\"\n  }'\n```\n\nResponse example\n\n```json\n{\n  \"id\": \"obs_1\",\n  \"device_id\": \"dev_1\",\n  \"mdc_code\": \"MDC_PULS_OXIM_SAT_O2\",\n  \"value\": 98.0,\n  \"unit_code\": \"%\"\n}\n```\n\n## query acqiMetrics(fromDate, toDate) · Query ACQI metrics\n\nRoute: query acqiMetrics(fromDate, toDate)\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nRetrieve Ambulance Clinical Quality Indicator metrics with sparkline trend data over a date range (GraphQL).\n\nIntegration notes:\n- Requires the argus:acqi:read scope on the calling service token.\n\nRequest example\n\n```bash\ncurl -X POST https://api.knogin.com/graphql \\\n  -H \"Authorization: Bearer <access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"query($from: DateTime!, $to: DateTime!) { acqiMetrics(fromDate: $from, toDate: $to) { name value numerator denominator unit } }\",\n    \"variables\": { \"from\": \"2026-04-01T00:00:00Z\", \"to\": \"2026-04-17T00:00:00Z\" }\n  }'\n```\n\nResponse example\n\n```json\n{\n  \"data\": {\n    \"acqiMetrics\": [\n      {\n        \"name\": \"rosc_survival\",\n        \"value\": 0.32\n      }\n    ]\n  }\n}\n```\n\n## Related Topics\n\n- [Identity and app registration](https://knogin.com/api/docs/identity-app-registration)\n- [OAuth and service tokens](https://knogin.com/api/docs/oauth-service-tokens)\n- [JWKS and token verification](https://knogin.com/api/docs/jwks-token-verification)\n- [Event delivery and webhooks](https://knogin.com/api/docs/event-delivery-webhooks)","metadata":{"readingTime":"16 min","difficulty":"intermediate","tags":["integrations","api","oauth","webhooks","graphql"]}}