{
  "openapi": "3.1.0",
  "info": {
    "title": "FHIR R4 Health Records API",
    "version": "R4",
    "description": "Practise healthcare API testing on a synthetic HL7 FHIR R4 subset: Patient, Observation (LOINC vitals) and Encounter, searchset Bundles with paging links, versioned ETags, 410 after delete and OperationOutcome errors. No real patient data."
  },
  "servers": [
    {
      "url": "https://funapi.dev/api/fhir/r4"
    }
  ],
  "tags": [
    {
      "name": "conformance",
      "description": "CapabilityStatement"
    },
    {
      "name": "Patient",
      "description": "demographics"
    },
    {
      "name": "Observation",
      "description": "vitals and labs"
    },
    {
      "name": "Encounter",
      "description": "visits"
    }
  ],
  "paths": {
    "/metadata": {
      "get": {
        "tags": [
          "conformance"
        ],
        "summary": "CapabilityStatement: what this server supports",
        "operationId": "fh-metadata",
        "responses": {
          "200": {
            "description": "CapabilityStatement",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resourceType": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "date": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string"
                    },
                    "fhirVersion": {
                      "type": "string"
                    },
                    "format": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "software": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "version": {
                          "type": "string"
                        }
                      }
                    },
                    "implementation": {
                      "type": "object",
                      "properties": {
                        "description": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        }
                      }
                    },
                    "rest": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "mode": {
                            "type": "string"
                          },
                          "security": {
                            "type": "object",
                            "properties": {
                              "description": {
                                "type": "string"
                              }
                            }
                          },
                          "resource": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string"
                                },
                                "interaction": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "code": {
                                        "type": "string"
                                      }
                                    }
                                  }
                                },
                                "versioning": {
                                  "type": "string"
                                },
                                "searchParam": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "name": {
                                        "type": "string"
                                      },
                                      "type": {
                                        "type": "string"
                                      }
                                    }
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/Patient": {
      "get": {
        "tags": [
          "Patient"
        ],
        "summary": "Search patients — name, family, given, gender, birthdate (ge/le), _count, _offset",
        "operationId": "fh-patient-search",
        "responses": {
          "200": {
            "description": "searchset Bundle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resourceType": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "total": {
                      "type": "number"
                    },
                    "link": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "relation": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "entry": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "fullUrl": {
                            "type": "string"
                          },
                          "resource": {
                            "type": "object",
                            "properties": {
                              "resourceType": {
                                "type": "string"
                              },
                              "id": {
                                "type": "string"
                              },
                              "meta": {
                                "type": "object",
                                "properties": {
                                  "versionId": {
                                    "type": "string"
                                  },
                                  "lastUpdated": {
                                    "type": "string"
                                  }
                                }
                              },
                              "identifier": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "system": {
                                      "type": "string"
                                    },
                                    "value": {
                                      "type": "string"
                                    }
                                  }
                                }
                              },
                              "active": {
                                "type": "boolean"
                              },
                              "name": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "use": {
                                      "type": "string"
                                    },
                                    "family": {
                                      "type": "string"
                                    },
                                    "given": {
                                      "type": "array",
                                      "items": {
                                        "type": "string"
                                      }
                                    }
                                  }
                                }
                              },
                              "gender": {
                                "type": "string"
                              },
                              "birthDate": {
                                "type": "string"
                              },
                              "telecom": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "system": {
                                      "type": "string"
                                    },
                                    "value": {
                                      "type": "string"
                                    }
                                  }
                                }
                              },
                              "address": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "city": {
                                      "type": "string"
                                    },
                                    "state": {
                                      "type": "string"
                                    },
                                    "country": {
                                      "type": "string"
                                    }
                                  }
                                }
                              }
                            }
                          },
                          "search": {
                            "type": "object",
                            "properties": {
                              "mode": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "OperationOutcome",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "family",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "gender",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "birthdate",
            "in": "query",
            "required": false,
            "description": "e.g. ge1980-01-01",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "_count",
            "in": "query",
            "required": false,
            "description": "Page size 0–100, default 10",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 5
          },
          {
            "name": "_offset",
            "in": "query",
            "required": false,
            "description": "Records to skip",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ]
      },
      "post": {
        "tags": [
          "Patient"
        ],
        "summary": "Create a synthetic patient (Bearer token)",
        "operationId": "fh-patient-create",
        "responses": {
          "201": {
            "description": "Created, Location with _history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resourceType": {
                      "type": "string"
                    },
                    "name": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "family": {
                            "type": "string"
                          },
                          "given": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "gender": {
                      "type": "string"
                    },
                    "birthDate": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "versionId": {
                          "type": "string"
                        },
                        "lastUpdated": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                }
              }
            }
          },
          "401": {
            "description": "No token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "OperationOutcome: invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "resourceType": {
                    "type": "string"
                  },
                  "name": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "family": {
                          "type": "string"
                        },
                        "given": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  },
                  "gender": {
                    "type": "string"
                  },
                  "birthDate": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "resourceType": "Patient",
                "name": [
                  {
                    "family": "Example",
                    "given": [
                      "Test"
                    ]
                  }
                ],
                "gender": "female",
                "birthDate": "1990-01-01"
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/Patient/{id}": {
      "get": {
        "tags": [
          "Patient"
        ],
        "summary": "Read a patient (ETag W/\"versionId\"); deleted → 410",
        "operationId": "fh-patient-read",
        "responses": {
          "200": {
            "description": "Patient",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resourceType": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "versionId": {
                          "type": "string"
                        },
                        "lastUpdated": {
                          "type": "string"
                        }
                      }
                    },
                    "identifier": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "system": {
                            "type": "string"
                          },
                          "value": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "active": {
                      "type": "boolean"
                    },
                    "name": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "use": {
                            "type": "string"
                          },
                          "family": {
                            "type": "string"
                          },
                          "given": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "gender": {
                      "type": "string"
                    },
                    "birthDate": {
                      "type": "string"
                    },
                    "telecom": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "system": {
                            "type": "string"
                          },
                          "value": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "address": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "city": {
                            "type": "string"
                          },
                          "state": {
                            "type": "string"
                          },
                          "country": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "304": {
            "description": "Not modified"
          },
          "404": {
            "description": "OperationOutcome: not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Patient"
        ],
        "summary": "Update a patient; If-Match enforces the version",
        "operationId": "fh-patient-update",
        "responses": {
          "200": {
            "description": "Updated, versionId incremented",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resourceType": {
                      "type": "string"
                    },
                    "name": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "family": {
                            "type": "string"
                          },
                          "given": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    },
                    "gender": {
                      "type": "string"
                    },
                    "birthDate": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "versionId": {
                          "type": "string"
                        },
                        "lastUpdated": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Version conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "W/\"<versionId>\" from the last read; stale → 412",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "resourceType": {
                    "type": "string"
                  },
                  "name": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "family": {
                          "type": "string"
                        },
                        "given": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  },
                  "gender": {
                    "type": "string"
                  },
                  "birthDate": {
                    "type": "string"
                  },
                  "id": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "resourceType": "Patient",
                "name": [
                  {
                    "family": "Example",
                    "given": [
                      "Test"
                    ]
                  }
                ],
                "gender": "female",
                "birthDate": "1990-01-01",
                "id": "1"
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "delete": {
        "tags": [
          "Patient"
        ],
        "summary": "Delete a patient (admin); later reads return 410 Gone",
        "operationId": "fh-patient-delete",
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "403": {
            "description": "Viewer token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/Observation": {
      "get": {
        "tags": [
          "Observation"
        ],
        "summary": "Search observations — patient, code (LOINC), category, date",
        "operationId": "fh-obs-search",
        "responses": {
          "200": {
            "description": "searchset Bundle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resourceType": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "total": {
                      "type": "number"
                    },
                    "link": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "relation": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "entry": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "fullUrl": {
                            "type": "string"
                          },
                          "resource": {
                            "type": "object",
                            "properties": {
                              "resourceType": {
                                "type": "string"
                              },
                              "id": {
                                "type": "string"
                              },
                              "meta": {
                                "type": "object",
                                "properties": {
                                  "versionId": {
                                    "type": "string"
                                  },
                                  "lastUpdated": {
                                    "type": "string"
                                  }
                                }
                              },
                              "status": {
                                "type": "string"
                              },
                              "category": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "coding": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "properties": {
                                          "system": {
                                            "type": "string"
                                          },
                                          "code": {
                                            "type": "string"
                                          }
                                        }
                                      }
                                    }
                                  }
                                }
                              },
                              "code": {
                                "type": "object",
                                "properties": {
                                  "coding": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "system": {
                                          "type": "string"
                                        },
                                        "code": {
                                          "type": "string"
                                        },
                                        "display": {
                                          "type": "string"
                                        }
                                      }
                                    }
                                  },
                                  "text": {
                                    "type": "string"
                                  }
                                }
                              },
                              "subject": {
                                "type": "object",
                                "properties": {
                                  "reference": {
                                    "type": "string"
                                  }
                                }
                              },
                              "encounter": {
                                "type": "object",
                                "properties": {
                                  "reference": {
                                    "type": "string"
                                  }
                                }
                              },
                              "effectiveDateTime": {
                                "type": "string"
                              },
                              "valueQuantity": {
                                "type": "object",
                                "properties": {
                                  "value": {
                                    "type": "number"
                                  },
                                  "unit": {
                                    "type": "string"
                                  },
                                  "system": {
                                    "type": "string"
                                  },
                                  "code": {
                                    "type": "string"
                                  }
                                }
                              }
                            }
                          },
                          "search": {
                            "type": "object",
                            "properties": {
                              "mode": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "OperationOutcome",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "patient",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1"
          },
          {
            "name": "code",
            "in": "query",
            "required": false,
            "description": "e.g. 8867-4 or http://loinc.org|8867-4",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "vital-signs or laboratory",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "_count",
            "in": "query",
            "required": false,
            "description": "Page size 0–100, default 10",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 5
          },
          {
            "name": "_offset",
            "in": "query",
            "required": false,
            "description": "Records to skip",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ]
      },
      "post": {
        "tags": [
          "Observation"
        ],
        "summary": "Record an observation; subject must reference an existing Patient",
        "operationId": "fh-obs-create",
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resourceType": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "code": {
                      "type": "object",
                      "properties": {
                        "coding": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "system": {
                                "type": "string"
                              },
                              "code": {
                                "type": "string"
                              },
                              "display": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    },
                    "subject": {
                      "type": "object",
                      "properties": {
                        "reference": {
                          "type": "string"
                        }
                      }
                    },
                    "valueQuantity": {
                      "type": "object",
                      "properties": {
                        "value": {
                          "type": "number"
                        },
                        "unit": {
                          "type": "string"
                        },
                        "system": {
                          "type": "string"
                        },
                        "code": {
                          "type": "string"
                        }
                      }
                    },
                    "id": {
                      "type": "string"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "versionId": {
                          "type": "string"
                        },
                        "lastUpdated": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                }
              }
            }
          },
          "422": {
            "description": "OperationOutcome: invalid or dangling reference",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "resourceType": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  },
                  "code": {
                    "type": "object",
                    "properties": {
                      "coding": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "system": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "display": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  },
                  "subject": {
                    "type": "object",
                    "properties": {
                      "reference": {
                        "type": "string"
                      }
                    }
                  },
                  "valueQuantity": {
                    "type": "object",
                    "properties": {
                      "value": {
                        "type": "number"
                      },
                      "unit": {
                        "type": "string"
                      },
                      "system": {
                        "type": "string"
                      },
                      "code": {
                        "type": "string"
                      }
                    }
                  }
                }
              },
              "example": {
                "resourceType": "Observation",
                "status": "final",
                "code": {
                  "coding": [
                    {
                      "system": "http://loinc.org",
                      "code": "8867-4",
                      "display": "Heart rate"
                    }
                  ]
                },
                "subject": {
                  "reference": "Patient/1"
                },
                "valueQuantity": {
                  "value": 72,
                  "unit": "beats/minute",
                  "system": "http://unitsofmeasure.org",
                  "code": "/min"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/Observation/{id}": {
      "get": {
        "tags": [
          "Observation"
        ],
        "summary": "Read an observation",
        "operationId": "fh-obs-read",
        "responses": {
          "200": {
            "description": "Observation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resourceType": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "versionId": {
                          "type": "string"
                        },
                        "lastUpdated": {
                          "type": "string"
                        }
                      }
                    },
                    "status": {
                      "type": "string"
                    },
                    "category": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "coding": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "system": {
                                  "type": "string"
                                },
                                "code": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "code": {
                      "type": "object",
                      "properties": {
                        "coding": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "system": {
                                "type": "string"
                              },
                              "code": {
                                "type": "string"
                              },
                              "display": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "text": {
                          "type": "string"
                        }
                      }
                    },
                    "subject": {
                      "type": "object",
                      "properties": {
                        "reference": {
                          "type": "string"
                        }
                      }
                    },
                    "encounter": {
                      "type": "object",
                      "properties": {
                        "reference": {
                          "type": "string"
                        }
                      }
                    },
                    "effectiveDateTime": {
                      "type": "string"
                    },
                    "valueQuantity": {
                      "type": "object",
                      "properties": {
                        "value": {
                          "type": "number"
                        },
                        "unit": {
                          "type": "string"
                        },
                        "system": {
                          "type": "string"
                        },
                        "code": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/Encounter": {
      "get": {
        "tags": [
          "Encounter"
        ],
        "summary": "Search encounters — patient, status, class",
        "operationId": "fh-enc-search",
        "responses": {
          "200": {
            "description": "searchset Bundle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resourceType": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "total": {
                      "type": "number"
                    },
                    "link": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "relation": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "entry": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "fullUrl": {
                            "type": "string"
                          },
                          "resource": {
                            "type": "object",
                            "properties": {
                              "resourceType": {
                                "type": "string"
                              },
                              "id": {
                                "type": "string"
                              },
                              "meta": {
                                "type": "object",
                                "properties": {
                                  "versionId": {
                                    "type": "string"
                                  },
                                  "lastUpdated": {
                                    "type": "string"
                                  }
                                }
                              },
                              "status": {
                                "type": "string"
                              },
                              "class": {
                                "type": "object",
                                "properties": {
                                  "system": {
                                    "type": "string"
                                  },
                                  "code": {
                                    "type": "string"
                                  },
                                  "display": {
                                    "type": "string"
                                  }
                                }
                              },
                              "subject": {
                                "type": "object",
                                "properties": {
                                  "reference": {
                                    "type": "string"
                                  }
                                }
                              },
                              "period": {
                                "type": "object",
                                "properties": {
                                  "start": {
                                    "type": "string"
                                  },
                                  "end": {
                                    "type": "string"
                                  }
                                }
                              }
                            }
                          },
                          "search": {
                            "type": "object",
                            "properties": {
                              "mode": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "patient",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "_count",
            "in": "query",
            "required": false,
            "description": "Page size 0–100, default 10",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 5
          },
          {
            "name": "_offset",
            "in": "query",
            "required": false,
            "description": "Records to skip",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ]
      }
    },
    "/Encounter/{id}": {
      "get": {
        "tags": [
          "Encounter"
        ],
        "summary": "Read an encounter",
        "operationId": "fh-enc-read",
        "responses": {
          "200": {
            "description": "Encounter",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resourceType": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "versionId": {
                          "type": "string"
                        },
                        "lastUpdated": {
                          "type": "string"
                        }
                      }
                    },
                    "status": {
                      "type": "string"
                    },
                    "class": {
                      "type": "object",
                      "properties": {
                        "system": {
                          "type": "string"
                        },
                        "code": {
                          "type": "string"
                        },
                        "display": {
                          "type": "string"
                        }
                      }
                    },
                    "subject": {
                      "type": "object",
                      "properties": {
                        "reference": {
                          "type": "string"
                        }
                      }
                    },
                    "period": {
                      "type": "object",
                      "properties": {
                        "start": {
                          "type": "string"
                        },
                        "end": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Use qa-admin-token / qa-viewer-token, or a JWT from POST /auth/v1/login."
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Cargo demo key: cargo-key-123."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "requestId": {
            "type": "string"
          }
        },
        "additionalProperties": true
      }
    }
  }
}
