docs(drift): draft from internal source

[pedromcunha]

Drafted from an internal source repo, requested by @ipeleg.

This PR was auto-generated by the reusable-docs-draft-pr workflow from a Claude-drafted update in the source repo. It is opened as a draft — please review, edit as needed, and mark ready for review before merging.

Review checklist

• Content matches the behavior shipped in the source PR
• No internal-only details (service names, file paths, unreleased names, security internals) leaked into the draft
• Conforms to CLAUDE.md style rules
• Cross-references and internal links resolve
• Any Needs human input items from the source comment are addressed

---

Generated by reusable-docs-draft-pr.yml in relayprotocol/agents-config.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
unevenlabs	🟢 Ready	View Preview	Aug 3, 2026, 7:28 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[github-actions]

Claude finished @ipeleg's task in 2m 1s —— View job

---

Code review — docs(drift): includeTotal on GET /requests/v3

• Read the PR diff and changed files
• Check conformance with AGENTS.md / CLAUDE.md style rules
• Verify cross-references, anchors, and nav wiring
• Post review

---

Small, well-scoped drift PR: one new query parameter (includeTotal) + one new response field (total), documented in the v3 migration guide and logged in the API changelog. Placement is right — the parameter itself renders from the OpenAPI spec on references/api/get-requests.mdx (openapi: get /requests/v3), so no endpoint-page edit is needed. Changelog entry is newest-first, dated correctly, and uses the **Added** lead per AGENTS.md §4.5. Nothing internal-only leaked.

Three things worth addressing before merge, none blocking.

1. total is placed where readers will look for it on the wrong object

references/api/api_guides/migrating-to-requests-v3.mdx:478 adds total to the Added in v3 table:

| `total` (response, opt-in) | total count of requests matching the filters; returned only when `includeTotal=true` |

Every other row in that table is a field of an individual request object (requestType, sender (root), data.route.actual, feeSponsorship.actual.sponsorPayment, …). total is not — it lives on the list envelope, as a sibling of the requests array and continuation. The changelog and the prose at :313 both say only "on the response", which inherits the same ambiguity. The docs never describe the v3 list envelope anywhere (I grepped — requests/continuation as an envelope shape isn't documented), so a reader has no way to disambiguate and may go looking for data.total.

Suggest making the level explicit in both places, e.g. "returned at the top level of the list response, alongside continuation". Fix this →

2. "the full data window" is undefined and load-bearing

references/api/changelog.mdx:8:

The count reflects all matches across the full data window, not just the returned page.

"Data window" appears nowhere else in the docs. If it means a retention/lookback bound on what GET /requests/v3 can count, that's a real constraint integrators need spelled out; if it just means "all matching rows, not only this page", the clause is redundant with the preceding sentence's "independent of limit and continuation". Either name the bound concretely or drop the sentence. Worth confirming against the source PR before deciding which. Fix this →

3. Changelog paragraph exceeds the house paragraph cap

references/api/changelog.mdx:8 is a single four-sentence paragraph. AGENTS.md §2.10 caps paragraphs at 2–3 sentences and applies to every in-scope page. The tail — the advisory "keep includeTotal off on the hot list-fetch path…" — is also guide-voice rather than changelog-voice, and it duplicates the latency guidance already at migrating-to-requests-v3.mdx:313. Trimming the changelog to what changed and leaving the "when to use it" advice in the migration guide would fix both. (Noting that neighbouring entries run similarly long, so this is a guide-conformance nit, not an inconsistency with the page.)

Minor / optional

• Ordering within the accordion (migrating-to-requests-v3.mdx:313) — the new Total match count. block sits after Removed & changed parameters. An addition reading after the removals is slightly awkward; moving it above that bullet list flows better.
• Discoverability from the checklist — the pagination step at :502 ("Pagination is unchanged — keep passing continuation back…") is where readers doing paging will actually land. A half-sentence pointer to includeTotal there would earn its keep.
• §2.9 emphasis convention — the style guide asks for bold+backticks (**`paramName`**) for prose parameter references; the new prose uses plain backticks. The rest of this page uses plain backticks throughout, so the PR is internally consistent — flagging only so the choice is deliberate.

Verification notes

• Nav wiring: no docs.json change needed — GET /requests/v3 already renders via references/api/get-requests.mdx, and references/api/changelog.mdx is already in the nav.
• Anchors and internal links in the touched hunks resolve; the pre-existing [Filtering, search & sorting](#what-changed) link at :479 is unchanged by this PR.
• I could not verify includeTotal / total against the live OpenAPI spec (https://api.relay.link/documentation/json) — outbound network access is blocked in this environment. The field names, the false default, and the envelope-level placement in finding 1 should be confirmed against the source PR.

I did not make any code changes — this was a review-only pass.
· Branch docs-drift/src-250bf92d38-f7c64c9