Instance-Level Operations

Execute FHIR operations on a specific resource instance.

string

required

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

string

required

The logical ID of the resource

string

required

The operation name (e.g., $validate, $everything, $meta)

Endpoint

GET /fhir/:resource_type/:id/$:operation
POST /fhir/:resource_type/:id/$:operation

Use GET for operations that only read data, or POST for operations that require input parameters.

Example Request

curl -X POST \
     -H "Content-Type: application/fhir+json" \
     -d '{"resourceType":"Parameters"}' \
     https://your-server.com/fhir/Patient/123/$validate

POST /fhir/Patient/123/$validate HTTP/1.1
Host: your-server.com
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  ...
}

Common Instance Operations

$validate

Validate a specific resource instance:

POST /fhir/Patient/123/$validate
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "resource",
      "resource": {
        "resourceType": "Patient",
        "id": "123",
        "name": [{"family": "Doe"}]
      }
    }
  ]
}

$everything (Patient)

Get all resources related to a specific patient:

GET /fhir/Patient/123/$everything

Or with parameters:

POST /fhir/Patient/123/$everything
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "_since",
      "valueDateTime": "2024-01-01T00:00:00Z"
    },
    {
      "name": "_type",
      "valueString": "Observation,MedicationRequest"
    }
  ]
}

$meta

Read or update resource metadata:

GET /fhir/Patient/123/$meta

Update metadata:

POST /fhir/Patient/123/$meta
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "meta",
      "valueMeta": {
        "tag": [
          {
            "system": "http://example.org/tags",
            "code": "important"
          }
        ]
      }
    }
  ]
}

Request Format

Operations use a Parameters resource for input:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "parameter-name",
      "valueString": "parameter-value"
    },
    {
      "name": "resource",
      "resource": {
        "resourceType": "Patient",
        "id": "123",
        ...
      }
    }
  ]
}

Response

Success (200 OK)

Returns operation results, typically as a Parameters resource or a Bundle:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "resource": {
        "resourceType": "Observation",
        "subject": {
          "reference": "Patient/123"
        },
        ...
      }
    }
  ]
}

Error (400 Bad Request)

Returns an OperationOutcome if the operation fails:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Operation $unknown not supported for Patient/123"
      }
    }
  ]
}

Not Found (404)

Returns an error if the resource doesn’t exist:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Resource Patient/123 not found"
      }
    }
  ]
}

Available Operations

The available instance-level operations depend on server configuration and resource type. Check the capability statement (/fhir/metadata) to see which operations are supported:

{
  "rest": [
    {
      "resource": [
        {
          "type": "Patient",
          "operation": [
            {
              "name": "$validate",
              "definition": "http://hl7.org/fhir/OperationDefinition/Resource-validate"
            },
            {
              "name": "$everything",
              "definition": "http://hl7.org/fhir/OperationDefinition/Patient-everything"
            }
          ]
        }
      ]
    }
  ]
}

Notes

Instance operations apply to a specific resource
Available operations vary by resource type
Operations may require specific permissions
Use POST when operations require input parameters
Operation names are case-sensitive and start with $
The resource must exist for instance operations to work

Overview

Metadata

CRUD Operations

Search

History & Versioning

Batch & Transaction

Operations

Instance-Level Operations