This page is the contract for API consumers of Externa 1.x: Public CMS REST (/api/v1) and GraphQL (/api/graphql). Package semver follows the same spirit (Release process / issue #22).

Public CMS API · GraphQL · Public CMS API types · CHANGELOG.md (once present)

Versioning surface

Surface	Stability in 1.x
*`/api/v1/`**	Stable base path for the entire 1.x line. No `/api/v2` required for compatible evolution.
`/api/graphql`	Same auth, collection guards, and field ACL as REST. Schema evolves under the rules below.
Auth	Anonymous via `public` role matrix, or `Authorization: Bearer ek_…` API keys bound to a non–super-admin role.

Admin session routes, Inertia props, and internal jobs are not covered by this public-API policy.

What may change in a minor (1.y → 1.y+1)

Additive changes are allowed without a major bump:

New REST endpoints under /api/v1
New optional request/query fields (defaults preserve prior behaviour)
New response fields (clients must ignore unknown keys)
New GraphQL types, fields, arguments that are optional or additive
New enum values where clients treat unknowns safely
Performance / docs / non-contract bug fixes

What requires deprecation or a major (2.0)

Treat as breaking (major release, or announced deprecation then removal):

Removing or renaming REST paths, required fields, or response fields consumers rely on
Changing auth semantics (how keys / public resolve) in an incompatible way
Removing GraphQL fields/types/arguments without a deprecation window
Tightening validation so previously valid requests fail (unless fixing a security hole — then document as security fix)

Security fixes that change behaviour may ship in a patch/minor with a clear CHANGELOG Security note.

Deprecation window

Mark the behaviour deprecated in CHANGELOG (Deprecated section) and in this docs site.
Prefer keeping the old path/field working through at least one minor after announcement (longer when practical).
Optional later: response headers or GraphQL @deprecated directives — not required for 1.x start.
Removal happens in a major (or at end of the announced window called out in release notes).

Auth & roles (unchanged intent)

API keys never grant super-admin.
Collection/file access still comes from the key’s role (or public) matrices — not Spatie admin permissions.
See Public CMS API for setup.

Client guidance

Pin to a documented Externa version for production.
Tolerate additive JSON/GraphQL fields.
Watch CHANGELOG + GitHub Releases when upgrading minors.
Prefer Bruno collection / published types for contract smoke tests.

Alignment with package semver

Package bump	Typical API impact
Patch	Fixes; no intentional public contract break
Minor	Additive API/GraphQL; deprecations may be announced
Major	Breaking removals/renames after (or with) deprecation notice

App version lives in composer.json (mirrored in package.json). Release checklist: issue #22 / Releasing docs.