# Add idempotency keys to mutating endpoints

Mutating endpoints that duplicate work on a retry, given idempotency keys with a replay test.

Category: API surface and contracts
Source: https://letsship.ai/use-cases/add-idempotency-keys
Published: 2026-08-25

## Goal

Add idempotency key support to mutating endpoints.

## Acceptance criteria

- A repeated request with the same key produces one effect
- The stored result is returned for the replay rather than an error
- Keys expire on a stated schedule
- A test replays a request and asserts a single effect

## What lands as proof

A replay test asserting exactly one effect from two identical calls, which is the whole promise.

## Prompt

Copy this to an agent to open the ticket:

```text
Create a Linear issue in my team and assign it to the SHIP agent.

Title: Add idempotency keys to {group}

Description: Add idempotency key support to mutating endpoints.

Acceptance criteria:
- A repeated request with the same key produces one effect
- The stored result is returned for the replay rather than an error
- Keys expire on a stated schedule
- A test replays a request and asserts a single effect

Before you create the issue, find mutating endpoints in this repository where a retry would duplicate work and replace {group} with them.
```

## Questions

### What does the agent actually change?

The ticket is scoped to one outcome: add idempotency key support to mutating endpoints. Work that serves that outcome is in scope, and anything outside it is left for a separate ticket, so the pull request stays reviewable.

### How do I know the work is done?

The pull request carries the evidence, not only the diff. Here that means replay test proving one effect from two identical calls, so a reviewer can confirm the result without reproducing the work locally.

### How much oversight does this need?

The run stops once the plan is written. Somebody reads the approach and approves it before any code exists, which is the cheapest moment to redirect the work.