for Developers

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.

GET/.well-known/smart-configuration

Code Samples

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}"

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();

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())

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());
    }
}

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 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.

GET/fhir/.well-known/smart-configuration

Response — 200

{
  "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

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}"

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();

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())

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());
    }
}

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 — 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.

GET/fhir/.well-known/jwks.json

Response — 200

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

Code Samples

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}"

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();

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())

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());
    }
}

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 describing this server's supported resources, operations, and search parameters.

GET/fhir/R4/metadata

Response — 200

{
  "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

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}"

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();

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())

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());
    }
}

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)
}