---
title: Discovery
description: 'Public endpoints for SMART configuration and FHIR capability discovery.'
nav: 'API / Discovery'
order: 10
version: v1
source: generated
updated: '2026-09-23'
---

# Discovery

Public endpoints for SMART configuration and FHIR capability discovery.

> This reference is generated from the canonical Huli Public API OpenAPI specification — do not edit it directly.

## Endpoints

### SMART Configuration (root alias)

Defensive root alias of the canonical `/fhir/.well-known/smart-configuration`.
SMART Backend Services clients should derive discovery from the issuer
(`https://api.huli.ai/fhir`), i.e. `/fhir/.well-known/smart-configuration`.
This root path serves the **identical** document so a client that probes the
host root instead of the issuer path still resolves (rather than receiving an
error). The returned `issuer` is still `…/fhir`.

<Endpoint method="GET" path="/.well-known/smart-configuration" />

#### 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}" \
  | jq -r .access_token)

curl -X GET https://api.huli.ai/.well-known/smart-configuration \
  -H "Authorization: Bearer ${TOKEN}"
```

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

const response = await fetch(
  `https://api.huli.ai/.well-known/smart-configuration`,
  {
    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/.well-known/smart-configuration",
    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 getSmartConfigurationRootAliasExample {
    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/.well-known/smart-configuration"))
        .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 getSmartConfigurationRootAliasExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("GET", "https://api.huli.ai/.well-known/smart-configuration", 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)
}
```

:::

---

### SMART Configuration

Returns the [SMART on FHIR discovery document](https://hl7.org/fhir/smart-app-launch/conformance.html)
describing the server's authorization capabilities, supported scopes, and token endpoint URL.
The discovery document is issuer-rooted under `/fhir`: the full URL is
`https://api.huli.ai/fhir/.well-known/smart-configuration` and it advertises a
`jwks_uri` of `https://api.huli.ai/fhir/.well-known/jwks.json`.

<Endpoint method="GET" path="/fhir/.well-known/smart-configuration" />

#### Response — 200

```json
{
  "issuer": "https://api.huli.ai/fhir",
  "jwks_uri": "https://api.huli.ai/fhir/.well-known/jwks.json",
  "authorization_endpoint": "",
  "token_endpoint": "https://api.huli.ai/auth/token",
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt",
    "none"
  ],
  "token_endpoint_auth_signing_alg_values_supported": [
    "RS384"
  ],
  "grant_types_supported": [
    "client_credentials",
    "authorization_code",
    "refresh_token"
  ],
  "scopes_supported": [
    "system/Patient.rs",
    "system/Patient.cru",
    "system/Appointment.rs",
    "system/Appointment.cru",
    "system/Encounter.rs",
    "system/Encounter.cru",
    "system/Observation.rs",
    "system/Observation.cru",
    "system/MedicationRequest.rs",
    "system/MedicationRequest.cru",
    "system/ServiceRequest.rs",
    "system/ServiceRequest.cru",
    "system/Composition.rs",
    "system/Composition.cru",
    "system/DocumentReference.rs",
    "system/DocumentReference.cru",
    "system/Practitioner.rs",
    "system/Organization.rs",
    "system/Subscription.rs",
    "system/Subscription.crud",
    "user/Patient.rs",
    "user/Patient.cru",
    "user/Appointment.rs",
    "user/Appointment.cru",
    "user/Encounter.rs",
    "user/Encounter.cru",
    "user/Observation.rs",
    "user/Observation.cru",
    "user/MedicationRequest.rs",
    "user/MedicationRequest.cru",
    "user/ServiceRequest.rs",
    "user/ServiceRequest.cru",
    "user/Composition.rs",
    "user/Composition.cru",
    "user/DocumentReference.rs",
    "user/DocumentReference.cru",
    "user/Practitioner.rs",
    "user/Organization.rs"
  ],
  "capabilities": [
    "client-confidential-asymmetric"
  ]
}
```

#### 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}" \
  | jq -r .access_token)

