Align the REST API OpenAPI spec with released Dashboard 6.1.5

[dennisdornon]

The published api-reference/openapi.yaml drifted from what Dashboard 6.1.5 serves. Each change below was verified against the 6.1.5 source and, where the route surface was in question, against a live Dashboard's route index.

What changed

• Removed GET /jobs/{id}. No released Dashboard registers that route. Queued responses still return a job_id; the spec now points status checks at the mainwp/get-batch-job-status-v1 ability on the WordPress Abilities API and notes that it uses WordPress authentication rather than the MainWP API key.
• Extension action routes accept PUT and PATCH. The SSL Monitor, Domain Monitor, and Lighthouse audit routes register WP_REST_Server::EDITABLE, so POST, PUT, and PATCH all work. The spec documented POST only. The route tables in extensions.mdx now match.
• Pro Reports corrections. Added the missing widgets, pagespeed, and multi-tokens report types (34 total). start_date and end_date are optional; the controller falls back to the last year when either is missing. The multi_tokens template parameter is now documented.
• Response schemas match real responses. success allows 0 on the three envelopes whose handlers report failures inside an HTTP 200 (Success, SuccessMessage, CountResult); the acknowledgement envelopes that hardcode 1 keep the tighter constraint. ToolJobStatus.errors items are {site_id, error} objects, and both timestamps allow the empty-string and null fallbacks the status handlers return while a job is running.
• Removed every 403 response. The authentication layer returns 401 for all failures, including a valid key that lacks the permission a method needs. The 401 descriptions now cover that case.
• info.version bumped from the stale 6.1.3 to 6.1.5.

Verification

• Redocly lint passes: 171 paths, 277 operations, all operationIds unique
• mint broken-links clean
• Behavior claims checked against the 6.1.5 controllers (class-mainwp-rest-authentication.php, the v2 sites/settings/monitors controllers, and the four extension controllers)

Review notes

The queued-work descriptions on /sites/sync, /sites/{id_domain}/sync, and /updates/update now tell API-key clients there is no v2 status route to poll. That is accurate for 6.1.5, and the wording should be revisited if a jobs route ships in a later Dashboard release.

Summary by CodeRabbit

• New Features
  • Added update and partial-update support for Domain Monitor and Lighthouse audit endpoints.
  • Added Page Speed and multi-token Pro Reports, including widget activity and resolved report content.
  • Added optional multi-token filtering for Pro Reports.
• Documentation
  • Updated API documentation to reflect consolidated authorization errors and WordPress Abilities API job tracking.
  • Made Pro Reports date filters optional, defaulting to the previous year when omitted.
  • Expanded documentation for success responses, timestamps, and background-job errors.

[coderabbitai]

Walkthrough

The API reference now targets version 6.1.5. It consolidates authorization responses, documents new update methods, expands Pro Reports, and describes updated success, queued-job, and background-job response schemas.

Changes

API contract documentation

Layer / File(s)	Summary
Response and job contracts api-reference/openapi.yaml	The OpenAPI document consolidates unauthorized responses into 401, references the WordPress Abilities API for queued jobs, expands success values, and documents structured job errors and timestamp types.
Extension operation methods api-reference/openapi.yaml, api-reference/rest-api/extensions.mdx	Domain Monitor and Lighthouse routes now document PUT and PATCH methods in addition to POST.
Pro Reports contracts api-reference/openapi.yaml, api-reference/rest-api/extensions.mdx	Pro Reports adds pagespeed and multi-tokens types, optional date filters, the multi_tokens parameter, and widget, Page Speed, and multi-token routes.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• mainwp/docs#108: This PR updates the OpenAPI specification introduced by PR #108.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the primary change: aligning the REST API OpenAPI specification with Dashboard 6.1.5.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/openapi-spec

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

api-reference/openapi.yaml (1)

237-243: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚖️ Poor tradeoff

Consider one reusable response component for the 401 body.

The same 401 description and Error schema now repeat in every operation. A single components.responses.Unauthorized entry, referenced with $ref, keeps the wording in one place and prevents drift when the text changes again. If this file is generated, apply the change in the generator instead.

♻️ Proposed shared response component

components:
  responses:
    Unauthorized:
      description: The API key is missing, malformed, or disabled, or does not carry the permission this method needs.
      content:
        application/json:
          schema:
            $ref: '`#/components/schemas/Error`'

Each operation then uses:

        '401':
          $ref: '`#/components/responses/Unauthorized`'

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@api-reference/openapi.yaml` around lines 237 - 243, Define one reusable
components.responses.Unauthorized entry containing the existing 401 description
and Error schema, or update the generator that produces this file if applicable.
Replace each operation’s duplicated 401 response body with a $ref to
components.responses.Unauthorized while preserving the existing 401 status.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@api-reference/openapi.yaml`:
- Around line 237-243: Define one reusable components.responses.Unauthorized
entry containing the existing 401 description and Error schema, or update the
generator that produces this file if applicable. Replace each operation’s
duplicated 401 response body with a $ref to components.responses.Unauthorized
while preserving the existing 401 status.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 55f8350a-c4a0-4417-96ed-882a0165132e

📥 Commits

Reviewing files that changed from the base of the PR and between 11f9dcd and 0991e90.

📒 Files selected for processing (2)

• api-reference/openapi.yaml
• api-reference/rest-api/extensions.mdx