Document the JSON API stability promise

docs/json_api.rst now opens with an API stability section declaring
what the 1.x promise covers: documented endpoints, parameters and
response keys are stable with additive-only changes; pagination tokens
are opaque strings; the error format and token restriction semantics
are stable. It lists the exempt tiers: endpoints carrying the
"unstable" marker key, debug and support endpoints (/-/threads,
/-/actions, /-/jump, the permission debug endpoints, table
autocomplete), and keys explicitly labeled unstable such as the
execute-write analysis block. Cross-referenced from the introspection
and permission-debug documentation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GrHZSypDfMnym1tM5XJAFZ

docs/authentication.rst

@@ -1151,6 +1151,8 @@ It also provides an interface for running hypothetical permission checks against
 
 This is designed to help administrators and plugin authors understand exactly how permission checks are being carried out, in order to effectively configure Datasette's permission system.
 
+These debug endpoints are exempt from the :ref:`JSON API stability promise <json_api_stability>` - their JSON shapes may change in future releases.
+
 .. _AllowedResourcesView:
 
 Allowed resources view

docs/introspection.rst

@@ -9,6 +9,8 @@ Each of these pages can be viewed in your browser. Add ``.json`` to the URL to g
 
 JSON responses that return an object include an ``"ok": true`` key, consistent with the rest of the :ref:`JSON API <json_api>`.
 
+The introspection endpoints documented on this page are covered by the :ref:`JSON API stability promise <json_api_stability>`, with the exception of the debug endpoints ``/-/threads``, ``/-/actions`` and ``/-/jump``, whose shapes may change in future releases.
+
 .. _JsonDataView_metadata:
 
 /-/metadata

docs/json_api.rst

@@ -9,6 +9,53 @@ through the Datasette user interface can also be accessed as JSON via the API.
 To access the API for a page, either click on the ``.json`` link on that page or
 edit the URL and add a ``.json`` extension to it.
 
+.. _json_api_stability:
+
+API stability
+-------------
+
+Datasette 1.0 makes a stability promise for its JSON API: the endpoints,
+parameters and response keys documented here and on the pages this
+documentation links to will not change in backwards-incompatible ways for
+the duration of the 1.x release series.
+
+Stability means:
+
+- Documented endpoints will keep their URLs, methods, parameters and
+  permission requirements.
+- Documented response keys will keep their names and types. New keys may be
+  **added** in any release - clients should ignore keys they do not
+  recognize.
+- The documented ``?_extra=`` names, ``?_shape=`` values and
+  :ref:`column filter operators <table_arguments>` are stable.
+- Pagination tokens - the ``"next"`` key and ``?_next=`` parameter - are
+  **opaque strings**. Pass them back exactly as you received them; their
+  internal structure is not part of the API and can change at any time.
+- The :ref:`standard error format <json_api_errors>` and the
+  :ref:`API token format and restriction semantics <CreateTokenView>` are
+  stable, including the action abbreviations stored inside signed tokens.
+
+Some JSON endpoints are **exempt** from this promise:
+
+- Endpoints that are not documented include this marker key in their
+  responses and can change at any time::
+
+      "unstable": "This API is not part of Datasette's stable interface and may change at any time"
+
+  This currently covers the instance homepage (``/.json``), the stored
+  query ``analyze``/``store``/``definition`` endpoints, ``/-/query/parameters``,
+  ``/-/execute-write/analyze`` and the JSON returned by the ``/-/permissions``
+  debug playground.
+- Debug and support endpoints are documented so you can use them, but their
+  JSON shapes are not frozen: :ref:`/-/threads <JsonDataView_threads>`,
+  :ref:`/-/actions <JsonDataView_actions>`, :ref:`/-/jump <JumpView>`,
+  the :ref:`permission debug endpoints <PermissionsDebugView>`
+  (``/-/allowed``, ``/-/rules``, ``/-/check``) and the
+  :ref:`table autocomplete endpoint <TableAutocompleteView>`.
+- Response keys explicitly labeled as unstable in this documentation, such
+  as the ``"analysis"`` block returned by :ref:`execute-write <ExecuteWriteView>`
+  and the ``debug`` and ``request`` extras.
+
 .. _json_api_default:
 
 Default representation
@@ -1612,7 +1659,7 @@ Unsupported SQL operations are rejected by default. ``VACUUM`` is not allowed in
 A successful response includes a message, the SQLite ``rowcount``, a ``"rows"``
 list, a ``"truncated"`` flag and a summary of the operations that were executed:
 
-The shape of the ``"analysis"`` block is not yet considered a stable API and may change in future Datasette releases.
+The shape of the ``"analysis"`` block is not part of the :ref:`stable API <json_api_stability>` and may change in future Datasette releases.
 
 .. code-block:: json
 

stable-api-recommendations.md

@@ -378,13 +378,17 @@ Concerns:
 
 ---
 
-## 9. Define stability tiers explicitly (P1 — documentation, not code) — partially implemented
+## 9. Define stability tiers explicitly (P1 — documentation, not code) — ✅ IMPLEMENTED
 
-> **Status:** undocumented JSON endpoints now self-describe with an
-> `"unstable": "This API is not part of Datasette's stable interface and
-> may change at any time"` key (homepage, queries analyze/store/definition,
-> query parameters, execute-write analyze, permissions playground POST).
-> The written tier documentation remains to be done.
+> **Status:** implemented. Undocumented JSON endpoints self-describe with
+> an `"unstable"` marker key, and `docs/json_api.rst` now opens with an
+> "API stability" section (`json_api_stability`) declaring the 1.x
+> promise: documented endpoints/keys are stable with additive-only
+> changes, pagination tokens are opaque, the error format and token
+> restriction semantics are stable, and the exempt tiers (marker-key
+> endpoints, debug/support endpoints, explicitly-unstable keys) are
+> listed. Cross-referenced from the introspection and permission-debug
+> docs.
 
 Not everything under `/-/` can or should carry a 1.0 guarantee. Recommend
 shipping 1.0 with an explicit three-tier contract, per endpoint:
@@ -431,8 +435,8 @@ Two details make tiering urgent rather than optional:
    `permissions-debug` (§6).~~ ✅ Done.
 6. ~~401 (not silent-anonymous) for invalid/expired bearer tokens (§1c).~~
    ✅ Done.
-7. Publish explicit stability tiers, including extras and pagination-token
-   opacity (§9).
+7. ~~Publish explicit stability tiers, including extras and pagination-token
+   opacity (§9).~~ ✅ Done.
 8. Resolve the looks-like-a-bug list (§8), especially ~~trusted-query delete
    and row-delete 500~~ (both done).