Medplum — FHIR REST API

naftiko: 1.0.0-alpha2
info:
  label: Medplum — FHIR REST API
  description: >-
    Generic FHIR R4 REST operations exposed by Medplum at https://api.medplum.com/fhir/R4.
    Covers create, read, update, delete, patch, search, and history operations across all
    FHIR resource types. Self-contained Naftiko capability over the Medplum FHIR business surface.
  tags:
    - Medplum
    - FHIR
    - Healthcare
    - REST
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
  - namespace: env
    keys:
      MEDPLUM_ACCESS_TOKEN: MEDPLUM_ACCESS_TOKEN
capability:
  consumes:
    - type: http
      namespace: medplum-fhir
      baseUri: https://api.medplum.com/fhir/R4
      description: Medplum FHIR R4 REST surface. Bearer token (OAuth 2.0 / SMART on FHIR) auth.
      resources:
        - name: Resource
          path: /{resourceType}
          operations:
            - name: search
              method: GET
              description: Search all resources of a given FHIR resourceType using FHIR search parameters.
              outputRawFormat: json
              inputParameters:
                - name: resourceType
                  in: path
                  type: string
                  required: true
                  description: FHIR resource type (e.g., Patient, Observation, Encounter).
                - name: _count
                  in: query
                  type: integer
                  description: Page size for search results.
                - name: _sort
                  in: query
                  type: string
                  description: Comma-separated list of sort fields.
            - name: createResource
              method: POST
              description: Create a new FHIR resource of the given resourceType.
              outputRawFormat: json
              inputParameters:
                - name: resourceType
                  in: path
                  type: string
                  required: true
                - name: body
                  in: body
                  type: object
                  required: true
                  description: FHIR resource JSON body conforming to R4 schema.
        - name: ResourceInstance
          path: /{resourceType}/{id}
          operations:
            - name: readResource
              method: GET
              description: Read a single FHIR resource by id.
              outputRawFormat: json
              inputParameters:
                - name: resourceType
                  in: path
                  type: string
                  required: true
                - name: id
                  in: path
                  type: string
                  required: true
            - name: updateResource
              method: PUT
              description: Update a FHIR resource by id (full replace).
              outputRawFormat: json
              inputParameters:
                - name: resourceType
                  in: path
                  type: string
                  required: true
                - name: id
                  in: path
                  type: string
                  required: true
                - name: body
                  in: body
                  type: object
                  required: true
            - name: patchResource
              method: PATCH
              description: Apply a JSON Patch to a FHIR resource.
              outputRawFormat: json
              inputParameters:
                - name: resourceType
                  in: path
                  type: string
                  required: true
                - name: id
                  in: path
                  type: string
                  required: true
                - name: body
                  in: body
                  type: array
                  required: true
                  description: JSON Patch document.
            - name: deleteResource
              method: DELETE
              description: Soft-delete a FHIR resource.
              inputParameters:
                - name: resourceType
                  in: path
                  type: string
                  required: true
                - name: id
                  in: path
                  type: string
                  required: true
        - name: ResourceHistory
          path: /{resourceType}/{id}/_history
          operations:
            - name: readResourceHistory
              method: GET
              description: Retrieve the version history of a FHIR resource.
              outputRawFormat: json
              inputParameters:
                - name: resourceType
                  in: path
                  type: string
                  required: true
                - name: id
                  in: path
                  type: string
                  required: true
        - name: ResourceVersion
          path: /{resourceType}/{id}/_history/{versionId}
          operations:
            - name: readVersion
              method: GET
              description: Read a specific version of a FHIR resource.
              outputRawFormat: json
              inputParameters:
                - name: resourceType
                  in: path
                  type: string
                  required: true
                - name: id
                  in: path
                  type: string
                  required: true
                - name: versionId
                  in: path
                  type: string
                  required: true