curl -X GET https://api.huli.ai/fhir/.well-known/smart-configuration \
  -H "Authorization: Bearer ${TOKEN}"
```

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

const response = await fetch(
  `https://api.huli.ai/fhir/.well-known/smart-configuration`,
  {
    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/.well-known/smart-configuration",
    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 getSmartConfigurationExample {
    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/.well-known/smart-configuration"))
        .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 getSmartConfigurationExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("GET", "https://api.huli.ai/fhir/.well-known/smart-configuration", 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)
}
```

:::

---

### JSON Web Key Set

Returns the server's [JSON Web Key Set](https://datatracker.ietf.org/doc/html/rfc7517)
— the active signing key plus any overlap-window key during rotation. Partners fetch
this to verify access-token signatures out-of-band without round-tripping to the
server. Advertised as `jwks_uri` in the SMART configuration document.

<Endpoint method="GET" path="/fhir/.well-known/jwks.json" />

#### Response — 200

```json
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS384",
      "kid": "2026-05-01",
      "n": "0vx7agoeb...",
      "e": "AQAB"
    }
  ]
}
```

#### 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}" \
  | jq -r .access_token)

curl -X GET https://api.huli.ai/fhir/.well-known/jwks.json \
  -H "Authorization: Bearer ${TOKEN}"
```

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

const response = await fetch(
  `https://api.huli.ai/fhir/.well-known/jwks.json`,
  {
    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/.well-known/jwks.json",
    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 getJwksExample {
    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/.well-known/jwks.json"))
        .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 getJwksExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("GET", "https://api.huli.ai/fhir/.well-known/jwks.json", 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)
}
```

:::

---

### Capability Statement

Returns the FHIR R4 [CapabilityStatement](https://hl7.org/fhir/R4/capabilitystatement.html)
describing this server's supported resources, operations, and search parameters.

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

#### Response — 200

```json
{
  "resourceType": "CapabilityStatement",
  "status": "active",
  "date": "2026-05-01",
  "kind": "instance",
  "fhirVersion": "4.0.1",
  "format": [
    "application/fhir+json"
  ],
  "rest": [
    {
      "mode": "server",
      "resource": [
        {
          "type": "Patient",
          "interaction": [
            {
              "code": "read"
            },
            {
              "code": "search-type"
            },
            {
              "code": "create"
            },
            {
              "code": "update"
            }
          ]
        },
        {
          "type": "Appointment",
          "interaction": [
            {
              "code": "read"
            },
            {
              "code": "search-type"
            },
            {
              "code": "create"
            },
            {
              "code": "update"
            }
          ]
        },
        {
          "type": "Encounter",
          "interaction": [
            {
              "code": "read"
            },
            {
              "code": "search-type"
            },
            {
              "code": "create"
            },
            {
              "code": "update"
            }
          ]
        },
        {
          "type": "Observation",
          "interaction": [
            {
              "code": "read"
            },
            {
              "code": "search-type"
            },
            {
              "code": "create"
            },
            {
              "code": "update"
            }
          ]
        },
        {
          "type": "Practitioner",
          "interaction": [
            {
              "code": "read"
            }
          ]
        },
        {
          "type": "Organization",
          "interaction": [
            {
              "code": "read"
            }
          ]
        }
      ]
    }
  ]
}
```

#### 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}" \
  | jq -r .access_token)

curl -X GET https://api.huli.ai/fhir/R4/metadata \
  -H "Authorization: Bearer ${TOKEN}"
```

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

const response = await fetch(
  `https://api.huli.ai/fhir/R4/metadata`,
  {
    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/metadata",
    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 getMetadataExample {
    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/metadata"))
        .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 getMetadataExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("GET", "https://api.huli.ai/fhir/R4/metadata", 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)
}
```

:::

---