docs(api): make the reference examples internally consistent - #248
Merged
Conversation
Covers product changes from the past five days across AI SRE, Monitors and RUM. - ai-sre/artifacts: document public (anonymous) artifact sharing — account-only vs public-link visibility, the content-snapshot model, update/revoke, and the 16 MiB cap; broaden publishable file types well beyond HTML/Markdown; correct the card type icon and title truncation - ai-sre/environments: add the degraded Runner status, its two detection signals and recovery paths, and note that degraded Runners stay selectable - ai-sre/knowledge: replace the extension allowlist with the content-based UTF-8 text rule; narrow the document-conversion list to the modern Office formats and call out legacy .doc/.xls/.ppt rejection - ai-sre/sessions: subagent/A2A child sessions are viewable read-only through a shared root link (no fork); forked dispatches always show as interrupted; HTML attachments - ai-sre/insight: entry kind scheduled -> automation, matching sessions.mdx - monitors/targets: new ServiceMap page (topology canvas, node/dependency detail fields, unresolved endpoints, host list, evidence quality) - monitors/quickstart: the data source type picker lists only configured types - rum/error-tracking: the Issue count on an application card deep-links into the error tracking list with the card's own scope
- changelog: new 2026-08-06 entry covering the artifact public-link sharing mode (snapshot semantics, update/revoke, 16 MiB cap), the broadened set of publishable artifact types, and the ServiceMap topology feature - monitors/targets/servicemap: mark the page as Beta and state the monit-agent eBPF dependency up front
…0806-014513 docs: sync doc-review findings (2026-08-06)
…0260806 docs(api): publish ServiceMap and RUM rule endpoints
Each of these contradicted itself on the rendered page: - ServiceMap fleet: the response showed a single `active` host for a request filtering on `degraded`/`stale`, while `coverage` claimed two returned and counted one of each. Now two hosts that match both the filter and the counts. - Preset-severity: the rule returned by `create` carried a priority the `list` example contradicted, and the history example's "empty" snapshot was timestamped after a rule that already existed. Rebuilt as one timeline — two creates and a disable, three snapshots, each holding the state the call that wrote it was about to change. - History `total` now equals the number of items returned, in both the preset-severity and error-ingestion examples. - Resource info: the order id encoded a date a year after the `created_at` of the resource it provisioned, and the billing window was not the 30-day span anchored at `created_at` that the field descriptions promise. - Example addresses now use the RFC 5737 documentation range, which the rest of the corpus already uses, instead of private-range ones. Examples feed no code generation — only the request-side ones reach the CLI, and none of those change here — so the generated SDK and CLI are unaffected.
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.
Every item here is a contradiction a reader can see on the rendered page.
fleetdegraded/stale; response returns oneactivehost, whilecoveragesaysreturned: 2and counts one degraded + one stalecreatepriority: 3for a rule thelistexample shows atpriority: 1priority: 2, andlistnow orders by creation, so priority and creation order agreehistory/listtotal: 4beside 2 items; theversion=1"empty" snapshot is timestamped after a rule that already existedtotal: 3, each snapshot holding the state its own call was about to changehistory/listtotal: 3beside 1 item; the snapshot already carried the update it was supposed to precedetotal: 2, the pre-update state where it belongsresource/infoorder_idencodes 2026-06-15 for a resourcecreated_at2025-06-15; billing window not anchored atcreated_atcreated_atthe field descriptions promiseNo downstream release needed. Examples feed no code generation: the CLI reads only request-side examples (
internal/cmd/cligen/main.go:461) and none of those change here. Verified by regenerating the SDK against this spec — only the vendored JSON differs, zero generated Go changes — and the SDK's spec-example round-trip test passes against the new payloads.Structural verification is unchanged and green: 12 specs parse, EN/ZH operation and schema key sets equal, nav allow-list agrees with the specs both ways, 654 catalog links match their
x-mint.href, and counts stay 327 across the declared total, per-module sums, table rows, and the specs themselves.