# Add Idempotency Keys to a Django REST Framework API

Yes. An agent adds an Idempotency-Key header to your POST APIs, stores each key's response per user, replays it on retry, refuses a changed body, and opens a PR.

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

## What the agent does

The agent reads how the APIs are built before it adds a header to them. In a project shaped like HackSoftware/Django-Styleguide-Example, `requirements/base.txt` pins `Django` 5.2.7, `djangorestframework` 3.16.1 and `drf-jwt` 1.19.2, and `requirements/local.txt` adds `pytest` 8.4.2 with `pytest-django`, `mypy` 1.18.2 with `django-stubs` and `djangorestframework-stubs`, and `ruff` 0.14.0. Every API is a plain `APIView` with nested `InputSerializer` and `OutputSerializer` classes that call a service: `UserCreateApi.post` in `styleguide_example/users/apis.py` validates `email` and `password` and calls `user_create`; `FileStandardUploadApi.post` in `styleguide_example/files/apis.py` answers `201` with the new file's id; `FileDirectUploadStartApi.post` returns presigned upload data. Authentication comes from `ApiAuthMixin` in `styleguide_example/api/mixins.py`, which accepts a session cookie, a `Session` header or a JWT and requires `IsAuthenticated`.

Two settings matter for how a retry behaves. `config/django/base.py` sets `DATABASES["default"]["ATOMIC_REQUESTS"] = True`, so each request is one transaction and a duplicate `POST` that fails halfway rolls back cleanly. `REST_FRAMEWORK["EXCEPTION_HANDLER"]` points at `drf_default_with_modifications_exception_handler` in `styleguide_example/api/exception_handlers.py`, which wraps every error in `{"detail": ...}`, so a new refusal has a shape to follow. `styleguide_example/common/models.py` gives every model `created_at` and `updated_at` through `BaseModel`, and `styleguide_example/api` is already a Django app with a `migrations` package, so the new table has a home.

The agent adds an `IdempotencyKey` model in `styleguide_example/api/models.py`: `key`, a foreign key to `users.BaseUser`, a `request_hash` of the method, path and body, the stored `response_status` and `response_body` as JSON, and a unique constraint on `(user, key)`. An `IdempotentPostMixin` in `styleguide_example/api/mixins.py` wraps `post`: with no `Idempotency-Key` header the view runs as before; with one, the mixin looks the key up for `request.user`, replays the stored status and body when the hash matches, answers `422` with `{"detail": "Idempotency-Key was used with a different request"}` when it does not, and otherwise runs the view and saves the response. A second request that arrives while the first is still inside its transaction hits the unique constraint on insert; the mixin catches that `IntegrityError` in a savepoint and answers `409` so the caller retries after the first finishes. The mixin goes on `UserCreateApi`, `FileStandardUploadApi` and `FileDirectUploadStartApi`, the three creates that a client is most likely to resend after a timeout.

Tests follow the repository's own style, `django.test.TestCase` with `APIClient` and `reverse("api:users:create")`, in `styleguide_example/api/tests/idempotency/`: the same key and body twice creates one user and returns the same body and status; the same key with another email is `422`; two different users may use the same key; no header keeps the old behaviour. A `cleanup_idempotency_keys` Celery task in `styleguide_example/api/tasks.py` deletes rows older than a day, registered through the existing `setup_periodic_tasks` command under `styleguide_example/tasks`, since the project already runs `django-celery-beat`. The agent runs `python manage.py makemigrations --check`, `pytest`, `ruff check .` and `mypy --config mypy.ini styleguide_example/`, the four commands `.github/workflows/django.yml` runs, and keeps their output.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add Idempotency-Key support to the POST APIs in this Django REST Framework project and open a pull request. Read requirements/base.txt, requirements/local.txt, config/django/base.py, styleguide_example/api/mixins.py, styleguide_example/api/exception_handlers.py, styleguide_example/users/apis.py, styleguide_example/files/apis.py, styleguide_example/common/models.py and styleguide_example/tasks/management/commands/setup_periodic_tasks.py first. Add an IdempotencyKey model in styleguide_example/api with key, user, request_hash, response_status, response_body and created_at, unique on user and key, with a migration. Add an IdempotentPostMixin beside ApiAuthMixin that replays a stored response when the key and hash match, answers 422 in the project's detail error shape when the body differs, answers 409 when the same key is in flight, and does nothing without the header. Apply it to UserCreateApi, FileStandardUploadApi and FileDirectUploadStartApi. Add a periodic Celery task that deletes keys older than a day. Write tests with APIClient covering replay, changed body, two users sharing a key and no header. Run python manage.py makemigrations --check, pytest, ruff check . and mypy --config mypy.ini styleguide_example/, and paste the output in the pull request.",
  "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 a new model and migration under `styleguide_example/api`, a mixin added to three API classes, a Celery task and its periodic registration, and a tests package. The description explains the three responses a client can get for a reused key, shows the `422` body in the project's `detail` shape, and pastes the `makemigrations --check`, `pytest`, `ruff` and `mypy` output.

