Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.0.3
info:
version: 1.0.0
title: Query Connector API - OpenAPI 3.0
# TODO: IMPLEMENT THIS PORTION PRIOR TO SHIPPING API
# components:
# securitySchemes:
# OAuth2:
# type: oauth2
# flows:
# authorizationCode:
# authorizationUrl: https://example.com/oauth/authorize
# tokenUrl: https://example.com/oauth/token
# scopes:
# read: Grants read access
# write: Grants write access
# admin: Grants access to admin operations
paths:
/api:
get:
description: Returns the health status of the API
responses:
200:
description: Health check for Query Connector
/api/query:
post:
description: A POST endpoint that accepts a FHIR patient resource or an HL7v2 message in the request body to execute a query within the Query Connector
parameters:
- name: fhir_server
in: query
description: Name of the FHIR server to query
required: true
schema:
type: string
example: "HELIOS Meld: Direct"
- name: id
in: query
description: ID of the query to use
required: true
schema:
type: string
example: cf580d8d-cc7b-4eae-8a0d-96c36f9222e3
- name: message_format
in: query
description: Whether the request body contents are HL7 or FHIR formatted messages
schema:
type: string
enum: [HL7, FHIR]
example: FHIR
requestBody:
required: true
content:
application/json:
schema:
type: object
example:
{
"resourceType": "Patient",
"id": "1C",
"meta":
{
"versionId": "1",
"lastUpdated": "2024-01-16T15:08:24.000+00:00",
"source": "#Aolu2ZnQyoelPvRd",
"profile":
[
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient",
],
},
"text":
{
"status": "generated",
"div": '<div xmlns="http://www.w3.org/1999/xhtml">This is a simple narrative with only plain text</div>',
},
"extension":
[
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
"extension":
[
{
"url": "ombCategory",
"valueCoding":
{
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2106-3",
"display": "White",
},
},
{ "url": "text", "valueString": "Mixed" },
],
},
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
"extension":
[
{
"url": "ombCategory",
"valueCoding":
{
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2135-2",
"display": "Hispanic or Latino",
},
},
{
"url": "text",
"valueString": "Hispanic or Latino",
},
],
},
],
"identifier":
[
{
"use": "usual",
"type":
{
"coding":
[
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MR",
"display": "Medical Record Number",
},
],
"text": "Medical Record Number",
},
"system": "http://hospital.smarthealthit.org",
"value": "8692756",
},
],
"active": true,
"name":
[
{
"family": "Shaw",
"given": ["Lee", "A."],
"period": { "start": "1975-12-06", "end": "2020-01-22" },
},
{
"family": "Shaw",
"given": ["Lee", "V."],
"suffix": ["MD"],
"period": { "start": "2020-01-23" },
},
],
"telecom":
[
{
"system": "phone",
"value": "517-425-1398",
"use": "home",
},
{ "system": "email", "value": "lee.shaw@email.com" },
],
"gender": "male",
"birthDate": "1975-12-06",
"address":
[
{
"line": ["49 Meadow St"],
"city": "Lansing",
"state": "MI",
"postalCode": "48864",
"country": "US",
"period": { "start": "2016-12-06", "end": "2020-07-22" },
},
{
"line": ["183 Mountain View St"],
"city": "Lansing",
"state": "MI",
"postalCode": "48901",
"country": "US",
"period": { "start": "2020-07-22" },
},
],
}
responses:
200:
description: The FHIR resources returned that match the information configured in the query referenced
400:
description: Missing patient identifiers
500:
description: Something went wrong :(
get:
description: A GET endpoint that accepts a series of query parameters to execute a query within the Query Connector. At least one of the patient identifier params are required
parameters:
- name: fhir_server
in: query
description: Name of the FHIR server to query
required: true
schema:
type: string
example: "HELIOS Meld: Direct"
- name: id
in: query
description: ID of the query to use
required: true
schema:
type: string
example: cf580d8d-cc7b-4eae-8a0d-96c36f9222e3
- name: given
description: Patient given name. At least one of the patient identifier params are required
in: query
schema:
type: string
example: Lee
- name: family
in: query
description: Patient family name. At least one of the patient identifier params are required
schema:
type: string
example: Shaw
- name: dob
in: query
description: Patient date of birth in YYYY-MM-DD format. At least one of the patient identifier params are required
schema:
type: string
example: 1975-12-06
- name: mrn
in: query
description: Patient medical record number. At least one of the patient identifier params are required
schema:
type: string
example: 8692756
- name: phone
in: query
description: Patient phone number. At least one of the patient identifier params are required
schema:
type: string
example: 517-425-1398
- name: gender
in: query
description: Patient sex as a FHIR administrative-gender code. Optional search refinement; does not count toward required patient identifiers
schema:
type: string
enum: [female, male, other, unknown]
example: female
- name: race
in: query
description: Patient race as an OMB category code from the CDC Race & Ethnicity code system (urn:oid:2.16.840.1.113883.6.238). Uses the US Core race SearchParameter; servers without US Core support may ignore it
schema:
type: string
enum: ["1002-5", "2028-9", "2054-5", "2076-8", "2106-3"]
example: "2106-3"
- name: ethnicity
in: query
description: Patient ethnicity as an OMB category code from the CDC Race & Ethnicity code system (urn:oid:2.16.840.1.113883.6.238). Uses the US Core ethnicity SearchParameter; servers without US Core support may ignore it
schema:
type: string
enum: ["2135-2", "2186-5"]
example: "2135-2"
responses:
200:
description: The FHIR resources returned that match the information configured in the query referenced
400:
description: Missing patient identifiers
500:
description: Something went wrong :(