docs: add governance API namespace migration guide by impoiler · Pull Request #5841 · maximhq/bifrost

impoiler · 2026-08-04T10:48:52Z

Summary

Briefly explain the purpose of this PR and the problem it solves.

Changes

What was changed and why
Any notable design decisions or trade-offs

Type of change

Affected areas

How to test

Describe the steps to validate this change. Include commands and expected outcomes.

# Core/Transports
go version
go test ./...

# UI
cd ui
pnpm i || npm i
pnpm test || npm test
pnpm build || npm run build

If adding new configs or environment variables, document them here.

Screenshots/Recordings

If UI changes, add before/after screenshots or short clips.

Breaking changes

Yes
No

If yes, describe impact and migration instructions.

Related issues

Link related issues and discussions. Example: Closes #123

Security considerations

Note any security implications (auth, secrets, PII, sandboxing, etc.).

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 · 2026-08-04T10:48:58Z

📝 Walkthrough

Summary by CodeRabbit

Documentation
- Expanded API key management documentation with canonical governance routes, legacy aliases, deprecation guidance, and updated endpoint listings.
- Added a governance API namespace migration guide covering route mappings, permissions, pagination, team and customer semantics, and rollout steps.
- Updated Audit Logs documentation to identify /api/governance/audit-logs as the canonical endpoint and legacy paths as deprecated.
Tests
- Added automated validation to keep documented endpoints aligned with the API specification and deprecation labels.

Walkthrough

The PR adds a governance API namespace migration guide, expands governance endpoint documentation, and adds a validation script that checks documented paths against openapi.yaml.

Changes

Governance API documentation

Layer / File(s)	Summary
Governance namespace migration guide `docs/migration-guides/governance-api-namespace.mdx`	Documents canonical routes, legacy aliases, deprecation behavior, endpoint mappings, permissions, pagination, team-customer semantics, and rollout steps.
Governance endpoint documentation `docs/api/procuring-api-keys.mdx`	Lists expanded governance routes, deprecated aliases, updated parameters, and canonical audit log paths.
Documentation route validation `docs/api/procuring-api-keys_test.py`	Compares documented paths with `openapi.yaml` and validates canonical route coverage and deprecated labels.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

maximhq/bifrost#5650: Updates the OpenAPI governance routes and legacy aliases covered by this documentation.
maximhq/bifrost#5831: Updates related Management API endpoint coverage and documentation.

Suggested reviewers: bearts, akshaydeo

🚥 Pre-merge checks | ✅ 2 | ❌ 3

