[flashduty]

Daily api-review (--mode generate --scope all --auto). Baseline docs main fb16440 (2026-10-23T06:31:16Z). The public surface was re-verified against fc-pgy logic/api/api_test.go at 67e776e8 (385 auth=all rows outside /event/push/) and every implementation repo at origin/main.

Operation changes per module

Module	added	updated	removed
on-call	0	2	0
platform	0	1	0
monitors / rum / safari	0	0	0

Documented operations stay at 384 (385 public registry rows minus the one unresolved row below), so docs.json navigation and both api-catalog.mdx indexes need no new rows — the path-coverage check reports none for all five modules in nav and in both catalogs.

What changed and the Go evidence

1. on-call · POST /incident/create gains labels — fc-event c85709d1f, cmd/server/controller/incident/action.go: createInput.Labels map[string]string \json:"labels"`. Constraints taken from the handler, not guessed: structs.ValidateLabelCountrejects more than 50 labels,structs.NormalizeLabelsdrops blank values, rewrites keys throughLabelFormat (^[a-zA-Z_][a-zA-Z0-9_]*$, other characters become _) and truncates values at maxLenOfLabel= 8 KiB. HencemaxProperties: 50` and the normalization wording. Also added to the request example.

2. platform · POST /member/invite gains schedule_id — fc-pgy f91ce88b, cmd/server/controller/member/member.go: ScheduleID uint64 \json:"schedule_id,omitempty"`. Behaviour from logic/invite/schedule.go: the schedule is remembered at invite time and the join runs as the inviter, so the caller must be allowed to edit that schedule; a deleted schedule or one with no joinable layer is skipped quietly (permanentJoinMarker). Also added to the request example (5789640530410`, the schedule ID already used elsewhere in the reference).

3. on-call · POST /channel/escalate/rule/reorder gains its request-body example — the operation became public when fc-pgy 67e776e8 flipped its registry row Auth from jwt to all. scripts/lint_openapi.py failed with missing-example on all four files that carry the operation. Note: open PR docs(api): add request body example for escalation rule reorder #1127 ("docs(api): add request body example for escalation rule reorder") fixes the same four spots with different ID values; this PR is self-contained and green, so if both land, take either set — if docs(api): add request body example for escalation rule reorder #1127 merges first this branch needs a trivial rebase on those four hunks, otherwise docs(api): add request body example for escalation rule reorder #1127 can be closed as superseded.

4. docs.json: one regenerated bare-path redirect for /channel/escalate/rule/reorder. This is the third surface that a new operation must reach: scripts/api_path_redirects.py --check was already failing on main because the page was added in docs(api): add escalation rule reorder endpoint #1126 without re-running the script. That is also why docs(api): add request body example for escalation rule reorder #1127's lint job is red today — the check runs in the same workflow. The entry was produced by the in-repo script (not hand-appended, so the ordering stays canonical) and --check now exits 0.

Unresolved (not written into any spec)

• POST /channel/incident/daily-counts (channel:read:incidentDailyCounts, Auth: all): still no handler or route on fc-event origin/main — the controller exists only on origin/dev. Unchanged from previous rounds.

Examples

This environment cannot call the dev API (no way to reference the credential env var directly), so every example added or touched here is constructed from the schema and the handler, with realistic values rather than placeholders. Nothing in this PR was captured from a live response.

Deliberately not changed (recorded for a human)

• DutyError split vs consolidated: the consolidated copies carry reason under the x-flashduty-preserve-absence hand-edit marker, the split copies do not. Left alone per the standing convention.
• Localized example values in the zh specs: safari's three artifact/gallery operations and monitors' POST /monit/rule/move use Chinese values in responses.200 examples (张伟, 移动成功) where the EN file has English ones. Introduced by 4eaf43df and kept since; the bilingual contract says examples carry the same values in both languages. Fixing it is a pure text revert of that pass, so it needs a maintainer's call rather than this round.
• Orphan schemas from non-public scopes: AlertRule (referenced only by RuleImportRequest, whose /monit/rule/bundle/import/* rows are jwt), AlertEvent (the /event/push/ payload) and MetricProbe*-style leftovers have no path referencing them. AlertRule also lacks investigation_targets, which model/alert_rule.go serializes — correct as long as no public operation returns it, so it was not touched. Garbage-collecting them belongs to a regeneration of those scopes.
• Published rate limits: unchanged, still the long-standing account-level vs registry AQps/AQpm gap that needs a policy decision before a bulk rewrite.

Verification

• python3 -c "import json; json.load(open(...))" on all six spec files plus docs.json — all parse.
• python3 scripts/lint_openapi.py → OK: 12 spec files, no violations.
• python3 scripts/api_path_redirects.py --check → exit 0 (was exit 1 on main).
• HEAD → worktree deep comparison of all six spec files: every change is a pure insertion (labels, schedule_id, the reorder example, its request-example key); no key was removed, reordered or rewritten, and the pre-existing key order of each file is preserved as a subsequence. git diff totals 104 insertions / 4 deletions across 7 files, and the deletions are only the four lines that had to gain a trailing comma.
• EN/ZH structural parity re-checked: no structural difference in either module beyond the pre-existing localized example values noted above.
• mint broken-links could not be run: mint is not installed in this environment. No path, tag or nav entry changed, so no new link can be produced.