What the agent does
The agent reads how the URL tree is built before it adds a version. In a project shaped like HackSoftware/Django-Styleguide-Example, config/urls.py includes styleguide_example.api.urls under api/ with the namespace api, and styleguide_example/api/urls.py includes authentication, users, errors, files and google-oauth2, each with its own namespace; authentication/urls.py nests session and jwt namespaces another level down. REST_FRAMEWORK in config/django/base.py sets an exception handler and a filter backend and no versioning class. Every URL is reached by name: test_user_login.py calls reverse("api:authentication:session:login"), reverse("api:authentication:jwt:login") and reverse("api:authentication:me"), and files/utils.py builds the local upload URL with reverse("api:files:upload:direct:local"). README.md documents the paths as /api/auth/jwt/login/ and /api/users/, and .github/workflows/django.yml runs ruff check, mypy --config mypy.ini styleguide_example/ and pytest against a Postgres service.
It picks the scheme that fits a project built on namespaces. REST_FRAMEWORK gains DEFAULT_VERSIONING_CLASS set to rest_framework.versioning.NamespaceVersioning, ALLOWED_VERSIONS of ["v1"] and DEFAULT_VERSION of v1. In config/urls.py the include moves to api/v1/ with the namespace v1 in place of api, so a request to /api/v1/users/ resolves inside the v1:users namespace and DRF reads request.version as v1 from the first namespace segment that is an allowed version. Nothing in styleguide_example/api/urls.py or the app-level urls.py files changes, because they only know their own namespace. The api/ prefix with no version is dropped rather than aliased, since DRF would answer it with the invalid-version error, and the README's path list is updated in the same commit.
Every reverse() follows the rename: the six calls in styleguide_example/authentication/tests/apis/test_user_login.py become v1:authentication:..., and styleguide_example/files/utils.py becomes v1:files:upload:direct:local. The agent also adds a styleguide_example/api/tests/test_versioning.py that fetches /api/v1/users/ with APIClient and asserts 200, fetches /api/users/ and asserts 404, and uses a tiny APIView subclass under a test-only URL to assert that request.version is v1, so the setting is covered rather than assumed. Where an API should behave differently in a later version, the pattern is if request.version == "v2" inside the view, and the agent writes that in a short section of README.md without inventing a v2.
Before it pushes, the agent runs what django.yml runs: ruff check ., mypy --config mypy.ini styleguide_example/ and pytest with config.django.test, against a Postgres it starts in the sandbox with the DATABASE_URL the Compose file uses. It also starts the server and requests /api/v1/auth/me/ and /api/auth/me/ with curl to show the first answers 403 for an anonymous user, as ApiAuthMixin requires, and the second answers 404, and pastes both in 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 this Django REST Framework project and open a pull request. Read config/urls.py, config/django/base.py, styleguide_example/api/urls.py, styleguide_example/authentication/urls.py, styleguide_example/authentication/tests/apis/test_user_login.py, styleguide_example/files/utils.py, README.md and .github/workflows/django.yml first. Set DEFAULT_VERSIONING_CLASS to rest_framework.versioning.NamespaceVersioning with ALLOWED_VERSIONS v1 and DEFAULT_VERSION v1 in REST_FRAMEWORK. Move the api include in config/urls.py to api/v1/ with the namespace v1 and drop the unversioned api/ prefix. Update every reverse() that starts with api: to v1:, including files/utils.py, and update the paths in README.md. Add styleguide_example/api/tests/test_versioning.py asserting /api/v1/users/ answers 200, /api/users/ answers 404 and request.version is v1 in a view. Add a short README section on branching on request.version for a future v2 without creating one. Run ruff check ., mypy --config mypy.ini styleguide_example/ and pytest against a Postgres as the workflow does, start the server and curl /api/v1/auth/me/ and /api/auth/me/, and paste the output in the pull request. Do not change any API's behaviour or any app-level urls.py.",
"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 that changes config/django/base.py (three keys in REST_FRAMEWORK), config/urls.py (the api/v1/ include with namespace v1), styleguide_example/authentication/tests/apis/test_user_login.py and styleguide_example/files/utils.py (the reverse() names), README.md, and adds styleguide_example/api/tests/test_versioning.py. The description lists every path that moved, old beside new, and pastes the ruff, mypy and pytest output and the two curl exchanges from the sandbox.
The Django application workflow runs the same three commands on the pull request in both of its jobs, the Docker Compose one and the Postgres service one, so the suite has passed with the moved routes before a reviewer opens it. The agent pushes one commit for the settings and URL change, one for the renamed reverses and new test, and one for the README.
A reviewer checks that no reverse("api: is left anywhere, which a grep in the description confirms, that request.version really reads v1 through the nested v1:authentication:session namespace, that the unversioned prefix answers 404 rather than a DRF version error, and that the README's curl examples use the new paths. Then they merge and tell API consumers the new prefix, since this change breaks the old one on purpose.
Run it on every Linear issue labelled agent
In the console, add an automation to the Project with this prompt and a linear trigger on linear.issue.labeled, filtered to the agent label and the team whose issues describe the API. When someone labels an issue such as "clients need a stable /api/v1 prefix before the mobile release", the trigger puts the issue after the prompt and the run reads any extra constraint, such as keeping a redirect, from the issue text. Only label changes made by a person fire the trigger; changes made by an app integration never do, and the automation starts at most max_runs_per_hour runs in an hour.
From your own server, the same body goes to POST /o/{org}/sessions with the repository in resources and the issue's URL beside it, read through your Linear connection, plus a request_id that is a UUID v5 of the issue id so a retried call does not open a second pull request for the same issue.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
A prefix change is trivial in one file and dangerous everywhere else: a reverse() in a utility module, a path in the README, a test that still resolves because the namespace happens to exist. In a Rush sandbox the agent runs the real suite against a real Postgres, greps for the old namespace, and requests both prefixes from a running server, with every command and its output kept in the transcript.
The result passes the repository's own lint, type-check and test jobs before a reviewer opens it, and the new test pins request.version so a later settings change cannot silently drop versioning. The same request works for any DRF project whose URLs are organised by namespace.
Frequently asked questions
Why NamespaceVersioning rather than URLPathVersioning?
The project already names every URL through nested namespaces and reaches them with reverse(). NamespaceVersioning reads the version from the resolver namespace, so one include in config/urls.py versions the whole tree and the app-level urls.py files stay as they are. URLPathVersioning would add a version kwarg to every reverse() instead.
Can the old /api/ paths keep working for a while?
Not with NamespaceVersioning and an allowed list, because a request that resolves under a namespace with no allowed version is answered with DRF's invalid-version error rather than served. If you need a grace period, say so in the issue and the agent adds a rewrite at your reverse proxy or a second include, and documents the trade-off.
Does request.version work through the nested namespaces?
Yes. DRF splits the resolver namespace on : and takes the first segment that is in ALLOWED_VERSIONS, so v1:authentication:session yields v1. The new test_versioning.py asserts exactly that from inside a view rather than trusting the documentation.
What changes for mypy and ruff?
Nothing in configuration. The mypy.ini plugins for Django and DRF type the new settings keys, and the new test module follows the import order ruff enforces through its isort rules. Both run in the workflow and in the sandbox before the pull request opens.