---
title: 'Slot (FHIR R4)'
description: 'FHIR R4 Slot resource.'
nav: 'API / R4 / Slot'
order: 180
version: v1
fhir: r4
source: generated
updated: '2026-09-23'
---

# Slot (FHIR R4)

<FhirResourceHeader fhir="r4" slug="slot" />

FHIR R4 Slot 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: [Slot — HL7 FHIR R4](https://hl7.org/fhir/R4/slot.html)

## Supported Interactions

- **search-type** — Search resources with query parameters (`GET /fhir/R4/{Resource}?...`)

<Callout variant="note">
Authorized by the SMART scope `system/Appointment.rs`. This resource inherits an existing scope — no per-resource `system/Slot.*` scope is minted; requesting one is rejected.
</Callout>

## Scopes

Scopes are shared across FHIR releases — the same `system/Slot.*` scope grants Slot access on both `/fhir/R4` and `/fhir/R5`.

- <Scope name="system/Appointment.rs" /> — see [scope reference](/v1/scopes#system-appointment-rs)

## Search Parameters

| Parameter | Type | Notes |
|-----------|------|-------|
| `schedule` | reference | Resource reference — supply the UUID of the referenced resource. |
| `actor` | reference | Resource reference — supply the UUID of the referenced resource. |
| `start` | date | Supports FHIR date prefixes: `eq`, `ne`, `gt`, `ge`, `lt`, `le`. Format: `[prefix]YYYY-MM-DD`. |
| `end` | date | Supports FHIR date prefixes: `eq`, `ne`, `gt`, `ge`, `lt`, `le`. Format: `[prefix]YYYY-MM-DD`. |
| `_count` | number | Integer. For `_count`: default 20, max 100. |
| `_offset` | number | Integer. For `_count`: default 20, max 100. |

## Endpoints

### Search Slot

Search Slot resources (available appointment slots). Results are returned as a
FHIR searchset Bundle. This is a read-only discovery resource, gated by
`system/Appointment.rs` because it supports appointment booking.
Either `schedule` OR `actor` is required. The `start`/`end` window is expressed
as date / RFC 3339 timestamps and is capped at a 31-day span.

<Endpoint method="GET" path="/fhir/R4/Slot" />

**Required scope:** <Scope name="system/Appointment.rs" />

#### Query Parameters

<ParamTable :rows='[{&quot;name&quot;:&quot;schedule&quot;,&quot;type&quot;:&quot;string&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;Filter by Schedule reference (UUID or `Schedule/&lt;uuid&gt;`). Either `schedule`\nor `actor` is required.\n&quot;},{&quot;name&quot;:&quot;actor&quot;,&quot;type&quot;:&quot;string&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;Filter by the actor (PractitionerRole/resource id; UUID or typed reference).\nEither `schedule` or `actor` is required.\n&quot;},{&quot;name&quot;:&quot;start&quot;,&quot;type&quot;:&quot;string&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;Start of the search window (date or RFC 3339 timestamp).&quot;},{&quot;name&quot;:&quot;end&quot;,&quot;type&quot;:&quot;string&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;End of the search window (date or RFC 3339 timestamp). The window between\n`start` and `end` is capped at 31 days.\n&quot;},{&quot;name&quot;:&quot;_count&quot;,&quot;type&quot;:&quot;integer&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;Number of results per page (default: 20, max: 100).&quot;},{&quot;name&quot;:&quot;_offset&quot;,&quot;type&quot;:&quot;integer&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;Number of results to skip (offset-based pagination).&quot;}]' />

#### Response — 200

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "Slot/220e8400-e29b-41d4-a716-446655440110",
      "resource": {
        "resourceType": "Slot",
        "id": "220e8400-e29b-41d4-a716-446655440110",
        "schedule": {
          "reference": "Schedule/110e8400-e29b-41d4-a716-446655440100"
        },
        "status": "free",
        "start": "2026-06-15T10:00:00Z",
        "end": "2026-06-15T10:30:00Z"
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}
```

#### 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/Slot \
  -H "Authorization: Bearer ${TOKEN}"
```

```typescript {label="TypeScript"}
const token = process.env.HULI_ACCESS_TOKEN ?? "";

const response = await fetch(
  `https://api.huli.ai/fhir/R4/Slot`,
  {
    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/Slot",
    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 searchSlotExample {
    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/Slot"))
        .header("Authorization", "Bearer " + token)
        .header("Accept", "application/fhir+json")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

        HttpResponse<String> 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 searchSlotExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("GET", "https://api.huli.ai/fhir/R4/Slot", 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-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 |

---