---
title: Reference
description: OpenAPI specification, FHIR CapabilityStatement, and generated endpoint pages for the Huli Public API v1.
nav: Reference
order: 80
version: v1
source: handwritten
updated: 2026-06-01
---

# 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](/v1/api)).

**Live spec:**

```bash
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](/v1/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.

```bash
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/`](/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](/v1/api), and use
the R4 / R5 switch there to pick a FHIR release — see [Choosing R4 vs R5](/v1/api/fhir-versions).

## SMART discovery

```bash
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:

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