---
title: 'ValueSet (FHIR R4)'
description: 'FHIR R4 ValueSet resource.'
nav: 'API / R4 / ValueSet'
order: 200
version: v1
fhir: r4
source: generated
updated: '2026-09-23'
---
# ValueSet (FHIR R4)
FHIR R4 ValueSet resource.
> This reference is generated from the canonical Huli Public API OpenAPI specification and the server's FHIR R4 CapabilityStatement — do not edit it directly.
## FHIR R4 Specification
Official spec: [ValueSet — HL7 FHIR R4](https://hl7.org/fhir/R4/valueset.html)
## Supported Interactions
- **$expand** — operation
Terminology operation. Scope is enforced per ValueSet `url` by the handler (cancellation-reason → `system/Appointment.rs`, observation-loinc → `system/Observation.rs`, mx-* → `system/Patient.rs`).
## Scopes
Scopes are shared across FHIR releases — the same `system/ValueSet.*` scope grants ValueSet access on both `/fhir/R4` and `/fhir/R5`.
## Endpoints
### Expand a ValueSet
Expand one of the Huli terminology ValueSets into its codes (FHIR `$expand`
operation). The `url` parameter selects the catalog. Scope is enforced per-url:
- `.../ValueSet/cancellation-reason` requires `system/Appointment.rs`
- `.../ValueSet/observation-loinc` requires `system/Observation.rs`
- `.../ValueSet/mx-country`, `.../ValueSet/mx-municipality`,
`.../ValueSet/mx-locality` require `system/Patient.rs`
`mx-municipality` requires a `state` parameter; `mx-locality` requires both
`state` and `municipality`. The optional `filter` is a case/accent-insensitive
name/code prefix where the backing catalog supports it.
**Required scope:**
#### Query Parameters
#### Response — 200
```json
{
"resourceType": "ValueSet",
"url": "https://fhir.huli.ai/r4/ValueSet/cancellation-reason",
"status": "active",
"expansion": {
"total": 1,
"contains": [
{
"system": "https://fhir.huli.ai/r4/CodeSystem/cancellation-reason",
"code": "patient-no-show",
"display": "El paciente no se presentó"
}
]
}
}
```
#### Code Samples
:::CodeGroup
```bash {label="cURL"}
TOKEN=$(curl -s -X POST https://api.huli.ai/auth/token \
-d "grant_type=client_credentials" \
-d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
-d "client_assertion=${CLIENT_ASSERTION}" \
-d "scope=system/Appointment.rs" \
| jq -r .access_token)
curl -X GET https://api.huli.ai/fhir/R4/ValueSet/$expand \
-H "Authorization: Bearer ${TOKEN}"
```
```typescript {label="TypeScript"}
const token = process.env.HULI_ACCESS_TOKEN ?? "";
const response = await fetch(
`https://api.huli.ai/fhir/R4/ValueSet/$expand`,
{
method: "GET",
headers: {
"Authorization": `Bearer ${token}`,
},
}
);
if (!response.ok) throw new Error(`HTTP ${String(response.status)}`);
const data: unknown = await response.json();
```
```python {label="Python"}
import os
import requests
token = os.environ["HULI_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {token}"}
resp = requests.get(
f"https://api.huli.ai/fhir/R4/ValueSet/$expand",
headers=headers,
)
resp.raise_for_status()
print(resp.json())
```
```java {label="Java"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class expandValueSetExample {
public static void main(String[] args) throws Exception {
String token = System.getenv("HULI_ACCESS_TOKEN");
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.huli.ai/fhir/R4/ValueSet/$expand"))
.header("Authorization", "Bearer " + token)
.header("Accept", "application/fhir+json")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse response =
client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("status: " + response.statusCode());
System.out.println(response.body());
}
}
```
```go {label="Go"}
import (
"fmt"
"net/http"
"os"
)
func expandValueSetExample() {
token := os.Getenv("HULI_ACCESS_TOKEN")
req, _ := http.NewRequest("GET", "https://api.huli.ai/fhir/R4/ValueSet/$expand", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, err := http.DefaultClient.Do(req)
if err != nil {
fmt.Println("error:", err)
return
}
defer resp.Body.Close()
fmt.Println("status:", resp.Status)
}
```
:::
#### Errors
| Code | Status | Description |
|------|--------|-------------|
| [HPB-00101](/v1/errors#hpb-00101) | 400 | Validation error |
| [HPB-00106](/v1/errors#hpb-00106) | 401 | Authentication failed |
| [HPB-00104](/v1/errors#hpb-00104) | 403 | Insufficient scope |
| [HPB-00105](/v1/errors#hpb-00105) | 429 | Rate limit exceeded |
---