GraphQL API
Flexible, type-safe queries over the entire HealthCloud data model
GraphQL Endpoint
https://api.healthcloud.ai/graphqlGraphiQL Playground
https://api.healthcloud.ai/graphiqlAuthentication
Pass your API key in the Authorization header: Authorization: Bearer hc_test_sk_demo_live_xxxxxx
Full Schema SDL
schema.graphql
# HealthCloud GraphQL Schema — v2.0
scalar DateTime
scalar JSON
enum AssetType { MODEL AGENT CONNECTOR DATASET SOLUTION APP }
enum AssetStatus { DRAFT UNDER_REVIEW APPROVED REJECTED DEPRECATED }
enum PricingType { FREE USAGE_BASED SUBSCRIPTION ENTERPRISE }
enum DeploymentStatus { PENDING RUNNING DEGRADED STOPPED FAILED }
enum WorkflowStatus { ACTIVE PAUSED ARCHIVED }
enum RunStatus { QUEUED RUNNING COMPLETED FAILED CANCELLED }
enum FHIRResourceType {
Patient Observation DiagnosticReport Encounter Condition
MedicationRequest CarePlan Device Practitioner
}
type Organization {
id: ID!
name: String!
slug: String!
plan: String!
memberCount: Int!
projects: [Project!]!
createdAt: DateTime!
}
type Project {
id: ID!
name: String!
organization: Organization!
assets: [AssetInstallation!]!
deployments: [Deployment!]!
workflows: [Workflow!]!
createdAt: DateTime!
}
type MarketplaceAsset {
id: ID!
name: String!
description: String!
type: AssetType!
category: String!
version: String!
publisher: Publisher!
pricing: Pricing!
fhirResources: [String!]!
complianceScore: ComplianceScore!
badges: [String!]!
rating: Float
downloads: Int!
status: AssetStatus!
createdAt: DateTime!
updatedAt: DateTime!
}
type Publisher {
id: ID!
name: String!
email: String!
organization: Organization
verified: Boolean!
totalApps: Int!
}
type Pricing {
type: PricingType!
costPerRequest: Float
monthlyFee: Float
annualFee: Float
freeTierLimit: Int
}
type ComplianceScore {
overall: Int!
security: Int!
privacy: Int!
clinicalSafety: Int!
hipaaCompliant: Boolean!
fdaCleared: Boolean!
}
type AssetInstallation {
id: ID!
asset: MarketplaceAsset!
project: Project!
status: String!
config: JSON
installedAt: DateTime!
}
type Deployment {
id: ID!
installation: AssetInstallation!
project: Project!
environment: String!
status: DeploymentStatus!
replicas: Int!
endpoint: String
hipaaMode: Boolean!
deployedAt: DateTime!
}
type Agent {
id: ID!
name: String!
description: String!
project: Project!
runMode: String!
status: String!
sessions: [AgentSession!]!
createdAt: DateTime!
}
type AgentSession {
id: ID!
agent: Agent!
patientId: String!
status: RunStatus!
input: JSON
output: JSON
latencyMs: Int
tokensUsed: Int
startedAt: DateTime!
completedAt: DateTime
}
type Workflow {
id: ID!
name: String!
description: String!
project: Project!
status: WorkflowStatus!
nodes: Int!
runs: [WorkflowRun!]!
createdAt: DateTime!
}
type WorkflowRun {
id: ID!
workflow: Workflow!
status: RunStatus!
input: JSON
output: JSON
durationMs: Int
startedAt: DateTime!
completedAt: DateTime
}
type FHIRPatient {
id: ID!
resourceType: String!
name: [JSON!]!
gender: String
birthDate: String
address: [JSON!]
telecom: [JSON!]
riskLevel: String
observations: [FHIRObservation!]!
encounters: [FHIREncounter!]!
}
type FHIRObservation {
id: ID!
resourceType: String!
status: String!
code: JSON!
subject: JSON!
valueQuantity: JSON
effectiveDateTime: DateTime
}
type FHIREncounter {
id: ID!
resourceType: String!
status: String!
class: JSON!
subject: JSON!
period: JSON
}
type WebhookSubscription {
id: ID!
url: String!
events: [String!]!
status: String!
project: Project!
createdAt: DateTime!
}
type Event {
id: ID!
type: String!
payload: JSON!
source: String!
timestamp: DateTime!
}
type SubmissionResult {
id: ID!
status: String!
message: String!
}
type Query {
organization(id: ID!): Organization
organizations(limit: Int, offset: Int): [Organization!]!
project(id: ID!): Project
projects(organizationId: ID!, limit: Int, offset: Int): [Project!]!
asset(id: ID!): MarketplaceAsset
assets(
type: AssetType
category: String
status: AssetStatus
minRating: Float
badges: [String!]
fhirResources: [String!]
limit: Int
offset: Int
): [MarketplaceAsset!]!
publishers(verified: Boolean, limit: Int): [Publisher!]!
agent(id: ID!): Agent
agents(projectId: ID!, limit: Int): [Agent!]!
workflow(id: ID!): Workflow
workflows(projectId: ID!, status: WorkflowStatus, limit: Int): [Workflow!]!
patient(id: ID!): FHIRPatient
patients(
riskLevel: String
program: String
limit: Int
offset: Int
): [FHIRPatient!]!
webhooks(projectId: ID!): [WebhookSubscription!]!
events(projectId: ID!, type: String, limit: Int): [Event!]!
}
type Mutation {
submitAsset(input: SubmitAssetInput!): SubmissionResult!
installAsset(assetId: ID!, projectId: ID!, config: JSON): AssetInstallation!
createDeployment(installationId: ID!, environment: String!, replicas: Int, hipaaMode: Boolean): Deployment!
createAgent(name: String!, projectId: ID!, runMode: String): Agent!
runAgent(agentId: ID!, patientId: String!, input: JSON): AgentSession!
createWorkflow(name: String!, projectId: ID!, steps: [String!]!): Workflow!
runWorkflow(workflowId: ID!, input: JSON): WorkflowRun!
createWebhook(projectId: ID!, url: String!, events: [String!]!): WebhookSubscription!
publishEvent(type: String!, payload: JSON!, projectId: ID!): Event!
}
type Subscription {
agentSessionUpdated(agentId: ID!): AgentSession!
workflowRunUpdated(workflowId: ID!): WorkflowRun!
eventStream(projectId: ID!, types: [String!]): Event!
deploymentStatusChanged(deploymentId: ID!): Deployment!
}
input SubmitAssetInput {
name: String!
description: String!
version: String!
type: AssetType!
category: String!
fhirResources: [String!]
pricingType: PricingType!
monthlyFee: Float
documentationUrl: String
supportEmail: String!
}Type System Explorer
Expand each root type to browse all available fields and their return types.
Example Operations
Query patient + observations
Fetch a patient record with recent observations and risk metadata.
Operation
query GetPatientWithObservations($patientId: ID!) {
patient(id: $patientId) {
id
name
gender
birthDate
riskLevel
observations {
id
status
code
valueQuantity
effectiveDateTime
}
encounters {
id
status
class
period
}
}
}Variables
{ "patientId": "pat_demo_001" }Response
{
"data": {
"patient": {
"id": "pat_demo_001",
"name": [{ "family": "Johnson-Rivera", "given": ["Maria"] }],
"gender": "female",
"birthDate": "1978-04-12",
"riskLevel": "high",
"observations": [
{
"id": "obs_hr_001",
"status": "final",
"code": { "coding": [{ "system": "http://loinc.org", "code": "8867-4" }] },
"valueQuantity": { "value": 78, "unit": "bpm" },
"effectiveDateTime": "2026-03-18T11:58:00Z"
}
],
"encounters": [
{
"id": "enc_demo_001",
"status": "finished",
"class": { "code": "AMB" },
"period": { "start": "2026-03-10T09:00:00Z", "end": "2026-03-10T09:45:00Z" }
}
]
}
}
}Send Request
const { data } = await fetch('https://api.healthcloud.ai/graphql', {
method: 'POST',
headers: {
'Authorization': 'Bearer hc_test_sk_demo_live_xxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
query: `query GetPatientWithObservations($patientId: ID!) {
patient(id: $patientId) {
id name gender birthDate riskLevel
observations { id status valueQuantity effectiveDateTime }
}
}`,
variables: { patientId: 'pat_demo_001' },
}),
}).then(r => r.json());Run agent (mutation)
Execute a clinical agent against a patient context and return reasoning output.
Operation
mutation RunClinicalAgent($agentId: ID!, $patientId: String!, $input: JSON) {
runAgent(agentId: $agentId, patientId: $patientId, input: $input) {
id
status
latencyMs
tokensUsed
output
completedAt
}
}Variables
{
"agentId": "agent_uti_v1",
"patientId": "Patient/pat_demo_001",
"input": {
"symptoms": ["dysuria", "frequency", "urgency"],
"durationDays": 3
}
}Response
{
"data": {
"runAgent": {
"id": "arun_gql_001",
"status": "COMPLETED",
"latencyMs": 1240,
"tokensUsed": 1842,
"output": {
"recommendation": "UTI likely — prescribe nitrofurantoin 100mg x 5d",
"confidence": 0.91,
"icd10": "N39.0"
},
"completedAt": "2026-03-18T12:00:01.240Z"
}
}
}Send Request
const { data } = await fetch('https://api.healthcloud.ai/graphql', {
method: 'POST',
headers: { 'Authorization': 'Bearer hc_test_sk_demo_live_xxxxxx', 'Content-Type': 'application/json' },
body: JSON.stringify({
query: `mutation RunClinicalAgent($agentId: ID!, $patientId: String!, $input: JSON) {
runAgent(agentId: $agentId, patientId: $patientId, input: $input) {
id status latencyMs tokensUsed output completedAt
}
}`,
variables: { agentId: 'agent_uti_v1', patientId: 'Patient/pat_demo_001', input: { symptoms: ['dysuria'] } },
}),
}).then(r => r.json());Subscribe to event stream
Open a real-time subscription to platform events for a project.
Operation
subscription ListenToProjectEvents($projectId: ID!, $types: [String!]) {
eventStream(projectId: $projectId, types: $types) {
id
type
payload
source
timestamp
}
}Variables
{
"projectId": "proj_rpm_001",
"types": ["workflow.completed", "agent.run_completed", "device.observation_received"]
}Response
# Server sends events as they occur:
{
"data": {
"eventStream": {
"id": "evt_live_001",
"type": "workflow.completed",
"payload": {
"workflowId": "wf_prior_auth_v2",
"runId": "wfrun_pa_xyz789",
"status": "approved",
"durationMs": 4200
},
"source": "workflow-engine",
"timestamp": "2026-03-18T12:05:00Z"
}
}
}Send Request
import { createClient } from 'graphql-ws';
const client = createClient({
url: 'wss://api.healthcloud.ai/graphql',
connectionParams: { Authorization: 'Bearer hc_test_sk_demo_live_xxxxxx' },
});
client.subscribe(
{
query: `subscription ListenToProjectEvents($projectId: ID!, $types: [String!]) {
eventStream(projectId: $projectId, types: $types) { id type payload source timestamp }
}`,
variables: { projectId: 'proj_rpm_001', types: ['workflow.completed', 'agent.run_completed'] },
},
{
next: (event) => console.log('Event received:', event.data?.eventStream),
error: (err) => console.error('Subscription error:', err),
complete: () => console.log('Subscription complete'),
}
);List assets with filtering
Fetch marketplace assets filtered by type, badge, and FHIR resource compatibility.
Operation
query ListClinicalAgents($badges: [String!], $fhirResources: [String!]) {
assets(
type: AGENT
badges: $badges
fhirResources: $fhirResources
minRating: 4.5
limit: 5
) {
id
name
version
rating
downloads
fhirResources
complianceScore { overall hipaaCompliant fdaCleared }
pricing { type costPerRequest monthlyFee }
publisher { name verified }
}
}Variables
{
"badges": ["hipaa_compliant"],
"fhirResources": ["Observation", "Patient"]
}Response
{
"data": {
"assets": [
{
"id": "agent_uti_v1",
"name": "UTI Screening Agent",
"version": "1.2.0",
"rating": 4.8,
"downloads": 15234,
"fhirResources": ["Patient", "Observation", "Condition"],
"complianceScore": { "overall": 96, "hipaaCompliant": true, "fdaCleared": false },
"pricing": { "type": "USAGE_BASED", "costPerRequest": 0.02, "monthlyFee": null },
"publisher": { "name": "HealthCloud Labs", "verified": true }
}
]
}
}Send Request
const { data } = await fetch('https://api.healthcloud.ai/graphql', {
method: 'POST',
headers: { 'Authorization': 'Bearer hc_test_sk_demo_live_xxxxxx', 'Content-Type': 'application/json' },
body: JSON.stringify({
query: `query ListClinicalAgents($badges: [String!], $fhirResources: [String!]) {
assets(type: AGENT, badges: $badges, fhirResources: $fhirResources, minRating: 4.5, limit: 5) {
id name version rating downloads
complianceScore { overall hipaaCompliant fdaCleared }
pricing { type costPerRequest monthlyFee }
publisher { name verified }
}
}`,
variables: { badges: ['hipaa_compliant'], fhirResources: ['Observation', 'Patient'] },
}),
}).then(r => r.json());Pagination
List queries accept limit (max 100, default 20) and offset for cursor-less pagination.
query PaginatedAssets {
assets(type: MODEL, limit: 20, offset: 40) {
id
name
version
}
}Error Handling
GraphQL always returns HTTP 200. Errors appear in the top-level errors array.
{
"errors": [
{
"message": "Asset not found",
"locations": [{ "line": 2, "column": 3 }],
"path": ["asset"],
"extensions": { "code": "NOT_FOUND", "assetId": "invalid-id" }
}
],
"data": null
}Try the GraphiQL Playground
Explore the schema interactively with autocomplete, inline docs, and live query execution.