> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heyrafiki.space/llms.txt
> Use this file to discover all available pages before exploring further.

# API changelog

> Changes to the Heyrafiki API, newest first.

Changes to the API, its resources and its webhooks. Product and website changes are on the [Heyrafiki changelog](https://heyrafiki.space/changelog).

Breaking changes ship behind a new version. Additive changes ship without one, so build clients that ignore unknown fields. See [Versioning](/versioning) for what counts as which.

<Update label="24 July 2026" description="Webhooks, idempotency" tags={["Added"]}>
  **Added** webhook events for the Session lifecycle, `note.approved`, `claim.*`, `payout.settled` and `practitioner.verified`, signed with HMAC-SHA256 over the raw body.

  **Added** `Idempotency-Key` on write requests. Replaying a key returns the original response instead of creating a second Session, Claim or Payment.

  **Added** rate-limit headers (`X-RateLimit-Limit`, `-Remaining`, `-Reset`) on every response, and `Retry-After` on `429`.
</Update>

<Update label="12 June 2026" description="Resource shapes, Session lifecycle" tags={["Added", "Changed"]}>
  **Added** the six core resources, each with a stable ID prefix: `per_`, `prc_`, `ses_`, `not_`, `clm_`, `led_`.

  **Added** the Session lifecycle (`booked` → `delivered` → `note_approved` → `settled`) and the money state attached to each transition.

  **Added** cursor pagination on list endpoints via `limit` and `starting_after`, returning `has_more`.

  **Changed** monetary fields to integers in the currency's smallest unit. `350000` is KES 3,500.00. Decimal amounts are rejected.
</Update>

<Update label="30 April 2026" description="Error envelope" tags={["Added"]}>
  **Added** a single error envelope for every failure, with a stable `error.code`, a human `error.message` and an `error.docs` link. Branch on the code; the message may change.

  **Added** `WWW-Authenticate` on `401`, distinguishing a missing key (`error="invalid_request"`) from a rejected one (`error="invalid_token"`).
</Update>

<Update label="18 March 2026" description="Environment-scoped keys" tags={["Added", "Changed"]}>
  **Added** environment scoping by key prefix: `sk_test_` for Sandbox, `sk_live_` for Production. A key is valid in one environment only, and using the wrong one returns `api_key_invalid` rather than an empty result.

  **Changed** authentication to prefer `Authorization: Bearer`. `x-api-key` remains supported for clients that cannot set an `Authorization` header.
</Update>

<Update label="6 February 2026" description="v1 base URL" tags={["Added"]}>
  **Added** `https://api.heyrafiki.space/v1`, served over HTTPS only. Requests over plain HTTP are rejected rather than redirected, so a key sent that way is never forwarded.
</Update>