> For the complete documentation index, see [llms.txt](https://islamu.gitbook.io/islamu-event/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://islamu.gitbook.io/islamu-event/api-reference/readme/api-changelog.md).

# API Changelog

Curated pre-v1 API contract changes and migration expectations.

The draft HTTP API version is `0.1`. In pre-release development before v1, breaking changes are made freely whenever they simplify the contract or restore architectural invariants.

## Current mainline contract

* HAL representations are default where available; clients use `_links` for resource actions.
* API version negotiation uses media type, query, or `X-Api-Version`; URL-segment versions are not supported.
* Failures use RFC 7807 ProblemDetails rather than failed success-shaped command bodies.
* Pagination is 1-based with default size `20` and maximum `100`.
* Bearer and `X-API-Key` authentication are mutually exclusive.
* Tenant context comes from host/header/scoped key authority, not request-body identity.
* Retryable documented writes use tenant-scoped idempotency keys.
* Interactive OpenAPI surfaces are Development/Testing by default.

## Recent externally visible themes

### Operator form choices (2026-09-21)

Authenticated clients can read `GET /api/operator-identity-metadata` through the generated `GetOperatorIdentityFormOptionsAsync` operation. It supplies canonical operator-kind codes, runtime country display choices, shared field limits and label/help identifiers without returning saved identity values. An unavailable country catalogue is explicit; do not replace it with invented choices. Registration identifiers remain optional, and registration-authority options are explicitly unsupported rather than a new list of authorities.

The resource is private/no-store and independent of directory publication. Its `self` and `refresh` links do not authorize identity edits. Normal authenticated instance identity documents advertise the `form-options` lookup; use the identity document's own mutation links and revision for saves. Setup-secret access is not extended. No database migration or deployment setting is required.

### Operations and configuration

Operational control-plane reads, safe health output, configuration-manifest workflows, privacy-erasure topology, and explicit managed-mode interfaces have been added or tightened. Optional managed interfaces remain disabled by default.

### Events and commerce

Public event slugs and Open Graph imagery, modular aspects, custom properties, registration/admission separation, buyer commerce reads, organizer refund actions, material-change response, and refund campaign operations are represented in the current contract. Provider-confirmed evidence controls payment/refund status.

### Communications and integrations

Web Push, SMTP/outbox behavior, sanitized Listmonk settings/test/credential-rotation operations, forms, webhook modes, MCP proposals, and selective federation have explicit contracts and limitations.

### Security and tenancy

Cerbos intent is explicit and fail closed. HAL action generation follows current authorization. Tenant resolution, secret-provider states, private/no-store commerce responses, and erasure-receipt handling have been hardened without compatibility aliases for removed pre-v1 shapes.

## What counts as a breaking change

Record removals, renames, authentication/authorization changes, request/response/problem changes, pagination/cursor changes, and generated-client changes. Each entry should name affected routes/schema/methods, old and new behavior, consumers, migration guidance or compatibility window, target release, and verification evidence.

## Canonical sources

The repository's `docs/API_CHANGELOG.md` is the detailed date-indexed contract log. The governed OpenAPI artifact is `schemas/openapi-islamu-event.json`. Regenerate all governed client artifacts after server contract changes; do not edit generated files manually.

At API v1.0, breaking schema diffs become blocking. Until then, treat every upgrade as a deliberate contract migration.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://islamu.gitbook.io/islamu-event/api-reference/readme/api-changelog.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.