Skip to main content
GET
/
{resourceType}
/
{id}
/
_history
/
{vid}
Versioned Read (vread)
curl --request GET \
  --url http://localhost:8080/fhir/{resourceType}/{id}/_history/{vid} \
  --header 'Authorization: Bearer <token>'
{
  "resourceType": "<string>",
  "id": "<string>",
  "meta": {
    "versionId": "<string>",
    "lastUpdated": "2023-11-07T05:31:56Z",
    "profile": [
      "<string>"
    ],
    "tag": [
      {
        "system": "<string>",
        "version": "<string>",
        "code": "<string>",
        "display": "<string>"
      }
    ],
    "security": [
      {
        "system": "<string>",
        "version": "<string>",
        "code": "<string>",
        "display": "<string>"
      }
    ]
  }
}

​
Versioned Read (vread)

Retrieve a specific version of a resource by its version ID.
​
resource_type
string
required
The FHIR resource type (e.g., Patient, Observation, Encounter)
​
id
string
required
The logical ID of the resource
​
vid
string
required
The version ID of the resource

​
Endpoint

GET /fhir/:resource_type/:id/_history/:vid

​
Example Request

curl "https://your-server.com/fhir/Patient/123/_history/2"

​
Response

​
Success (200 OK)

Returns the resource at the specified version: 
{
  "resourceType": "Patient",
  "id": "123",
  "meta": {
    "versionId": "2",
    "lastUpdated": "2024-01-01T13:00:00Z"
  },
  "name": [
    {
      "family": "Doe",
      "given": ["Jane"]
    }
  ],
  "gender": "male",
  "birthDate": "1990-01-01"
}

​
Not Found (404)

Returns an error if the resource or version doesn’t exist: 
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Resource Patient/123/_history/2 not found"
      }
    }
  ]
}

​
HEAD Request

Use HEAD to check if a specific version exists without retrieving its body: 
HEAD /fhir/Patient/123/_history/2
Returns 200 OK if the version exists, 404 Not Found otherwise. No response body is returned.

​
Use Cases

Versioned read is useful for:
  • Audit Trail: Viewing what a resource looked like at a specific point in time
  • Rollback: Comparing versions before reverting changes
  • Compliance: Retrieving historical versions for regulatory requirements
  • Debugging: Understanding how a resource changed over time

​
Getting Version IDs

You can get version IDs from:
  1. Resource metadata: The meta.versionId field in any resource
  2. History endpoint: The _history endpoint lists all versions
  3. ETag header: The ETag header in responses (format: W/"versionId")

​
Example Workflow

  1. Read current version: 
    GET /fhir/Patient/123
# Returns version 3
  2. Read previous version: 
    GET /fhir/Patient/123/_history/2
# Returns version 2
  3. Compare versions to see what changed

​
Notes

  • Version IDs are sequential integers starting from 1
  • Version 1 is always the original creation
  • Deleted resources can still be read by version ID
  • Version IDs are immutable - they never change
  • Use vread to access historical versions for audit or compliance purposes

Authorizations

​
Authorization
string
header
required

Bearer token authentication

Path Parameters

​
resourceType
string
required

The FHIR resource type (e.g., Patient, Observation, Encounter)

​
id
string
required

The logical ID of the resource

​
vid
string
required

The version ID

Response

Resource version

A FHIR resource. All resources have resourceType, id, and meta fields.

​
resourceType
string
required

The type of resource

​
id
string

Logical id of this artifact

​
meta
object

Metadata about a resource