> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.hrizn.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Safely retry requests without duplicate side effects

POST requests that create resources support idempotency keys to prevent duplicate operations when retrying failed requests.

## How it works

Include an `X-Idempotency-Key` header with a unique string (up to 256 characters). If the same key is sent again within 24 hours, the API returns the original response instead of creating a duplicate.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.app.hrizn.io/v1/public/ideaclouds \
    -H "X-API-Key: hzk_your_key_here" \
    -H "X-Idempotency-Key: create-ideacloud-2026-02-10-crv-review" \
    -H "Content-Type: application/json" \
    -d '{ "keyword": "2026 Chevrolet Equinox EV range" }'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch("https://api.app.hrizn.io/v1/public/ideaclouds", {
    method: "POST",
    headers: {
      "X-API-Key": "hzk_your_key_here",
      "X-Idempotency-Key": "create-ideacloud-2026-02-10-crv-review",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ keyword: "2026 Chevrolet Equinox EV range" }),
  });
  const data = await res.json();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      "https://api.app.hrizn.io/v1/public/ideaclouds",
      headers={
          "X-API-Key": "hzk_your_key_here",
          "X-Idempotency-Key": "create-ideacloud-2026-02-10-crv-review",
      },
      json={"keyword": "2026 Chevrolet Equinox EV range"},
  )
  data = response.json()
  ```

  ```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
  $ch = curl_init("https://api.app.hrizn.io/v1/public/ideaclouds");
  curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          "X-API-Key: hzk_your_key_here",
          "X-Idempotency-Key: create-ideacloud-2026-02-10-crv-review",
          "Content-Type: application/json",
      ],
      CURLOPT_POSTFIELDS => json_encode(["keyword" => "2026 Chevrolet Equinox EV range"]),
      CURLOPT_RETURNTRANSFER => true,
  ]);
  $data = json_decode(curl_exec($ch));
  ```
</CodeGroup>

## When to use it

Use idempotency keys on any POST request that triggers a side effect:

* Creating IdeaClouds
* Creating articles
* Triggering compliance checks
* Triggering content tools generation
* Triggering description generation

GET, PATCH, and DELETE requests are naturally idempotent and do not need this header.

## Supported Endpoints

<AccordionGroup>
  <Accordion title="IdeaClouds">
    * `POST /ideaclouds` — Create a single IdeaCloud
    * `POST /ideaclouds/batch` — Create up to 25 IdeaClouds
  </Accordion>

  <Accordion title="Content">
    * `POST /content` — Create a single article
    * `POST /content/batch` — Create up to 10 articles
    * `POST /content/{id}/generate` — Re-generate an article
  </Accordion>

  <Accordion title="Content Types">
    * `POST /content/comparison` — Create a comparison article
    * `POST /content/model-landing` — Create a model landing page
    * `POST /content/sales-event` — Create a sales event article
  </Accordion>

  <Accordion title="Quality & Inventory">
    * `POST /content/{id}/compliance` — Trigger compliance check
    * `POST /content/{id}/content-tools` — Generate content tools
    * `POST /inventory/{vin}/description` — Generate vehicle description
    * `POST /inventory/descriptions/batch` — Batch vehicle descriptions
  </Accordion>
</AccordionGroup>

## Key format

Use any string that uniquely identifies the intended operation. Common patterns:

| Pattern            | Example                                |
| ------------------ | -------------------------------------- |
| UUID               | `550e8400-e29b-41d4-a716-446655440000` |
| Action + timestamp | `create-article-2026-02-10T12:00:00Z`  |
| External reference | `dsrptv-order-12345`                   |

## Conflict detection

<Warning>
  If you reuse an idempotency key with **different request parameters**, the API returns `409 Conflict`. This prevents accidental misuse — each key is permanently bound to the first request's parameters.
</Warning>

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key reused with different parameters"
  }
}
```

## Expiration

<Note>
  Idempotency keys expire after **24 hours**. After that, the same key can be reused with any parameters.
</Note>