Skip to content

docs: document every Maintainerr API endpoint - #167

Merged
enoch85 merged 2 commits into
mainfrom
docs/api-reference-complete
Aug 30, 2026
Merged

docs: document every Maintainerr API endpoint#167
enoch85 merged 2 commits into
mainfrom
docs/api-reference-complete

Conversation

@enoch85

@enoch85 enoch85 commented Aug 30, 2026

Copy link
Copy Markdown
Collaborator

Replaces the partial API page with complete reference documentation for all 219 Maintainerr endpoints.

What was added

Page Endpoints Covers
api/settings 74 Every integration's connection settings, connection tests, the media server switch
api/rules 29 Rule groups, execution, exclusions, community rules, YAML import and export
api/overlays 28 Overlay settings, processing runs, templates, fonts and images
api/collections 25 Collections, membership, bulk media actions, handling, posters, logs
api/media-server 23 Libraries, items, search, watch state, users, media server collections
api/notifications 8 Agents, configurations, rule group links, test sends
api/app-and-health 7 App status, time zone, releases, health probes, task status
api/logs 6 Log stream, log files, log level settings
api/seerr 6 Seerr lookups, requester names, request and media deletion
api/metadata-and-storage 6 Metadata provider lookups, storage metrics, the events stream
api/servarr 5 Radarr, Sonarr and Sportarr disk space and quality profiles
api/streamystats 2 Streamystats server info and per-item watch statistics

docs/API.md keeps its api id and /api slug 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 a 200, POST answering 201, default error bodies, and which routes return secrets unmasked.

Bundled OpenAPI spec

static/openapi-spec/maintainerr_api_specs.yaml was badly stale and is regenerated from the current server.

Before After
Paths 120 187
Operations 152 239
Missing live paths 72 0
Paths that no longer exist 5 0

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.md normally 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 one sidebars.js line. versioned_docs/ is untouched.

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
enoch85 force-pushed the docs/api-reference-complete branch from 057f2a1 to 8dc4527 Compare August 30, 2026 07:42
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.
@enoch85
enoch85 merged commit 313fdfb into main Aug 30, 2026
3 checks passed
@enoch85
enoch85 deleted the docs/api-reference-complete branch August 30, 2026 08:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant