How do I install the Fhir API skill?

Run npx skillmds@latest add diegosouzapw/fhir-api in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Fhir API safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: makes network calls. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Fhir API?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Fhir API free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Fhir API?

diegosouzapw (@diegosouzapw) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Fhir API by diegosouzapw — Agent Skill

Name: Fhir API
Rating: 4.2 (5 reviews)
Author: diegosouzapw

Fhir API

Expert guidance for implementing FHIR RESTful API servers and clients following the HL7 FHIR specification. Use this skill when implementing a FHIR server with REST endpoints, building a FHIR client, designing FHIR API routes and handlers, implementing FHIR operations (read, create, update, delete, search, history), working with FHIR bundles, batch requests, or transactions, handling FHIR content negotiation, headers, and versioning, or implementing conditional operations. Trigger keywords include "FHIR REST", "FHIR API", "FHIR server", "FHIR client", "FHIR endpoint", "FHIR operations", "RESTful FHIR", "implement FHIR".

diegosouzapw Updated Sep 8, 2026 54 repo stars

File contents

FHIR REST API implementation

This skill provides guidance for implementing FHIR RESTful APIs according to the HL7 FHIR specification (R4/R5).

URL structure

All FHIR REST URLs follow the pattern:

[base]/[type]/[id]

[base]: Service base URL (e.g., https://fhir.example.org/r4)
[type]: Resource type (e.g., Patient, Observation)
[id]: Logical resource ID

URLs are case-sensitive and use UTF-8 encoding.

Core operations

Operation	HTTP	URL Pattern	Success
Read	GET	`[base]/[type]/[id]`	200
VRead	GET	`[base]/[type]/[id]/_history/[vid]`	200
Create	POST	`[base]/[type]`	201
Update	PUT	`[base]/[type]/[id]`	200/201
Patch	PATCH	`[base]/[type]/[id]`	200
Delete	DELETE	`[base]/[type]/[id]`	200/204
Search	GET/POST	`[base]/[type]?params`	200
History	GET	`[base]/[type]/[id]/_history`	200
Capabilities	GET	`[base]/metadata`	200
Batch/Transaction	POST	`[base]`	200

For detailed specifications of each operation, see references/operations.md.

Content negotiation

MIME types

Format	MIME Type
JSON	`application/fhir+json`
XML	`application/fhir+xml`
RDF	`application/fhir+turtle`

Use the Accept header for response format and Content-Type for request body format.

The _format query parameter overrides Accept when clients cannot set headers.

FHIR version

Specify version via MIME type parameter:

Accept: application/fhir+json; fhirVersion=4.0

Version mappings: 1.0 (R2), 3.0 (R3), 4.0 (R4), 4.3 (R4B), 5.0 (R5).

Required headers

Request headers

Header	Purpose	Example
Accept	Response format	`application/fhir+json`
Content-Type	Request body format	`application/fhir+json`
If-Match	Optimistic locking	`W/"123"`
If-None-Exist	Conditional create	`identifier=123`
Prefer	Return preference	`return=representation`

Response headers

Header	Purpose	Example
ETag	Version identifier	`W/"123"`
Location	New resource URL	`[base]/Patient/123/_history/1`
Last-Modified	Modification time	RFC 7231 date

Versioning and optimistic locking

FHIR uses weak ETags for version tracking:

Server returns ETag: W/"[versionId]" with responses
Client sends If-Match: W/"[versionId]" with updates
Server returns 412 Precondition Failed if version mismatch

Implement version-aware updates when CapabilityStatement.rest.resource.versioning is versioned-update.

Error handling

Return OperationOutcome resources for all errors:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "invalid",
            "diagnostics": "Patient.birthDate: Invalid date format"
        }
    ]
}

Status codes

Code	Meaning
400	Invalid syntax or validation failure
404	Resource not found
409	Version conflict
410	Resource deleted
412	Precondition failed (version mismatch)
422	Business rule violation

Prefer header

Control response content with Prefer:

Value	Response body
`return=minimal`	Empty (headers only)
`return=representation`	Full resource
`return=OperationOutcome`	Validation outcome

For async operations, use Prefer: respond-async to get 202 Accepted with status polling URL.

Implementation checklist

Server implementations should:

Implement CapabilityStatement at /metadata
Support content negotiation (JSON at minimum)
Return proper ETags for versioned resources
Include Location header on create/update
Return OperationOutcome for all errors
Support _format parameter fallback
Honour Prefer header for response content

References

operations.md: Detailed operation specifications
search.md: Search parameter and result handling
batch-transaction.md: Batch and transaction processing

