---
title: Concepts
description: Mental models for working with the Huli Public API — organizations, pagination, rate limiting, and audit.
nav: Concepts
order: 0
version: v1
source: handwritten
updated: 2026-06-01
---

# Concepts

Three concepts underpin every request to the Huli Public API: the organization boundary
(which organization owns the data), cursor-based pagination (how sets are navigated),
and the rate-limit and audit system (what the API enforces and records on every
authenticated call).

## In this section

- **[Organizations](/v1/concepts/organizations)** — `organization_id` is the security
  boundary. Every resource belongs to exactly one organization. Cross-organization reads
  return `403`.
- **[Pagination](/v1/concepts/pagination)** — All list endpoints use cursor-based
  pagination via `_count` and `_cursor`. `total` is advisory; do not use it as a loop
  terminator.
- **[Rate Limiting](/v1/concepts/rate-limiting)** — Per-key and per-organization
  request ceilings. Every authenticated request writes an audit record with a 7-year
  retention obligation.
- **[Webhooks](/v1/concepts/webhooks)** — Outbound notifications via the FHIR R4
  `Subscription` resource. HMAC-signed, id-level, at-least-once deliveries with retries,
  auto-pause, and `$replay` for outage recovery.

## FHIR conformance

The public surface is FHIR R4. The normative contract is the live CapabilityStatement
at [`/fhir/R4/metadata`](https://api.huli.ai/fhir/R4/metadata). All resources and
operations advertised there are what the API actually supports — no divergence between
docs and the statement.

Extensions and custom identifiers are documented in the individual resource pages under
the [API reference](/v1/api).