FAR Package Management API

Manage FHIR packages with npm-style operations exposed as FHIR operations.

$fhir-package-install

Installs FHIR Implementation Guide packages from a registry or direct URL. Downloads, validates, and installs packages along with their dependencies.

The default NPM registry URL can be changed via the FHIR NPM Package registry setting.

POST /fhir/$fhir-package-install

Installation Behavior

During installation, Aidbox performs pinning and tree-shaking on canonicals:

The Core package (e.g., hl7.fhir.r4.core) is automatically installed if missing.
The Terminology (THO) package must be provided explicitly if needed.
Only referenced canonicals from dependency packages are included (tree-shaking).
Each canonical <url>|<version> pair is unique in the final result.

For details on the candidate selection algorithm and recursive pinning process, see Pinning and Tree-Shaking.

Input Parameters

Name	Card.	Type	Description
package	1..*	string	Package specification in one of the following formats: `<name>@<version>` — identifier from the registry (e.g., `hl7.fhir.us.core@5.0.0`) `https://` — remote gzipped tarball URL (e.g., `https://example.org/package.tgz`) `file://` — local gzipped tarball path (e.g., `file:///path/to/package.tgz`)
registry	0..1	url	Package registry URL used for resolving non-local packages. Defaults to `https://fs.get-ig.org/pkgs`.

Output Parameters

Parameter	Cardinality	Type	Example	Description
result	1..1	boolean	`true`	Whether the installation succeeded.
package	1..*			Installed package information.
package.name	1..1	string	`hl7.fhir.us.core@5.0.0`	Package identifier in `<name>@<version>` format.
package.installedCanonicals	1..1	integer	`194`	Number of canonical resources installed.
package.intention	1..1	string	`direct` / `transitive`	Whether installed directly or as a dependency.
package.source.type	1..1	string	`npm` / `file`	Source type from which the package was fetched.
package.source.registry	0..1	string	`https://fs.get-ig.org/pkgs`	Package registry URL.

Examples

Install package from default registry

POST /fhir/$fhir-package-install
Content-Type: application/json
Accept: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "package",
      "valueString": "hl7.fhir.us.core@5.0.0"
    }
  ]
}

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "result",
      "valueBoolean": true
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.fhir.us.core@5.0.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 194
        },
        {
          "name": "intention",
          "valueString": "direct"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "us.nlm.vsac@0.3.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 20
        },
        {
          "name": "intention",
          "valueString": "transitive"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.fhir.uv.sdc@3.0.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 11
        },
        {
          "name": "intention",
          "valueString": "transitive"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.terminology.r4@3.1.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 7
        },
        {
          "name": "intention",
          "valueString": "transitive"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    }
  ]
}

Install package from specific registry

POST /fhir/$fhir-package-install
Content-Type: application/json
Accept: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "package",
      "valueString": "hl7.fhir.us.core@5.0.0"
    },
    {
      "name": "registry",
      "valueString": "https://packages.simplifier.net"
    }
  ]
}

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "result",
      "valueBoolean": true
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.fhir.us.core@5.0.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 194
        },
        {
          "name": "intention",
          "valueString": "direct"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "us.nlm.vsac@0.3.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 20
        },
        {
          "name": "intention",
          "valueString": "transitive"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.fhir.uv.sdc@3.0.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 11
        },
        {
          "name": "intention",
          "valueString": "transitive"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.terminology.r4@3.1.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 7
        },
        {
          "name": "intention",
          "valueString": "transitive"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    }
  ]
}

Install latest version of package

POST /fhir/$fhir-package-install
Content-Type: application/json
Accept: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "package",
      "valueString": "hl7.fhir.us.core"
    }
  ]
}

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "result",
      "valueBoolean": true
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.fhir.us.core@8.0.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 205
        },
        {
          "name": "intention",
          "valueString": "direct"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "us.nlm.vsac@0.23.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 96
        },
        {
          "name": "intention",
          "valueString": "transitive"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.terminology.r4@6.4.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 23
        },
        {
          "name": "intention",
          "valueString": "transitive"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.fhir.uv.extensions.r4@5.2.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 2
        },
        {
          "name": "intention",
          "valueString": "transitive"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "us.cdc.phinvads@0.12.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 2
        },
        {
          "name": "intention",
          "valueString": "transitive"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.fhir.uv.sdc@3.0.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 11
        },
        {
          "name": "intention",
          "valueString": "transitive"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    }
  ]
}

Install package from a local file

POST /fhir/$fhir-package-install
Content-Type: application/json
Accept: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "package",
      "valueString": "file:///tmp/my-package.tgz"
    }
  ]
}

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "result",
      "valueBoolean": true
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "my.package@1.0.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 5
        },
        {
          "name": "intention",
          "valueString": "direct"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "file"
            }
          ]
        }
      ]
    },
  ]
}

Install multiple packages

POST /fhir/$fhir-package-install
Content-Type: application/json
Accept: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "package",
      "valueString": "hl7.fhir.us.core@5.0.0"
    },
    {
      "name": "package",
      "valueString": "hl7.fhir.us.mcode@2.0.0"
    }
  ]
}

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "result",
      "valueBoolean": true
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.fhir.us.core@5.0.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 194
        },
        {
          "name": "intention",
          "valueString": "direct"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.fhir.us.mcode@2.0.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 153
        },
        {
          "name": "intention",
          "valueString": "direct"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "us.nlm.vsac@0.3.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 20
        },
        {
          "name": "intention",
          "valueString": "transitive"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.fhir.uv.sdc@3.0.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 11
        },
        {
          "name": "intention",
          "valueString": "transitive"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.terminology.r4@3.1.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 7
        },
        {
          "name": "intention",
          "valueString": "transitive"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.fhir.us.core@4.0.0"
        },
        {
          "name": "installedCanonicals",
          "valueInteger": 30
        },
        {
          "name": "intention",
          "valueString": "transitive"
        },
        {
          "name": "source",
          "part": [
            {
              "name": "type",
              "valueString": "npm"
            },
            {
              "name": "registry",
              "valueString": "https://fs.get-ig.org/pkgs"
            }
          ]
        }
      ]
    }
  ]
}

$fhir-package-uninstall

Uninstalls FHIR Implementation Guide packages from the server. Removes the specified packages and their canonical resources.

POST /fhir/$fhir-package-uninstall

Input Parameters

Name	Card.	Type	Description
package	1..*	string	Package identifier in `<name>@<version>` format (e.g., `hl7.fhir.us.core@5.0.0`).

Output Parameters

Parameter	Cardinality	Type	Example	Description
result	1..1	boolean	`true`	Whether the uninstallation succeeded.
package	1..*			Uninstalled package information.
package.name	1..1	string	`hl7.fhir.us.core@5.0.0`	Package identifier in `<name>@<version>` format.
package.status	1..1	string	`deleted`	Status of the uninstallation.

Examples

Uninstall package

POST /fhir/$fhir-package-uninstall
Content-Type: application/json
Accept: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "package",
      "valueString": "hl7.fhir.us.core@8.0.0"
    }
  ]
}

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "result",
      "valueBoolean": true
    },
    {
      "name": "package",
      "part": [
        {
          "name": "name",
          "valueString": "hl7.fhir.us.core@8.0.0"
        },
        {
          "name": "status",
          "valueString": "deleted"
        }
      ]
    }
  ]
}

$fhir-package-install

Installation Behavior

Input Parameters

Output Parameters

Examples

$fhir-package-uninstall

Input Parameters

Output Parameters

Examples

See also