---name: fhir-apidescription: Expert guidance for implementing FHIR RESTful API servers and clients following the HL7 FHIR specification. Use this skill when implementing a FHIR server with REST endpoints, building a FHIR client, designing FHIR API routes and handlers, implementing FHIR operations (read, create, update, delete, search, history), working with FHIR bundles, batch requests, or transactions, handling FHIR content negotiation, headers, and versioning, or implementing conditional operations. Trigger keywords include "FHIR REST", "FHIR API", "FHIR server", "FHIR client", "FHIR endpoint", "FHIR operations", "RESTful FHIR", "implement FHIR".---# FHIR REST API implementationThis skill provides guidance for implementing FHIR RESTful APIs according to the HL7 FHIR specification (R4/R5).## URL structureAll FHIR REST URLs follow the pattern:```[base]/[type]/[id]```- `[base]`: Service base URL (e.g., `https://fhir.example.org/r4`)- `[type]`: Resource type (e.g., `Patient`, `Observation`)- `[id]`: Logical resource IDURLs are case-sensitive and use UTF-8 encoding.## Core operations| Operation | HTTP | URL Pattern | Success || ----------------- | -------- | ----------------------------------- | ------- || Read | GET | `[base]/[type]/[id]` | 200 || VRead | GET | `[base]/[type]/[id]/_history/[vid]` | 200 || Create | POST | `[base]/[type]` | 201 || Update | PUT | `[base]/[type]/[id]` | 200/201 || Patch | PATCH | `[base]/[type]/[id]` | 200 || Delete | DELETE | `[base]/[type]/[id]` | 200/204 || Search | GET/POST | `[base]/[type]?params` | 200 || History | GET | `[base]/[type]/[id]/_history` | 200 || Capabilities | GET | `[base]/metadata` | 200 || Batch/Transaction | POST | `[base]` | 200 |For detailed specifications of each operation, see [references/operations.md](references/operations.md).## Content negotiation### MIME types| Format | MIME Type || ------ | ------------------------- || JSON | `application/fhir+json` || XML | `application/fhir+xml` || RDF | `application/fhir+turtle` |Use the `Accept` header for response format and `Content-Type` for request body format.The `_format` query parameter overrides `Accept` when clients cannot set headers.### FHIR versionSpecify version via MIME type parameter:```Accept: application/fhir+json; fhirVersion=4.0```Version mappings: 1.0 (R2), 3.0 (R3), 4.0 (R4), 4.3 (R4B), 5.0 (R5).## Required headers### Request headers| Header | Purpose | Example || ------------- | ------------------- | ----------------------- || Accept | Response format | `application/fhir+json` || Content-Type | Request body format | `application/fhir+json` || If-Match | Optimistic locking | `W/"123"` || If-None-Exist | Conditional create | `identifier=123` || Prefer | Return preference | `return=representation` |### Response headers| Header | Purpose | Example || ------------- | ------------------ | ------------------------------- || ETag | Version identifier | `W/"123"` || Location | New resource URL | `[base]/Patient/123/_history/1` || Last-Modified | Modification time | RFC 7231 date |## Versioning and optimistic lockingFHIR uses weak ETags for version tracking:1. Server returns `ETag: W/"[versionId]"` with responses2. Client sends `If-Match: W/"[versionId]"` with updates3. Server returns `412 Precondition Failed` if version mismatchImplement version-aware updates when `CapabilityStatement.rest.resource.versioning` is `versioned-update`.## Error handlingReturn `OperationOutcome` resources for all errors:```json{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "invalid", "diagnostics": "Patient.birthDate: Invalid date format" } ]}```### Status codes| Code | Meaning || ---- | -------------------------------------- || 400 | Invalid syntax or validation failure || 404 | Resource not found || 409 | Version conflict || 410 | Resource deleted || 412 | Precondition failed (version mismatch) || 422 | Business rule violation |## Prefer headerControl response content with `Prefer`:| Value | Response body || ------------------------- | -------------------- || `return=minimal` | Empty (headers only) || `return=representation` | Full resource || `return=OperationOutcome` | Validation outcome |For async operations, use `Prefer: respond-async` to get `202 Accepted` with status polling URL.## Implementation checklistServer implementations should:1. Implement CapabilityStatement at `/metadata`2. Support content negotiation (JSON at minimum)3. Return proper ETags for versioned resources4. Include `Location` header on create/update5. Return `OperationOutcome` for all errors6. Support `_format` parameter fallback7. Honour `Prefer` header for response content## References- [operations.md](references/operations.md): Detailed operation specifications- [search.md](references/search.md): Search parameter and result handling- [batch-transaction.md](references/batch-transaction.md): Batch and transaction processing

Frequently asked questions