docs: document every Maintainerr API endpoint - #167
Merged
Conversation
Replace the partial API page with complete reference documentation for all 219 endpoints, split into twelve per-area pages under docs/api/. Also regenerate the bundled OpenAPI YAML from the current server: it carried 120 paths against 187 live, missing 72 and listing 5 that no longer exist.
enoch85
force-pushed
the
docs/api-reference-complete
branch
from
August 30, 2026 07:42
057f2a1 to
8dc4527
Compare
Twelve endpoints documented a request body without saying that nothing validates it. Each now says so, with the concrete consequence where there is one: the yaml and migrate routes answer code 0 with Invalid input rather than a 400, and a misspelled field on the rule test route is read as missing instead of being rejected. The API conventions section says again that all seventeen carry the note, which is now true.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Replaces the partial API page with complete reference documentation for all 219 Maintainerr endpoints.
What was added
api/settingsapi/rulesapi/overlaysapi/collectionsapi/media-serverapi/notificationsapi/app-and-healthapi/logsapi/seerrapi/metadata-and-storageapi/servarrapi/streamystatsdocs/API.mdkeeps itsapiid and/apislug and becomes a hub: the existing no-auth danger admonition, a new API conventions section, and a table of contents. The "does not yet embed the generated Swagger reference" note and the "Notable endpoints" framing are gone, since coverage is no longer partial.Each endpoint has a summary, parameter table, request and response shapes, a status-code table with the real cause of each code, side effects, and the traps a caller would otherwise hit. All 46 destructive endpoints carry a warning saying what they destroy and whether it can be undone.
Conventions section
Cross-cutting facts that hold API-wide, so they are stated once rather than per endpoint: no authentication, no rate limiting,
BASE_PATH, CORS, request validation (70 endpoints take a body, 17 with no schema), the OK/NOK envelope that reports failure inside a200,POSTanswering201, default error bodies, and which routes return secrets unmasked.Bundled OpenAPI spec
static/openapi-spec/maintainerr_api_specs.yamlwas badly stale and is regenerated from the current server.The 5 removed:
/api/moviedb/image/{type}/{tmdbId},/api/moviedb/movie/imdb/{id},/api/moviedb/person/{personId},/api/rules/exclusions/{plexId},/api/rules/schedule/update.The sidebars.js edit
AGENTS.mdnormally forbids touching sidebars. This PR edits it anyway, adding the twelve new ids under the existing API category. It is unavoidable: new doc pages have no route into the site otherwise, so without it the twelve pages would build but be unreachable. The edit is additive and changes nothing about the existing entries.Scope
Only
docs/,static/openapi-spec/and that onesidebars.jsline.versioned_docs/is untouched.