# Add API Versioning to ASP.NET Core Minimal API Endpoints

Yes. An agent adds Asp.Versioning to your minimal API endpoint groups, keeps every current route answering as v1, wires the OpenAPI documents and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-api-versioning/dotnet/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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

- [Add Architecture Tests to a .NET Clean Architecture Solution](https://getrush.ai/run/add-architecture-tests/dotnet/)
- [Add Code Coverage to CI for a .NET Solution](https://getrush.ai/run/add-coverage-to-ci/dotnet/)
- [Add a Dev Container to a .NET Solution](https://getrush.ai/run/add-dev-containers/dotnet/)

## The same job on other stacks

- [Add API Versioning to a Vapor App](https://getrush.ai/run/add-api-versioning/vapor/)
- [Add API Versioning to an ASP.NET Core Web API](https://getrush.ai/run/add-api-versioning/aspnet-core/)
- [Add API Versioning to a Django REST Framework Project from a Linear Issue](https://getrush.ai/run/add-api-versioning/django-rest-framework/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
