docs: add user scopes, fast-mode costs, OCR fields, and pagination to custom pricing docs

[Pratham-Mishra04]

Summary

Expands the custom pricing documentation to cover new user-scoped overrides, additional pricing fields (fast-mode, OCR, premium images, extended cache creation/read tiers), and updated API behavior including paginated list responses and a corrected PUT verb for updates.

Changes

• Added three new scope kinds — user, user_provider, and user_provider_key — to the scope hierarchy, table, and field reference, positioned between the virtual-key family and the provider/global scopes
• Clarified scope resolution order: virtual-key family is checked before user family, which is checked before provider/global scopes
• Updated the scope_kind enum in the config field reference to include all user* variants and added the user_id conditional field
• Corrected the update endpoint verb from PATCH to PUT and added a note that omitted fields are merged from the existing record
• Added pagination support to the list endpoint (limit, offset, search query params) with documentation of the paginated response shape and all supported query filters
• Added new pricing patch fields: input_cost_per_token_fast, output_cost_per_token_fast, and their cache counterparts (cache_creation_input_token_cost_fast, cache_read_input_token_cost_fast, cache_creation_input_token_cost_above_1hr_fast)
• Added extended cache creation/read tier fields for flex and 272k+ context windows, 1hr+ TTL entries, and 200k+ context with 1hr+ TTL
• Added premium image output cost fields and per-resolution premium image variants
• Added input_cost_per_image_above_128k_tokens for image input above 128k context
• Added inference_geo_us_multiplier for data-residency cost multipliers
• Added a new OCR costs section covering ocr_cost_per_page and annotation_cost_per_page

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

Review the rendered documentation to confirm:

• The scope hierarchy diagram and table include all three user* scope kinds in the correct position
• The update example uses PUT and includes the merge-patch note
• The list example shows the paginated query and documents all supported filters
• All new pricing fields appear in their respective sections with accurate descriptions

Breaking changes

• Yes
• No

Security considerations

None. This is a documentation-only change.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Pratham-Mishra04]

• feat: add pricing fields for >2048px and >4096px image output cost overrides #5854
• docs: add user scopes, fast-mode costs, OCR fields, and pagination to custom pricing docs #5853 👈 (View in Graphite)
• docs: add user scopes, pagination, and extended pricing fields to pricing overrides OpenAPI spec #5852
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Added guidance for user-scoped pricing overrides and precedence across user, provider, and provider-key settings.
  • Documented user identifiers, scope combinations, and pricing configuration fields.
  • Updated the pricing update example to use PUT with sparse merge semantics.
  • Expanded API listing documentation with pagination, search, and supported filters.
  • Clarified cost and multiplier units, image-size thresholds, and pricing for fast mode, flex tier, premium images, inference regions, OCR, TTL-specific caching, and related cache and image costs.

Walkthrough

The custom pricing documentation adds user-scoped override rules, updates pricing API behavior, expands list API parameters, and documents additional token, image, cache, inference-region, and OCR pricing fields.

Changes

Custom pricing documentation

Layer / File(s)	Summary
User override scopes docs/providers/custom-pricing.mdx	Documents user, user-provider, and user-provider-key scopes, their precedence, and required identifiers.
Pricing API behavior docs/providers/custom-pricing.mdx	Changes the update example to PUT, documents sparse merge behavior, and adds pagination, search, and filtering details to the list API.
Pricing field coverage docs/providers/custom-pricing.mdx	Clarifies pricing units and adds fast-mode, flex-tier, cache, image, inference-region, OCR, and annotation pricing fields.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• maximhq/bifrost#5852: Documents the corresponding user-scoped pricing overrides, API behavior, and expanded pricing fields in OpenAPI updates.

Suggested reviewers: akshaydeo, danpiths

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the documentation updates for user scopes, pricing fields, and pagination.
Description check	✅ Passed	The description covers the required sections and provides clear documentation changes, validation steps, scope, and impact details.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 08-04-fix_sync_custom-pricing_docs_with_backend

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/providers/custom-pricing.mdx`:
- Around line 211-212: Update the custom pricing update semantics documentation
to explicitly state that supplying scope_kind resets all scope identifiers and
retains only identifiers included in that request, while preserving the existing
merge behavior for other omitted fields and full replacement behavior for patch.
- Line 403: Update the introductory pricing-field description near the
`inference_geo_us_multiplier` entry to distinguish USD-denominated cost fields
from dimensionless multiplier fields. Preserve the existing explanation of
`inference_geo_us_multiplier` as a factor applied to token and cache costs.
- Around line 375-379: Remove the premium-image pricing rows from the custom
pricing documentation until billing supports them. Keep only rate fields
currently consumed by computeImageOutputCost and represented by ImageUsage,
without documenting inactive premium fields.
- Around line 376-379: Update the image-size descriptions for the
output_cost_per_image_above_512_and_512_pixels,
output_cost_per_image_above_1024_and_1024_pixels, and corresponding premium
tiers to say “at or above” the stated dimensions, reflecting inclusive threshold
matching.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 368d4968-cb0c-4ef6-a207-bcabca1f00c4

📥 Commits

Reviewing files that changed from the base of the PR and between 3a549b0 and d30f090.

📒 Files selected for processing (1)

• docs/providers/custom-pricing.mdx

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[akshaydeo]

Merge activity

• Aug 5, 4:41 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Aug 5, 4:43 AM UTC: @akshaydeo merged this pull request with Graphite.

The base branch was changed.