❌ Failed checks (3 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The changes document governance API namespaces and aliases, but linked issue `#123` requires File API support for file uploads and related workflows.	Add or link implementation and documentation changes for the File APIs described in issue `#123`, including the required file upload endpoints.
Out of Scope Changes check	⚠️ Warning	The PR changes are focused on governance API documentation and validation, which is unrelated to the linked issue `#123` about File API support.	Link the correct governance API issue or revise the PR to address the File API requirements in issue `#123`.
Description check	⚠️ Warning	The description contains only the unfilled template and omits the PR purpose, changes, testing steps, affected areas, and security details.	Replace the default template text with completed sections that describe the documentation changes, validation script, affected Docs area, test command, breaking changes, and security considerations.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly identifies the main change: adding a governance API namespace migration guide.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch 08-04-docs_governance_api_migration_guide

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

impoiler · 2026-08-04T10:49:06Z

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

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/api/procuring-api-keys.mdx`:
- Line 49: Update the governance endpoint rows around the RBAC, User, Team, and
access-profile entries to use their canonical /api/governance paths, or
explicitly label the existing legacy paths as deprecated aliases. Ensure the
table clearly distinguishes canonical routes from aliases and no longer presents
removal-bound routes as standard management endpoints.

In `@docs/migration-guides/governance-api-namespace.mdx`:
- Around line 1-4: Add the new governance migration guide entry to the Migration
Guides section of docs/docs.json, using the path
migration-guides/governance-api-namespace so it appears in documentation
navigation.

🪄 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: 16d46cfa-2b64-418d-a58c-d182fc2c3ee0

📥 Commits

Reviewing files that changed from the base of the PR and between c9d55ea and 6a574ef.

📒 Files selected for processing (2)

docs/api/procuring-api-keys.mdx
docs/migration-guides/governance-api-namespace.mdx

coderabbitai · 2026-08-10T13:30:06Z

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.

coderabbitai

Actionable comments posted: 1

🤖 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/api/procuring-api-keys_test.py`:
- Around line 43-64: Complete LEGACY_TO_CANONICAL using
docs/api/procuring-api-keys.mdx as the source of truth, adding every documented
deprecated alias and its canonical successor, including
/api/users/email/{email}, nested access-profile routes, and nested audit-log
routes. Preserve the existing mappings and ensure the mapping has parity with
the documented API paths and provider behavior.

🪄 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: c1be0e93-2774-401c-98c2-e91965894c04

📥 Commits

Reviewing files that changed from the base of the PR and between af72e02 and 73a9a9a.

📒 Files selected for processing (3)

docs/api/procuring-api-keys.mdx
docs/api/procuring-api-keys_test.py
docs/migration-guides/governance-api-namespace.mdx

…ilies

…specs

akshaydeo · 2026-08-11T07:01:23Z

Merge activity

Aug 11, 7:01 AM UTC: A user started a stack merge that includes this pull request via Graphite.
Aug 11, 7:05 AM UTC: @akshaydeo merged this pull request with Graphite.

The base branch was changed.

## Summary Briefly explain the purpose of this PR and the problem it solves. ## Changes - What was changed and why - Any notable design decisions or trade-offs ## 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 Describe the steps to validate this change. Include commands and expected outcomes. ```sh # Core/Transports go version go test ./... # UI cd ui pnpm i || npm i pnpm test || npm test pnpm build || npm run build ``` If adding new configs or environment variables, document them here. ## Screenshots/Recordings If UI changes, add before/after screenshots or short clips. ## Breaking changes - [ ] Yes - [ ] No If yes, describe impact and migration instructions. ## Related issues Link related issues and discussions. Example: Closes #123 ## Security considerations Note any security implications (auth, secrets, PII, sandboxing, etc.). ## 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

This was referenced Aug 4, 2026

refactor: generate OpenAPI JSON and docs.json #5650

Merged

feat: adds deprecated and Enterprise tags in api refs #5652

Closed

chore(docs): add OpenAPI bundler and Mintlify nav sync scripts #5838

Merged

This was referenced Aug 4, 2026

feat: adds missing endpoints to e2e api tests #5831

Merged

refactor(governance): allow editions to override governance route families #5839

Merged

docs(openapi): add missing management endpoints and split governance specs #5840

Merged

impoiler force-pushed the 08-04-docs_governance_api_migration_guide branch from 3b629b7 to 97f1ff0 Compare August 4, 2026 10:53

impoiler force-pushed the 08-04-docs_openapi_spec_sources branch from dd7877c to 5e508f4 Compare August 4, 2026 10:53

impoiler force-pushed the 08-04-docs_governance_api_migration_guide branch 2 times, most recently from 68496ca to 41bd12f Compare August 4, 2026 12:35

impoiler force-pushed the 08-04-docs_openapi_spec_sources branch from 5e508f4 to f59b1d2 Compare August 4, 2026 13:38

impoiler force-pushed the 08-04-docs_governance_api_migration_guide branch from 41bd12f to 712fdf6 Compare August 4, 2026 13:38

impoiler self-assigned this Aug 4, 2026

impoiler force-pushed the 08-04-docs_openapi_spec_sources branch from f59b1d2 to ac1fc2c Compare August 5, 2026 04:34

impoiler force-pushed the 08-04-docs_governance_api_migration_guide branch from 9e77e91 to 797ae14 Compare August 5, 2026 04:34

impoiler force-pushed the 08-04-docs_openapi_spec_sources branch from ac1fc2c to 8422527 Compare August 5, 2026 08:42

impoiler force-pushed the 08-04-docs_governance_api_migration_guide branch from 797ae14 to 3f93378 Compare August 5, 2026 08:42

impoiler force-pushed the 08-04-docs_openapi_spec_sources branch from 8422527 to 35710da Compare August 5, 2026 12:21

impoiler force-pushed the 08-04-docs_governance_api_migration_guide branch from 3f93378 to 1cc1053 Compare August 5, 2026 12:21

impoiler force-pushed the 08-04-docs_openapi_spec_sources branch from 35710da to f971559 Compare August 6, 2026 11:38

impoiler force-pushed the 08-04-docs_governance_api_migration_guide branch from 1cc1053 to 12a193e Compare August 6, 2026 11:38

impoiler force-pushed the 08-04-docs_openapi_spec_sources branch from f971559 to c9d55ea Compare August 6, 2026 11:39

impoiler force-pushed the 08-04-docs_governance_api_migration_guide branch from 12a193e to 6a574ef Compare August 6, 2026 11:39

impoiler marked this pull request as ready for review August 6, 2026 11:40

coderabbitai Bot requested a review from BearTS August 6, 2026 11:41

coderabbitai Bot requested changes Aug 6, 2026

View reviewed changes

Comment thread docs/api/procuring-api-keys.mdx

Comment thread docs/migration-guides/governance-api-namespace.mdx

impoiler force-pushed the 08-04-docs_openapi_spec_sources branch from c9d55ea to f803676 Compare August 7, 2026 11:28

impoiler force-pushed the 08-04-docs_governance_api_migration_guide branch from 6a574ef to 2f5c167 Compare August 7, 2026 11:28

impoiler force-pushed the 08-04-docs_openapi_spec_sources branch from 7233e27 to af72e02 Compare August 10, 2026 13:29

impoiler force-pushed the 08-04-docs_governance_api_migration_guide branch 2 times, most recently from 8c67b4f to 73a9a9a Compare August 10, 2026 13:29

coderabbitai Bot requested a review from akshaydeo August 10, 2026 13:34

coderabbitai Bot requested changes Aug 10, 2026

View reviewed changes

Comment thread docs/api/procuring-api-keys_test.py

coderabbitai Bot previously approved these changes Aug 10, 2026

View reviewed changes

impoiler force-pushed the 08-04-docs_openapi_spec_sources branch from af72e02 to f914b44 Compare August 10, 2026 17:51

impoiler force-pushed the 08-04-docs_governance_api_migration_guide branch from 73a9a9a to 34b6a3f Compare August 10, 2026 17:51

impoiler added 6 commits August 11, 2026 09:48

feat: adds missing endpoints to e2e api tests

ac5f30f

chore(docs): add OpenAPI bundler and Mintlify nav sync scripts

a478273

refactor(governance): allow editions to override governance route fam…

5cd8ab8

…ilies

docs(openapi): add missing management endpoints and split governance …

87dbb74

…specs

docs: add governance API namespace migration guide

65d5475

chore: revert unintended go.mod/go.sum sonic bump

afdddb7

impoiler force-pushed the 08-04-docs_governance_api_migration_guide branch from 34b6a3f to afdddb7 Compare August 11, 2026 04:20

impoiler force-pushed the 08-04-docs_openapi_spec_sources branch from f914b44 to 87dbb74 Compare August 11, 2026 04:20

akshaydeo changed the base branch from 08-04-docs_openapi_spec_sources to graphite-base/5841 August 11, 2026 07:04

akshaydeo changed the base branch from graphite-base/5841 to dev August 11, 2026 07:05

akshaydeo requested a review from a team as a code owner August 11, 2026 07:05

akshaydeo merged commit 4fbc9cf into dev Aug 11, 2026
9 checks passed

akshaydeo deleted the 08-04-docs_governance_api_migration_guide branch August 11, 2026 07:05

coderabbitai Bot mentioned this pull request Aug 14, 2026

docs: migrate routing rules and complexity analyzer endpoints from /api/governance/* to /api/routing/* with deprecated legacy aliases #6147

Merged

18 tasks

coderabbitai Bot mentioned this pull request Aug 19, 2026

docs(migration): consolidate governance API namespace guide into v2.0.0 migration page #6332

Merged

18 tasks

Navigation Menu

Uh oh!

docs: add governance API namespace migration guide - #5841

docs: add governance API namespace migration guide#5841
akshaydeo merged 6 commits into
devfrom
08-04-docs_governance_api_migration_guide

impoiler commented Aug 4, 2026

Uh oh!

coderabbitai Bot commented Aug 4, 2026 •

edited

Loading

Summary by CodeRabbit

Walkthrough

Changes

❌ Failed checks (3 warnings)

Uh oh!

impoiler commented Aug 4, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 10, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

akshaydeo commented Aug 11, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

impoiler commented Aug 4, 2026

Summary

Changes

Type of change

Affected areas

How to test

Screenshots/Recordings

Breaking changes

Related issues

Security considerations

Checklist

Uh oh!

coderabbitai Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Walkthrough

Changes

❌ Failed checks (3 warnings)

Uh oh!

impoiler commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 10, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

akshaydeo commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coderabbitai Bot commented Aug 4, 2026 •

edited

Loading

impoiler commented Aug 4, 2026 •

edited

Loading

akshaydeo commented Aug 11, 2026 •

edited

Loading