docs(api): publish ServiceMap and RUM rule endpoints, fix reference drift - #246
Merged
ysyneu merged 2 commits intoAug 6, 2026
Merged
Conversation
…rift
Publishes 23 endpoints and corrects five places where the reference no
longer matched how the service behaves.
New endpoints
- Monitors / Service map (5): status, topology, summary, fleet and
fleet/summary. The subsystem is optional, so each page states that a
deployment without the ServiceMap store configured answers
ServiceUnavailable (503).
- RUM / Error ingestion rules (8) and Issue preset severity rules (9):
list, create, update, delete, enable, disable, reorder (severity rules
only) and the history list/revert pair.
- RUM / Resources (1): resource/info.
Corrections
- /incident/work-item/list no longer requires the On-call Pro license, so
that note is dropped. The work-item mutations stay Pro-gated.
- /incident/comment-type/{create,update,delete,reorder} are gated by the
new Comment Types Manage permission rather than Incidents Manage;
holding only the latter is rejected. The read path is unaffected.
- /member/info/reset gains the `from` field, which marks an updated phone
or email as verified when the account has member invites disabled, and
now rejects an empty `updates` object.
- /rum/facet/list is removed. It has had no backend route since the facet
model was replaced by fields, and it is no longer registered on the
gateway, so every documented call 404s. The usage note on
/rum/facet/count now points at /rum/field/list, its replacement.
- The consolidated specs were missing the AlertRule family's `timezone`
property and the cron_pattern note that goes with it. Both are synced
from the per-module spec so an exported rule keeps its timezone.
Also backfills two catalog rows for endpoints that shipped without an
index entry (post-mortem content reset, on-call license list), and stops
the generator emitting "1 requests/second" for a rate limit of one.
Review tip: the consolidated spec renders as 18 hunks with
`--diff-algorithm=histogram`, versus 4174 with the default.
- error-ingestion and preset-severity `rules/delete` said the rule stops being evaluated immediately. The enabled-rule set is cached for up to 5 seconds — the same lag already documented for enable/disable. - preset-severity `rules/reorder` said only rules strictly between the two original positions shift. The target rule shifts as well. - preset-severity `rules/history/list` said a snapshot is written before every update call. An update carrying none of the mutable fields writes none. - preset-severity `rules/create` declared `minItems: 1` on `filters`, which the server does not enforce: an empty array is accepted and yields a rule that can never match. Drop the constraint and state the real behaviour instead. - `resource/info` said `no_cache` recomputes the session usage counts. It bypasses the cache of the resource record; the counts come from a separate hourly cache the flag does not touch.
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.
Brings the public API reference back in line with what the services actually serve: 23 endpoints that were live but undocumented, one that was documented but dead, and five smaller mismatches.
New endpoints (23)
status,topology,summary,fleet,fleet/summarylist,create,update,delete,enable,disable,history/list,history/revertreorderresource/infoNotes worth a reviewer's eye:
ServiceUnavailable(503), which is documented per endpoint.ataccepts onlynowanddirectiononlyoutboundtoday; both are stated rather than presented as open enums.reorderis a single-item move, not a swap or a full reordering: the dragged rule takes the target's priority and everything strictly between shifts by one.history/revertanswersInvalidParameterfor an unknown version, notResourceNotFound. This breaks the pattern the other rule-id operations follow, so it is called out on the page.app_keycan call this operation", which is accurate: none of the API names appear as a factor on any permission point. Thirteen of them mutate rules. Flagging it here because publishing makes that gap visible; closing it is a backend change, not a docs one.Removed (1)
POST /rum/facet/listhad no backend route since the facet model was replaced by fields, and is no longer registered on the gateway — every documented call 404s./rum/facet/count's usage note pointed readers at it and now points at/rum/field/list, its replacement.Corrections (5)
/incident/work-item/listis no longer Pro-gated; the note is dropped. The work-item mutations stay Pro-gated./incident/comment-type/{create,update,delete,reorder}moved to the new Comment Types Manage permission — holding only Incidents Manage is rejected. The read path still accepts either./member/info/resetgainsfrom, which marks an updated phone or email as verified when the account has member invites disabled, and now rejects an emptyupdates.timezoneproperty and thecron_patternnote about it, so a rule exported through them lost its timezone. Synced from the per-module spec.Plus one generator fix: a rate limit of one rendered as "1 requests/second".
Verification
Structural checks over all four surfaces that have to agree — the module spec Mintlify renders, the consolidated copy used for SDK and Apifox import, the
docs.jsonnav allow-list, and the hand-maintained catalog:x-mint.href— zero mismatches.$refanywhere. Every new integer time field carriesUnixin its description (seconds vs milliseconds distinguished), so the SDK generator maps them to a timestamp type rather than a bare int.Reading the diff
The consolidated spec renders as 18 hunks with
--diff-algorithm=histogramand 4174 with the default — deleting one path from the middle of a large uniform JSON confuses Myers badly. Real shape: 5031 insertions, 136 deletions, net +4895 lines.