for Developers

Reference

Machine-readable contracts for the Huli Public API v1.

OpenAPI specification

The OpenAPI 3.0.3 specification covers the FHIR R4 endpoints (see the API reference).

Live spec:

curl https://api.huli.ai/openapi.json

The published openapi.json is the source of truth for the API contract — the endpoint reference under API is generated from it.

The spec includes x-huli-scope extensions on each operation documenting the required scope.

FHIR CapabilityStatement

The live CapabilityStatement reflects what the server currently supports. It is generated from the same source as the OpenAPI spec — they do not diverge.

curl https://api.huli.ai/fhir/R4/metadata \
  -H "Accept: application/fhir+json"

This endpoint does not require authentication. It is safe to fetch on startup to validate that the server supports the operations your integration needs.

Generated endpoint pages

The pages under /v1/api/ are auto-generated from the OpenAPI spec and the server FHIR CapabilityStatement at build time. Each resource page merges the endpoint reference (request/response schemas, required scopes, error codes, code samples) with the FHIR narrative (supported interactions, search parameters, custom extensions, and LATAM-specific identifiers). Browse them from the API reference index, and use the R4 / R5 switch there to pick a FHIR release — see Choosing R4 vs R5.

SMART discovery

curl https://api.huli.ai/fhir/.well-known/smart-configuration

Returns the token_endpoint, jwks_uri, scopes_supported, and grant_types_supported needed to configure any SMART-compatible client library.

JWKS

The server's public key for verifying issued access tokens:

curl https://api.huli.ai/fhir/.well-known/jwks.json