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	Jul 30, 2026, 8:13 PM

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

[github-actions]

Claude finished @ipeleg's task in 3m 46s —— View job

---

Code review — PR #385

• Read PR diff and gather repo context
• Check conformance to AGENTS.md style rules (§2, §3.3, §4)
• Verify cross-references and docs.json nav placement
• Check for internal-only detail leakage
• Verify against the OpenAPI spec — blocked, see note at the bottom
• Post review

Small, well-scoped drift PR. Nav placement (under the Utilities group in docs.json:150) is right for a usage/metrics endpoint, links are root-relative per §2.6, the callout is well under the 15-line cap, and I found no internal-only leakage (no service names, file paths, or unreleased identifiers). A few things to fix before merge.

---

1. No changelog entry for a new public endpoint (§4.1 / §4.5)

references/api/changelog.mdx is described as the "Record of breaking changes, deprecations, and notable additions", and the existing precedent is exactly this shape:

Added — GET /requests/v3: the recommended Requests API. …

A brand-new public endpoint should get a ## 2026-07-30 — … entry with an **Added** line. Right now the endpoint ships with no dated record.

Fix this →

2. api-keys.mdx:29 — an API endpoint inside a list of Dashboard features

The list is introduced at line 22 with "The [Relay Dashboard] is also where you observe what your integration is doing in production:" and every existing bullet is a Dashboard surface (Requests, Advanced filtering, Custom views, Keys, Webhooks). "Programmatic usage metrics — the … endpoint" is not a Dashboard feature, so it reads as a category error in an otherwise consistent list. It also restates the endpoint page's entire description, which is duplication that will drift.

Better as a single sentence after the list (next to the existing requestId line at 31), e.g. "The same aggregated counts are available programmatically via Get Integrator Usage."

Fix this →

3. get-integrators-usage.mdx:3 — frontmatter and body disagree on the grouping

The description says counts are grouped by "API key, endpoint, status code, and error code"; the body (line 7) says only "endpoint, HTTP status, and … errorCode". The api-keys.mdx bullet also omits API key. One of the three is wrong — please confirm against the spec whether the response actually breaks down per key, and align all three. (Minor: the description is missing its trailing period; siblings like get-chains-liquidity.mdx have one.)

Fix this →

4. Body duplicates spec-derived detail (§3.3 drift risk)

§3.3 makes the OpenAPI spec the source of truth and the MDX a stub, with body content reserved for "a cross-cutting note OpenAPI can't express". Line 9 restates the granularity enum and each value's default window — all of which the spec already carries as query-param enum + defaults. When the spec changes (a new bucket, a different default window), this page silently goes stale.

The genuinely non-spec-expressible parts are the 14-day retention and the "how to actually use this" guidance. Keeping only those (and dropping the enum/default recital) matches the rule and removes the drift surface. Precedent for a short prose body does exist (get-intents-status-v3.mdx), so a body isn't wrong per se — just don't restate the spec in it.

Fix this →

5. errorCode values aren't linked (§2.6)

The <Tip> names AMOUNT_TOO_LOW and UNSUPPORTED_CHAIN, both of which are documented in Handling Quote Errors (lines 16 and 39 of that file). §2.6 says to link a concept that has its own page on first mention — worth a link so readers can find the full enum instead of two examples.

6. Possible reader-facing conflict on retention

api-keys.mdx:24 promises the Dashboard shows a "full history of quotes and intents made with each key", while the new page states "Data older than 14 days is not retained." These are plausibly different datasets (per-request records vs. aggregated counters), but a reader hitting both will read them as contradictory. Consider scoping the new sentence — e.g. "Aggregated usage data older than 14 days is not retained."

7. Style nits

• <Tip> on an endpoint page: §3.3 specifically calls for <Note> or <Info> for endpoint-page body notes. <Tip> is valid globally under §2.5, so this is a soft nit, but <Note> is the closer match to the profile.
• §2.9 asks for bold + backticks in prose references to a parameter — **`granularity`**, **`errorCode`** — rather than bare backticks. Applies to the new page and to the api-keys.mdx bullet.

---

Could not verify (needs a human check)

Network egress is blocked in my environment, so I could not fetch https://api.relay.link/documentation/json to confirm:

• that get /integrators/usage exists in the published spec with that exact method + path — if it doesn't, Mintlify renders an empty page, so this is the one blocking check;
• the granularity enum values, defaults, and per-value windows asserted on line 9;
• whether the response groups by API key (finding 3) and the 14-day retention claim.

The Mintlify preview is the fastest way to confirm the first one — if the parameters and response render, the openapi: reference resolved.

No code changes made — this is review feedback only.
· branch docs-drift/src-3128427f9f-19a2abd