Idempotency

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.

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" }'

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();

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()

$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));

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

IdeaClouds

POST /ideaclouds — Create a single IdeaCloud
POST /ideaclouds/batch — Create up to 25 IdeaClouds

Content

POST /content — Create a single article
POST /content/batch — Create up to 10 articles
POST /content/{id}/generate — Re-generate an article

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

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

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

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.

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key reused with different parameters"
  }
}

Expiration

Idempotency keys expire after 24 hours. After that, the same key can be reused with any parameters.

Getting Started

Concepts

Guides

Scopes

How it works

When to use it

Supported Endpoints

Key format

Conflict detection

Expiration

​How it works

​When to use it

​Supported Endpoints

​Key format

​Conflict detection

​Expiration

How it works

When to use it

Supported Endpoints

Key format

Conflict detection

Expiration