docs: add per-user access-profile budget override API and docs

[impoiler]

Summary

Adds a per-user budget override mechanism for access-profile budgets, allowing administrators to temporarily raise a single user's spending limit without modifying the shared profile template or affecting other users.

Changes

• Added PUT /api/users/{target_user_id}/access-profiles/{profile_id}/budgets/{budget_id}/override to set or replace a spending override on a user's access-profile budget. The override is additive (effective_max_limit = base_limit + override_amount) and leaves the base limit, current usage, and reset schedule untouched.
• Added DELETE /api/users/{target_user_id}/access-profiles/{profile_id}/budgets/{budget_id}/override to remove an active override, reverting enforcement to the base max_limit.
• Overrides support two modes: cycles (active for a finite number of reset windows, with the current window counting as the first) and forever (active until explicitly deleted). Overrides propagate cluster-wide and survive profile cloning and propagation.
• Both endpoints require the AccessProfiles.Update permission and reference the budget on the user's own copy of the profile, not the shared template.
• Documented the budget override feature in access-profiles.mdx, including the additive formula, mode options, curl examples, and a cross-reference to the equivalent virtual key override feature.

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

# Set an override for 2 reset cycles
curl -X PUT "$BIFROST_URL/api/users/$USER_ID/access-profiles/$PROFILE_ID/budgets/$BUDGET_ID/override" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "mode": "cycles", "cycles": 2}'
# Expect 200 with the persisted budget and effective_max_limit = base + 100

# Set a permanent override
curl -X PUT "$BIFROST_URL/api/users/$USER_ID/access-profiles/$PROFILE_ID/budgets/$BUDGET_ID/override" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "mode": "forever"}'
# Expect 200

# Remove the override
curl -X DELETE "$BIFROST_URL/api/users/$USER_ID/access-profiles/$PROFILE_ID/budgets/$BUDGET_ID/override" \
  -H "Authorization: Bearer $TOKEN"
# Expect 200 with budget reverted to base max_limit

# Verify other users on the same profile are unaffected

Breaking changes

• No

Security considerations

Both endpoints require the AccessProfiles.Update permission. The budget_id must belong to the target user's own copy of the profile, preventing callers from modifying the shared template or budgets belonging to other users. Overrides are scoped to a single user and do not bleed into the profile template or other assigned users.

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

[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: b2a46fcf-efa5-451a-b32d-a4cce2fef3cd

📥 Commits

Reviewing files that changed from the base of the PR and between a7742dd and 5f99d0b.

📒 Files selected for processing (4)

• docs/enterprise/access-profiles.mdx
• docs/openapi/openapi.json
• docs/openapi/openapi.yaml
• docs/openapi/paths/management/accessprofiles.yaml

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added support for per-user budget overrides on access profiles.
  • Overrides can be set, replaced, or removed through management API endpoints.
  • Added support for cycle-based or indefinite (forever) override durations.
  • Documented permissions, propagation, persistence, request formats, and error responses.

• Documentation

  • Updated access-profile and OpenAPI documentation with override behavior and API details.

Walkthrough

The change documents per-user budget overrides for access profiles. It adds OpenAPI definitions for PUT and DELETE operations and describes override duration, additive limits, permissions, propagation, persistence, and API usage.

Changes

Access-profile budget overrides

Layer / File(s)	Summary
Budget override API contracts docs/openapi/openapi.yaml, docs/openapi/paths/management/accessprofiles.yaml, docs/openapi/openapi.json	The OpenAPI specification defines authenticated PUT and DELETE operations for setting, replacing, and removing user-specific access-profile budget overrides.
Override behavior documentation docs/enterprise/access-profiles.mdx	The enterprise documentation describes additive limits, reset-cycle and forever durations, permissions, propagation, persistence, and API examples.

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

Possibly related PRs

• maximhq/bifrost#5434: Documents API behavior for per-user budget overrides.
• maximhq/bifrost#5435: Implements the corresponding user access-profile budget override endpoints.
• maximhq/bifrost#5523: Updates the frontend UI for managing access-profile budget overrides.

Suggested reviewers: akshaydeo, roroghost17, pratham-mishra04

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the addition of the per-user access-profile budget override API and documentation.
Description check	✅ Passed	The description covers the purpose, API changes, behavior, testing steps, security considerations, affected areas, and breaking-change status.
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 07-31-docs_user_budget_override_api_references_and_docs

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.26.0)

docs/openapi/openapi.yaml

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

---

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

[impoiler]

• docs: add per-user access-profile budget override API and docs #5747 👈 (View in Graphite)
• main

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

[mintlify]

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

Project	Status	Preview	Updated (UTC)
bifrost	🟢 Ready	View Preview	Jul 31, 2026, 12:31 PM

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

[Pratham-Mishra04]

Merge activity

• Jul 31, 12:34 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jul 31, 12:35 PM UTC: @Pratham-Mishra04 merged this pull request with Graphite.