# Add API Versioning to an ASP.NET Core Web API

Yes. An agent adds Asp.Versioning to your Minimal API endpoint groups with a default version so existing clients keep working, and opens a PR with the tests passing.

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

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

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

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

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

## More ASP.NET Core jobs

- [Add Test Coverage Reporting to ASP.NET Core CI](https://getrush.ai/run/add-coverage-to-ci/aspnet-core/)
- [Add CSV Export to an ASP.NET Core API](https://getrush.ai/run/add-csv-export/aspnet-core/)
- [Add Health Checks to an ASP.NET Core App from a Linear Issue](https://getrush.ai/run/add-health-checks/aspnet-core/)

## The same job on other stacks

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

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