What the agent does
The agent reads how endpoints are registered before it chooses a versioning scheme. In an API shaped like jasontaylordev/CleanArchitecture, global.json pins the .NET SDK at 10.0.402, Directory.Packages.props manages every package version centrally (Microsoft.AspNetCore.OpenApi 10.0.13, Scalar.AspNetCore, NUnit, Shouldly, Moq), and src/Web/Program.cs calls MapOpenApi, MapScalarApiReference and MapEndpoints(typeof(Program).Assembly). That extension in src/Web/Infrastructure/WebApplicationExtensions.cs finds every IEndpointGroup, maps a group at /api/{ClassName} with a matching OpenAPI tag and calls its static Map(RouteGroupBuilder). The groups are TodoLists, TodoItems, WeatherForecasts and Users, the last wrapping MapIdentityApi, and EndpointRouteBuilderExtensions names each endpoint after its handler method so the Angular client in src/Web/ClientApp can be generated by nswag from wwwroot/openapi/v1.json. Nothing reads an API version.
The agent adds Asp.Versioning.Http to Directory.Packages.props and Web.csproj and, in AddWebServices in src/Web/DependencyInjection.cs, calls AddApiVersioning with a default version of 1.0, AssumeDefaultVersionWhenUnspecified, ReportApiVersions, and a reader that combines the api-version header and query string. It deliberately does not put the version in the URL: the generated Angular client, the React client under ClientApp-React and the /api entry in proxy.conf.js all call /api/TodoLists and /api/WeatherForecasts, and a URL segment would break every one of them. In MapEndpoints it builds one ApiVersionSet with NewApiVersionSet().HasApiVersion(1.0).ReportApiVersions().Build() and attaches it to each group with WithApiVersionSet, so every existing route answers version 1.0 unchanged and reports api-supported-versions on its responses. IEndpointGroup gains an optional static ApiVersions property so a future TodoLists v2 can declare itself without touching the extension.
The tests live where the repository already tests the Web project. tests/Application.FunctionalTests starts the app through DistributedApplicationTestingBuilder over TestAppHost, waits for the database and builds a WebApiFactory, a WebApplicationFactory<Program> that swaps IUser for a mock. The agent adds Web/ApiVersioningTests.cs there, using the factory's HttpClient: a request with api-version: 2.0 answers 400 with the UnsupportedApiVersion problem details before authorization runs, a request to /api/WeatherForecasts with no version and one with api-version: 1.0 carry api-supported-versions: 1.0, and the OpenAPI document at /openapi/v1.json still lists the same operation ids the nswag.json client depends on.
Before pushing, the agent runs what .github/workflows/build.yml runs: dotnet restore, dotnet build --no-restore --configuration Release and dotnet test --no-build --configuration Release, which includes the functional tests on the SQLite default the AppHost configures. It regenerates wwwroot/openapi/v1.json and diffs it to show the paths and operation ids are unchanged, and adds a paragraph on versioning to README.md.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "codex",
"input": "Add API versioning to this ASP.NET Core Minimal API and open a pull request. Read global.json, Directory.Packages.props, src/Web/Web.csproj, src/Web/Program.cs, src/Web/DependencyInjection.cs, src/Web/Infrastructure/WebApplicationExtensions.cs, src/Web/Infrastructure/IEndpointGroup.cs, src/Web/Infrastructure/EndpointRouteBuilderExtensions.cs, the files under src/Web/Endpoints, src/Web/ClientApp/nswag.json, src/Web/ClientApp/proxy.conf.js, tests/Application.FunctionalTests/FunctionalTestSetup.cs, tests/Application.FunctionalTests/Infrastructure/WebApiFactory.cs and .github/workflows/build.yml first. Add Asp.Versioning.Http through central package management. In AddWebServices call AddApiVersioning with default version 1.0, AssumeDefaultVersionWhenUnspecified, ReportApiVersions, and a reader combining the api-version header and query string; do not version by URL segment, because the generated clients call /api/{Group}. In MapEndpoints build one ApiVersionSet with version 1.0 and attach it to every group with WithApiVersionSet; add an optional static ApiVersions property to IEndpointGroup for future versions. Add tests/Application.FunctionalTests/Web/ApiVersioningTests.cs using the WebApiFactory HttpClient: api-version 2.0 answers 400 with UnsupportedApiVersion, requests with no version and with 1.0 carry api-supported-versions, and /openapi/v1.json keeps the same operation ids. Run dotnet restore, dotnet build --no-restore --configuration Release and dotnet test --no-build --configuration Release, regenerate wwwroot/openapi/v1.json and show its diff, and paste the results in the pull request description. Add a versioning paragraph to README.md. Do not change any command, query or entity under src/Application or src/Domain.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request with Asp.Versioning.Http in Directory.Packages.props and Web.csproj, the AddApiVersioning call in DependencyInjection.cs, the version set in WebApplicationExtensions.cs, the new property on IEndpointGroup, ApiVersioningTests.cs under the functional tests, and a README paragraph. The description shows the restore, build and test output and an empty diff of wwwroot/openapi/v1.json paths and operation ids, which is the proof that the Angular and React clients need no regeneration.
The repository's Build workflow runs on the pull request: restore, Release build and dotnet test across the unit, integration, functional and acceptance projects, with the Playwright browsers it installs for the acceptance tests.
A reviewer checks that no route pattern changed, that unversioned requests still succeed because the default is assumed, that the 400 for an unknown version happens before authorization so it carries no cookie requirement, and that MapIdentityApi under Users sits in the same version set. Then they plan the first v2 endpoint on the new ApiVersions property.
Run it on every new backend service
A team that builds several services from the same template starts one run per repository with POST /o/{org}/sessions, this prompt and the repository in resources. Each run reads that service's own endpoint groups and clients, so a service with no generated client can take URL segment versioning while one with an nswag client keeps header versioning, and each run ends in its own pull request.
The key's webhook_url receives run.completed for each run it starts, with a session_url for the result, so a script can post the pull request links to the team channel as they land.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Versioning is a change that is cheap to add and expensive to get wrong, because the clients that break are the ones you do not run locally. In a Rush sandbox the agent starts the app through the same Aspire test host the functional tests use, sends real requests with and without a version, regenerates the OpenAPI document and diffs it; every command and its output is kept in the run's transcript, so the pull request shows the clients are unaffected rather than asserting it.
The result passes the repository's own Release build and full test run before a reviewer opens it, and the choice of header over URL segment is written down with the reason. The same request works on every service built from the template, each in its own sandbox at the same time.
Frequently asked questions
Why version by header instead of /api/v1/…?
Because the Angular client is generated by nswag from wwwroot/openapi/v1.json, the React client and proxy.conf.js both address /api, and the Minimal API groups are mapped at /api/{ClassName}. A header or query reader with an assumed default keeps every existing URL valid, so no client needs a release on the same day.
Does it work with Minimal API groups and MapIdentityApi?
Yes. Asp.Versioning.Http adds NewApiVersionSet and WithApiVersionSet on route groups, and the Users group that calls MapIdentityApi is a group like the others, so its endpoints join the same version set and report the same api-supported-versions header.
What does an unsupported version return?
A 400 problem details response with the UnsupportedApiVersion code, produced during endpoint selection before the authorization requirement runs. The new functional test sends api-version: 2.0 through the WebApiFactory client and asserts exactly that.
How do I add a v2 of one endpoint later?
Declare the extra version on the group's ApiVersions property, map the new handler with MapToApiVersion(2.0) beside the existing one, and the header reader routes each request to the right handler at the same URL. The OpenAPI document can then be split per version as a separate change.