---
title: Changelog
description: Release history for the Huli Public API — dated, versioned, and flagged for breaking changes.
nav: Changelog
order: 95
version: v1
source: handwritten
updated: 2026-06-01
---

# Changelog

<ChangelogEntry date="2026-06-01" version="v1.0.0">

## Huli Public API v1.0 — General Availability

**Breaking:** no. This is the initial public release.

### What ships

**FHIR R4 resources**

- `Patient` — read, search, create, update. Identifiers: CURP, RFC, NSS, INE. Two-surname
  support via the `segundo-apellido` extension. Gender mapping: FHIR `male/female/other`
  → Huli `M/F/I`.
- `Appointment` — read, search, create, update. Status transitions: `booked`,
  `cancelled`, `fulfilled`.
- `Encounter` — read, search, create, update. Class: ambulatory, emergency, inpatient.
- `Observation` — read, search, create, update. Categories: `vital-signs`, `laboratory`,
  `exam`. LOINC required on write. UCUM validated.
- `Practitioner` — read, search (read-only).
- `Organization` — read, search (read-only).

**Authentication**

- Admin-managed bearer tokens via Practice Settings.
- SMART backend services (`client_credentials` + `private_key_jwt`, RS384).
- Interactive OAuth Authorization Code + PKCE via `app.huli.ai/oauth/authorize`.
- SMART discovery at `/fhir/.well-known/smart-configuration`.

**Rate limiting and audit**

- Per-key and per-organization request ceilings. `429` with `Retry-After` on limit
  exceeded.
- Every authenticated request writes an audit record with 7-year retention (NOM-024
  compliance requirement).

**`huli` CLI v1.0**

- `huli auth login` (interactive OAuth PKCE), `huli auth setup` (bearer), `huli auth
status`, `huli auth token`.
- `huli fhir patient|appointment|encounter|observation|practitioner|organization`
  subcommands.
- `huli api get|post|put` for raw HTTP access.
- `huli config get|set|list`.

**Scope system**

- `system/<Resource>.<perms>` format. Permissions: `r` (read), `s` (search), `c`
  (create), `u` (update).
- Scopes: `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/Practitioner.rs`,
  `system/Organization.rs`.

### Error codes

| Code        | HTTP | Meaning               |
| ----------- | ---- | --------------------- |
| `HPB-00101` | 400  | Validation error      |
| `HPB-00102` | 404  | Resource not found    |
| `HPB-00103` | 409  | Version conflict      |
| `HPB-00104` | 403  | Insufficient scope    |
| `HPB-00105` | 429  | Rate limit exceeded   |
| `HPB-00106` | 401  | Authentication failed |
| `HPB-00107` | 401  | Token expired         |

### Known limitations at GA

- FHIR `$export` (bulk data access) is not available in v1.
- Webhook subscriptions are not available in v1.
- The `_include` and `_revinclude` FHIR search parameters are not supported.

</ChangelogEntry>