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 supported POST endpoints that trigger side effects:

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

External publication callback

POST /v1/public/content/{id}/posted uses current-state no-op behavior rather than an idempotency-key response cache. It does not support X-Idempotency-Key response caching, and authorization reruns on every call. Retrying the current posted_url is a no-op. A different URL replaces it while preserving the server-recorded first marked_posted_at. The last successfully applied update wins; there is no event version. Serialize corrections per content ID and stop superseded retries so an older URL cannot overwrite your latest correction. On 409 conflict from contention, retry only the latest intended payload. This is distinct from the idempotency_conflict response described below. See Mark content as externally posted for the request, tenant boundaries, and backfill workflow.

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

External publication callback

Key format

Conflict detection

Expiration

​How it works

​When to use it

​Supported Endpoints

​External publication callback

​Key format

​Conflict detection

​Expiration

How it works

When to use it

Supported Endpoints

External publication callback

Key format

Conflict detection

Expiration