fix(6194): correct API param + document compactPad in http_api docs

The 1.3.1 entry in APIHandler registered `['padID', 'authorId']`, but
`API.compactPad` takes `(padID, keepRevisions)` and the CLI sends a
`keepRevisions` query param. APIHandler.handle dispatches by URL field
name, so the previous wiring silently dropped `keepRevisions` and never
ran the keep-last branch over HTTP.

- Register `['padID', 'keepRevisions']` so the handler forwards the
  CLI/HTTP arg into the API function.
- Add HTTP-level dispatch tests that hit `/api/1.3.1/compactPad` with
  and without `keepRevisions`. The direct `api.compactPad()` tests
  bypass the handler and would have missed this regression.
- Document compactPad in `doc/api/http_api.md` and `http_api.adoc`,
  and bump the documented latest version from 1.3.0 to 1.3.1 to match
  `latestApiVersion`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: JohnMcLear

doc/api/http_api.adoc

@@ -65,7 +65,7 @@ Portal submits content into new blog post
 === Usage
 
 ==== API version
-The latest version is `1.3.0`
+The latest version is `1.3.1`
 
 The current version can be queried via /api.
 
@@ -588,6 +588,22 @@ _Example returns:_
   * `{code: 0, message:"ok", data: null}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
+==== compactPad(padID, [keepRevisions])
+ * API >= 1.3.1
+
+collapses the pad's revision history to reclaim database space (issue #6194). Wraps the same `Cleanup` helper that powers the admin-settings UI, so admins can trigger compaction over the public API or via `bin/compactPad` without going through the admin UI.
+
+When `keepRevisions` is omitted (or null), all history is collapsed into a single base revision that reproduces the current pad text — equivalent to a freshly-imported pad. When set to a positive integer N, the pad keeps only its last N revisions.
+
+Pad text and chat are preserved in both modes. Saved-revision bookmarks are cleared. *This operation is destructive — export the pad first via `getEtherpad` if you need a backup.*
+
+_Example returns:_
+
+  * `{code: 0, message:"ok", data: {ok: true, mode: "all"}}`
+  * `{code: 0, message:"ok", data: {ok: true, mode: "keepLast", keepRevisions: 50}}`
+  * `{code: 1, message:"padID does not exist", data: null}`
+  * `{code: 1, message:"keepRevisions must be a non-negative integer", data: null}`
+
 ==== getReadOnlyID(padID)
  * API >= 1
 

doc/api/http_api.md

@@ -98,7 +98,7 @@ Portal submits content into new blog post
 ## Usage
 
 ### API version
-The latest version is `1.3.0`
+The latest version is `1.3.1`
 
 The current version can be queried via /api.
 
@@ -619,6 +619,21 @@ moves a pad. If force is true and the destination pad exists, it will be overwri
 * `{code: 0, message:"ok", data: null}`
 * `{code: 1, message:"padID does not exist", data: null}`
 
+#### compactPad(padID, [keepRevisions])
+* API >= 1.3.1
+
+collapses the pad's revision history to reclaim database space (issue #6194). Wraps the same `Cleanup` helper that powers the admin-settings UI, so admins can trigger compaction over the public API or via `bin/compactPad` without going through the admin UI.
+
+When `keepRevisions` is omitted (or null), all history is collapsed into a single base revision that reproduces the current pad text — equivalent to a freshly-imported pad. When set to a positive integer N, the pad keeps only its last N revisions.
+
+Pad text and chat are preserved in both modes. Saved-revision bookmarks are cleared. **This operation is destructive — export the pad first via `getEtherpad` if you need a backup.**
+
+*Example returns:*
+* `{code: 0, message:"ok", data: {ok: true, mode: "all"}}`
+* `{code: 0, message:"ok", data: {ok: true, mode: "keepLast", keepRevisions: 50}}`
+* `{code: 1, message:"padID does not exist", data: null}`
+* `{code: 1, message:"keepRevisions must be a non-negative integer", data: null}`
+
 #### getReadOnlyID(padID)
 * API >= 1
 

src/node/handler/APIHandler.ts

@@ -144,7 +144,7 @@ version['1.3.0'] = {
 
 version['1.3.1'] = {
   ...version['1.3.0'],
-  compactPad: ['padID', 'authorId'],
+  compactPad: ['padID', 'keepRevisions'],
 };
 
 

src/tests/backend/specs/compactPad.ts

@@ -1,5 +1,7 @@
 'use strict';
 
+import {generateJWTToken} from "../common";
+
 const assert = require('assert').strict;
 const common = require('../common');
 const padManager = require('../../../node/db/PadManager');
@@ -10,6 +12,9 @@ const api = require('../../../node/db/API');
 // verify the public-API wiring and argument handling.
 describe(__filename, function () {
   let padId: string;
+  let agent: any;
+
+  before(async function () { agent = await common.init(); });
 
   beforeEach(async function () {
     padId = common.randomString();
@@ -80,4 +85,38 @@ describe(__filename, function () {
           /keepRevisions must be a non-negative integer/);
     });
   });
+
+  // Verifies the APIHandler dispatch wiring — i.e. that `keepRevisions`
+  // travels from the URL query string to the API function under the
+  // right argument name. This catches regressions where the handler's
+  // version map gets renamed without updating the function signature.
+  describe('HTTP API dispatch (1.3.1)', function () {
+    it('passes keepRevisions from query string into compactPad', async function () {
+      const pad = await padManager.getPad(padId);
+      for (let i = 0; i < 5; i++) await pad.appendText(`http-line-${i}\n`);
+
+      const res = await agent.get(
+          `/api/1.3.1/compactPad?padID=${padId}&keepRevisions=2`)
+          .set('authorization', await generateJWTToken())
+          .expect(200)
+          .expect('Content-Type', /json/);
+
+      assert.strictEqual(res.body.code, 0, JSON.stringify(res.body));
+      assert.strictEqual(res.body.data.mode, 'keepLast');
+      assert.strictEqual(res.body.data.keepRevisions, 2);
+    });
+
+    it('collapses all history when keepRevisions is absent from URL', async function () {
+      const pad = await padManager.getPad(padId);
+      for (let i = 0; i < 3; i++) await pad.appendText(`http-all-${i}\n`);
+
+      const res = await agent.get(`/api/1.3.1/compactPad?padID=${padId}`)
+          .set('authorization', await generateJWTToken())
+          .expect(200)
+          .expect('Content-Type', /json/);
+
+      assert.strictEqual(res.body.code, 0, JSON.stringify(res.body));
+      assert.deepStrictEqual(res.body.data, {ok: true, mode: 'all'});
+    });
+  });
 });