docs: add user scopes, pagination, and extended pricing fields to pricing overrides OpenAPI spec

[Pratham-Mishra04]

Summary

Extends the Pricing Overrides API with user-scoped override support, pagination/search on the list endpoint, and a significantly expanded set of priceable fields covering new token tiers, cache variants, image quality/size tiers, and OCR costs.

Changes

• Introduced a shared PricingOverrideScopeKind schema component, replacing inline enum definitions across PricingOverride, CreatePricingOverrideRequest, UpdatePricingOverrideRequest, and the list query parameter. The enum now includes three new user* scopes: user, user_provider, and user_provider_key. Resolution priority is documented: virtual_key* > user* > provider/global, with more-specific matches winning within a family.
• Added user_id field to override request/response schemas and as a query filter on the list endpoint, required when using user* scopes.
• Updated provider_id and provider_key_id descriptions to reflect their applicability to the new user_provider and user_provider_key scopes.
• Added pagination and search to the list endpoint via limit, offset, and search query parameters. When any of these are present, the response switches to a paginated shape with total_count, limit, and offset fields alongside the existing count. The non-paginated path remains backward-compatible.
• Expanded PricingPatch with many new pricing fields, organized into logical sections:
  • Text: input/output_cost_per_token_flex, input/output_cost_per_token_fast (Anthropic research preview, flat rate with no tiering)
  • 128k tier: input_cost_per_image/video/audio_above_128k_tokens
  • 200k tier: priority variants for input and output
  • 272k tier: standard, priority, and flex variants for input and output
  • Cache: flex, priority, fast, and 272k-tier variants; cache_creation_input_token_cost_above_1hr and its 200k/fast variants
  • Image: premium_image combined tiers at 512px and 1024px, input_cost_per_image_token
  • Other: inference_geo_us_multiplier (Anthropic data-residency), ocr_cost_per_page, 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

Verify the updated OpenAPI spec is valid and that the new fields and parameters appear correctly:

# Validate the OpenAPI spec
npx @redocly/cli lint docs/openapi/openapi.yaml

# Confirm new scope kinds are present
grep -E "user|user_provider|user_provider_key" docs/openapi/openapi.yaml

# Confirm pagination parameters are present on the list endpoint
grep -E "limit|offset|search" docs/openapi/paths/management/governance.yaml

Breaking changes

• Yes
• No

The list endpoint response gains new optional fields (total_count, limit, offset) and the non-paginated path continues to behave as before. Existing scope_kind enum values are unchanged; new values are additive.

Related issues

Security considerations

The new user_id scoping field allows pricing overrides to be applied per user. Ensure that user_id values are validated against authenticated session context server-side and are not accepted from untrusted input without authorization checks.

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
• docs: add user scopes, pagination, and extended pricing fields to pricing overrides OpenAPI spec #5852 👈 (View in Graphite)
• dev

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 4527a1ad-6b00-4efe-b880-a274c8eb395d

📥 Commits

Reviewing files that changed from the base of the PR and between adfb312 and 4f19c15.

📒 Files selected for processing (4)

• docs/openapi/openapi.json
• docs/openapi/openapi.yaml
• docs/openapi/paths/management/governance.yaml
• docs/openapi/schemas/management/governance.yaml

🚧 Files skipped from review as they are similar to previous changes (4)

• docs/openapi/openapi.yaml
• docs/openapi/paths/management/governance.yaml
• docs/openapi/openapi.json
• docs/openapi/schemas/management/governance.yaml

---

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Added support for user-specific and user-provider pricing override scopes.
  • Expanded pricing options for flexible, fast-mode, tiered, caching, media, OCR, annotation, and inference-geography rates.
  • Added filtering and pagination controls for pricing overrides, including user ID, search, limit, and offset.
• API Improvements
  • Pricing override responses now include pagination metadata and clearer count information.
  • Standardized pricing scope values across related requests and responses.

Walkthrough

The OpenAPI contract adds shared user-scoped pricing override schemas, expanded pricing fields, list filters, and pagination metadata.

Changes

Pricing override API contract

Layer / File(s)	Summary
Scope kinds and listing filters docs/openapi/schemas/management/governance.yaml, docs/openapi/openapi.yaml, docs/openapi/paths/management/governance.yaml, docs/openapi/openapi.json	Adds shared pricing override scope values and list filters for user_id, search, limit, and offset.
Expanded pricing patch fields docs/openapi/schemas/management/governance.yaml, docs/openapi/openapi.json	Adds flex, fast-mode, tiered, cache, media, inference-geo, OCR, and annotation pricing fields.
Override models and pagination metadata docs/openapi/schemas/management/governance.yaml, docs/openapi/openapi.json	Adds user_id, reuses PricingOverrideScopeKind, and documents paginated count, total_count, limit, and offset semantics.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• maximhq/bifrost#5581: Documents the user-scoped pricing override schema and API fields introduced by this PR.
• maximhq/bifrost#5582: Defines the same user-scoped pricing override kinds, user_id fields, and filtering APIs.
• maximhq/bifrost#5853: Documents related pricing-override filters and expanded pricing fields.

Suggested reviewers: akshaydeo, impoiler, danpiths

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main OpenAPI changes: user scopes, pagination, and expanded pricing fields.
Description check	✅ Passed	The description covers the purpose, changes, testing steps, affected areas, compatibility, security, and checklist requirements.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 08-04-fix_sync_pricing-override_openapi_spec_with_backend

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 oasdiff (1.27.0)

docs/openapi/openapi.json

Error: failed to load revision spec from "docs/openapi/openapi.json": map key "MCPClientCreateRequestHTTP" not found

docs/openapi/openapi.yaml

Error: failed to load base spec from "/tmp/coderabbit-oasdiff-base.ZiMEYd": encountered disallowed external reference: "./paths/inference/async.yaml#/components/parameters/AsyncJobId"

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 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/openapi/paths/management/governance.yaml`:
- Around line 1133-1149: The pricing override endpoint does not match its
documented presence-based pagination and search behavior. Update the handler’s
search detection to recognize the query parameter whenever it is present,
including an empty value, while preserving the legacy response only when
pagination and search parameters are absent; also update
GetPricingOverridesPaginated to search both name and pattern, or revise the
OpenAPI description to document name-only search.

In `@docs/openapi/schemas/management/governance.yaml`:
- Around line 1779-1791: Update the reusable pricing-override scope schemas in
docs/openapi/schemas/management/governance.yaml at lines 1779-1791, 1837-1849,
and 1878-1890 to use oneOf variants that require the correct identifier
combination for every scope_kind; apply these variants to both response and
create models, and define update validation against the final merged scope state
when scope_kind or identifiers change.

🪄 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: 0a4c9075-fe1a-4024-9492-57d5a09cd894

📥 Commits

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

📒 Files selected for processing (4)

• docs/openapi/openapi.json
• docs/openapi/openapi.yaml
• docs/openapi/paths/management/governance.yaml
• docs/openapi/schemas/management/governance.yaml

[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:42 AM UTC: @akshaydeo merged this pull request with Graphite.