The repository's `Django application` workflow runs the same four commands against a Postgres service on the pull request, so the checks a reviewer sees are the ones already configured, with the new tests included.

A reviewer checks that a request without the header is byte-for-byte unchanged, that stored response bodies never include anything the original response did not, that the hash covers the path so a key cannot replay one API's answer on another, and that the cleanup task's age matches how long their clients retry. They merge when the workflow is green.

## Run it on every API that clients retry after a timeout

A team with several Django services sends one `POST /o/{org}/sessions` per repository, with this prompt and the repository in `resources`. Each run reads that service's own `APIView` classes and applies the mixin to its creates, so each pull request names the endpoints it changed rather than a fixed list.

Pass a `request_id` on each call so a retried start returns the run already in progress, and give the key a `webhook_url` so `run.completed` arrives with `session_url` when the turn ends and your handler posts the pull request link to the channel that reviews backend changes.

## Why run it on Rush?

Idempotency is a correctness feature whose bugs only show under concurrency: two requests with the same key at the same moment, a replay across users, a key reused with a different body. In a Rush sandbox the agent runs the test suite against a real Postgres, including the savepoint path that catches the unique constraint, and keeps every command and result in the run's record beside the pull request.

Doing this by hand means touching a model, a migration, a mixin, three views, a Celery task and tests while keeping `mypy` with `django-stubs` happy. The agent makes the whole change in one pass with the repository's own checks, and a follow-up such as "also cover the password reset endpoint" wakes the parked sandbox and adds to the same branch.

## Frequently asked questions

### Why store the response instead of just the key?

Because a client that retries wants the answer it missed, not an error saying the work already happened. Storing `response_status` and `response_body` lets the mixin replay the original `201` with the same id, so the client's code path is the same whether or not the first attempt reached it.

### Why is the key scoped to the user?

Keys are chosen by clients, and two clients can pick the same UUID. The unique constraint is on `(user, key)`, and the lookup filters by `request.user`, so one caller can never read another caller's stored response. Views that allow anonymous requests are left out of this change.

### What happens if the first request is still running?

The second insert fails on the unique constraint inside a savepoint, so the outer `ATOMIC_REQUESTS` transaction survives, and the API answers `409` with a `detail` message asking the client to retry shortly. Once the first request commits, the retry replays its response.

### Does this change the endpoints without the header?

No. The mixin returns early when `Idempotency-Key` is absent, so existing clients see the same status codes and bodies. The tests include a case that sends two identical requests with no header and asserts two users are created, as before.

### How long are keys kept?

The pull request sets the cleanup task to delete rows older than a day, which covers the retry windows most HTTP clients use. The age is one constant in `styleguide_example/api/tasks.py`, and the period is a `django-celery-beat` schedule the reader can change in the admin.

## More Django REST Framework jobs

- [Add OpenAPI Docs to a Django REST Framework API](https://getrush.ai/run/add-openapi-docs/django-rest-framework/)
- [Add OpenTelemetry Tracing to a Django REST Framework API](https://getrush.ai/run/add-opentelemetry/django-rest-framework/)
- [Add a Password Change Endpoint to a Django REST Framework API from a Linear Issue](https://getrush.ai/run/add-password-change/django-rest-framework/)

## More jobs like this: Hand off a long task

- [Add Idempotency Keys to a Fiber API](https://getrush.ai/run/add-idempotency-middleware/fiber/)
- [Add ignoreDifferences to Argo CD Applications](https://getrush.ai/run/add-ignore-differences/argo-cd/)
- [Add Image Update Automation to a Flux Repository](https://getrush.ai/run/add-image-automation/flux/)

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