What the agent does
The agent clones the repository into its own cloud sandbox and reads how routes are built before it adds a version anywhere. In a solution like jasontaylordev/CleanArchitecture, there are no controllers: src/Web/Infrastructure/WebApplicationExtensions.cs scans the assembly for classes that implement IEndpointGroup, calls app.MapGroup(routePrefix) with a default prefix of /api/{ClassName}, tags the group and invokes the class's static Map(RouteGroupBuilder). Four groups exist in src/Web/Endpoints/: TodoItems, TodoLists, WeatherForecasts and Users, the last of which calls MapIdentityApi<ApplicationUser>() and adds a logout route. EndpointRouteBuilderExtensions.cs wraps MapGet, MapPost, MapPut, MapPatch and MapDelete so each endpoint is named after its handler method, which becomes the OpenAPI operationId that the generated TypeScript clients depend on. Program.cs calls app.MapOpenApi() and app.MapScalarApiReference(), DependencyInjection.cs registers AddOpenApi with two operation transformers, the Angular client proxies /api, and Web.http exercises /api/WeatherForecasts and /api/TodoLists.
It adds the Asp.Versioning.Http package as a PackageVersion in Directory.Packages.props and an unversioned PackageReference in src/Web/Web.csproj, as central package management requires, and registers versioning in AddWebServices: AddApiVersioning with a default version of 1.0, AssumeDefaultVersionWhenUnspecified on, and ReportApiVersions so every response carries an api-supported-versions header. The version reader combines the URL segment and the api-version header, so existing callers that send nothing keep working. In WebApplicationExtensions.MapEndpoints it builds one ApiVersionSet with app.NewApiVersionSet().HasApiVersion(new ApiVersion(1, 0)).ReportApiVersions().Build(), changes the default prefix to /api/v{version:apiVersion}/{ClassName} and calls .WithApiVersionSet(versionSet) on each group, leaving IEndpointGroup.RoutePrefix as the override hook it already is.
Because Users maps the Identity endpoints, which clients and the login flow call at /api/Users/login and /api/Users/register, the agent gives that group an explicit RoutePrefix of /api/Users and leaves it outside the version set, and says why in the pull request. For the three versioned groups it keeps the old unversioned routes answering by mapping a second group with the previous prefix marked IsApiVersionNeutral() and a deprecation note in its OpenAPI description, so /api/TodoLists and /api/v1/TodoLists return the same thing until the clients move. It then updates Web.http, the Angular proxy.conf.js and web-api-client.ts base path, and the React client's equivalent, to the v1 paths, and adjusts the OpenAPI setup so the document lists the versioned routes under their version with the operationId values unchanged.
It runs dotnet build --configuration Release with the solution's TreatWarningsAsErrors, then dotnet test --no-build --configuration Release so tests/Application.FunctionalTests, which drive the API through Aspire.Hosting.Testing and Microsoft.AspNetCore.Mvc.Testing, prove the handlers still answer at the paths the tests use, and it updates those tests where they hard-code a route. Finally it starts the Web project in the sandbox, requests /api/v1/WeatherForecasts, /api/WeatherForecasts and the OpenAPI document, and records the status codes and the api-supported-versions header for the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add API versioning to the minimal API endpoints in this ASP.NET Core solution using Asp.Versioning. Read how endpoint groups are discovered and mapped first. Register versioning with a default of 1.0, assumed when the caller sends none, with versions reported in response headers. Put every endpoint group under /api/v{version}/... through one shared ApiVersionSet, keep the current unversioned routes answering as version-neutral with a deprecation note, and leave the Identity endpoints group at its current path. Keep every OpenAPI operationId unchanged, update the HTTP file, the client proxy settings and generated client base paths, build with warnings as errors, run the full test suite and open a pull request that lists each route before and after.",
"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 on its own branch that changes Directory.Packages.props, src/Web/Web.csproj, src/Web/DependencyInjection.cs, src/Web/Infrastructure/WebApplicationExtensions.cs, src/Web/Endpoints/Users.cs, src/Web/Web.http, the two client apps' base paths and any functional test that hard-coded a route. The description has a table of every route before and after, the dotnet build and dotnet test output from the sandbox, and the status codes and api-supported-versions header from the live requests it made against the running project.
The run's record keeps every command with its output, including the OpenAPI document it fetched, so a reviewer can check that operationId values did not move and that the unversioned routes still answer.
Before merging, a reviewer decides how long the version-neutral routes stay, whether the Identity group should join the version set in a later change, and when the first 2.0 endpoint will justify the scaffolding; the pull request shows where a second version slots in.
Run it on every Linear issue labelled api-change
In the console, an automation in the Project that has the repository, with a linear trigger on linear.issue.labeled and labels set to api-change, starts one run per issue with the issue as its context after the prompt; the saved prompt is the whole instruction and the trigger fills in no placeholder. The prompt asks the run to read the issue, make the endpoint change under the version the issue names, and keep the earlier version answering, so breaking changes land as a new version instead of a surprise.
From your own tracker, a handler sends one POST /o/{org}/sessions with this body, the repository in resources and a request_id that is a UUID v5 of the issue id, so a repeated webhook returns the run already started. Set a webhook URL on the API key and Rush posts run.completed with session_url when the pull request is up.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Versioning touches the route builder, the OpenAPI pipeline, two generated clients, an HTTP scratch file and the functional tests, and the mistakes are quiet: an operationId that changes and breaks the generated client, a login route that moves out from under the Angular app, a test that passes against the wrong path. The agent reads the discovery code first, keeps the names fixed by design, starts the project and makes the requests, so the pull request shows each route answering rather than asserting it.
The sandbox is its own computer with the .NET SDK from global.json and Node for the client apps, and every build, test and request stays in the run's record. Several services can be versioned at once in separate sandboxes, each ending in its own pull request with its own route table.
Frequently asked questions
Will existing clients break when this merges?
No. The default version is assumed when a caller sends none, and the old unversioned prefixes are mapped as version-neutral groups alongside the new v1 paths. The pull request marks them deprecated in the OpenAPI document so you can remove them once the clients are on v1.
Why are the Identity endpoints left out?
MapIdentityApi produces login, register, refresh and related routes that the client apps and the cookie flow call at their current paths, and they are framework-owned rather than application endpoints. Keeping them at /api/Users avoids changing authentication in the same pull request; moving them is a one-line change later.
Does the OpenAPI document still generate the same TypeScript client?
The operationId values come from handler method names through the repository's own MapGet and MapPost wrappers, and the agent does not touch those. Paths change to include v1, which the generated client's base path absorbs, and the agent regenerates nothing without asking.
How do I add version 2 of one endpoint afterwards?
Add HasApiVersion(new ApiVersion(2, 0)) to the shared version set, map the new handler in the same group with .MapToApiVersion(2.0), and leave the 1.0 handler in place. The pull request body shows this with the TodoLists group as the example.
More .NET jobs
The same job on other stacks
- Add API Versioning to a Vapor App (Vapor)
- Add API Versioning to an ASP.NET Core Web API (ASP.NET Core)
- Add API Versioning to a Django REST Framework Project from a Linear Issue (Django REST Framework)