Idempotency

Use Idempotency-Key on supported non-GET write requests when a network timeout could leave you unsure whether the request succeeded. Public routes enable idempotency by default unless they explicitly opt out, and the request must resolve to an organization.

When to use it

Send an idempotency key for create, update, and delete jobs that your system may retry automatically:

curl "https://app.promptingco.com/api/v1/content" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: $TPC_API_KEY" \
  -H "Idempotency-Key: content-sync-2026-04-30-pricing" \
  --data '{"productId":"product_123","pages":[{"slug":"pricing","title":"Pricing","content":"# Pricing"}]}'

Replay behavior

TPC keeps an idempotency reservation for 24 hours and caches successful (2xx) JSON responses within that window. Error responses and non-JSON responses are not cached.

Same key	Same route and method	Same body	Result
Yes	Yes	Yes	Cached response is replayed with `x-idempotent-replay: true`.
Yes	Yes	No	API returns `409 CONFLICT`.
Yes	Yes	Request still in progress	API returns `409 CONFLICT`.
Yes	No	Any body	Treated as a separate operation.

Keys are scoped to the organization, URL pathname, and method. The raw request body is hashed and compared on reuse, so changing JSON whitespace or property order can cause a conflict. Query parameters are not part of the key: use a different key for a different operation, even if only its query string changes. Use a non-empty key of at most 255 characters after trimming. Keep the same key and exact body for retries of one operation; choose a new key for each new operation.

Retry example

Generate and persist a unique key for the operation before calling this helper. Reuse it if your job restarts. This example retries network failures; handle HTTP errors such as 429 separately using the rate-limit guidance.

async function createPageWithRetry(productId: string, apiKey: string, key: string) {
  const body = {
    productId,
    pages: [
      {
        slug: "docs/retry-safe-page",
        title: "Retry-safe page",
        content: "# Retry-safe page",
      },
    ],
  };

  for (let attempt = 0; attempt < 3; attempt += 1) {
    try {
      const response = await fetch("https://app.promptingco.com/api/v1/content", {
        method: "POST",
        headers: {
          "content-type": "application/json",
          "x-api-key": apiKey,
          "Idempotency-Key": key,
        },
        body: JSON.stringify(body),
      });

      return await response.json();
    } catch (error) {
      if (attempt === 2) throw error;
    }
  }
}

Get started

Concepts

Content API

API Reference

Idempotency

Idempotency

When to use it

Replay behavior

Retry example

​Idempotency

​When to use it

​Replay behavior

​Retry example

Idempotency

When to use it

Replay behavior

Retry example