content:write

content:write The content:write scope allows you to create content from completed IdeaClouds, re-trigger generation on existing IdeaCloud-linked content, and report where your integration has externally published content.

Endpoints

Method	Path	Description
`POST`	`/public/content`	Create a single content item
`POST`	`/public/content/batch`	Create content in batch
`POST`	`/public/content/{id}/generate`	Re-trigger body generation for existing IdeaCloud-linked content
`POST`	`/public/content/{id}/posted`	Record or correct the externally published URL

Report external publication

Call POST /v1/public/content/{id}/posted after your integration publishes the page. This requires X-API-Key, content:write, and the API Access (API_ACCESS) plan entitlement. Use the Hrizn content UUID returned by create, not an external CMS, job, or IdeaCloud ID. Send only { "posted_url": "https://www.example.com/blog/hybrid-suv-guide" }. The URL is trimmed, must be absolute HTTP(S), must contain no credentials, and must be at most 4096 characters after trimming. Unknown body fields are rejected; site, customer, and actor IDs are never accepted. The key-associated site constrains both reads and conditional writes; missing and other-site content return the same 404 not_found. A successful 200 response contains data with id, posted_url, marked_posted_at, and publish_state: "published". The server records the first report time; retries and URL corrections preserve it. A retry with the current URL is a no-op. A different URL replaces it, and the last successfully applied update wins. Serialize corrections and stop superseded retries; no event version or X-Idempotency-Key response caching is supported. Authorization reruns on each call. Retry only the latest intended payload after a contention 409 conflict. The callback reuses the manual posted marker. It does not crawl, independently verify, or publish the page, and leaves generation, CMS publishing state, and telemetry unchanged. It does not add content to /content/published or unlock /content/{id}/publish-data. Backfill known content-ID/URL pairs with one request per pair; no scanning, batch, unpublish, or new MCP tools are provided. See Mark content as externally posted for an example and error handling, including validation (400), scope or plan denial (403), not found (404), contention (409), rate limiting (429), service unavailability (503), and unexpected failures (500).

Create content

POST /public/content

Creates new content from a completed IdeaCloud and starts generation immediately. Pass selected_question_ids to choose which questions to cover; otherwise the IdeaCloud’s recommended questions are used.

Request body

Field	Type	Required	Description
`ideacloud_id`	string (UUID)	Yes	The IdeaCloud to generate the content from
`article_type`	string	Yes	One of: `basic`, `qa`, `expert`, `modellanding`, `comparison`, `salesevent`, `enhancedcontent`
`selected_question_ids`	array of strings	No	Question IDs from the IdeaCloud (UUIDs or legacy `q-{timestamp}-{index}`). Defaults to recommended questions. See Get IdeaCloud questions.
`selected_staff`	array of UUIDs	For `qa`/`expert`	Staff element IDs from Get site staff. May instead be persisted with Update IdeaCloud settings. The first ID is used.
`brand_voice_id`	string	No	Brand voice ID to use for tone and style
`tone`	string	No	Text generation tone. Ignored when `brand_voice_id` is provided
`title`	string	No	Custom content title (max 500 chars)
`language`	string	No	Language for generated content. Default `English`
`content_intent`	string	No	Link distribution strategy: `fixed_ops` (service/parts), `variable` (sales/financing), or `general` (all). Default `general`
`content_depth`	string	No	One of `concise`, `steady`, `balanced`, `substantial`, or `in-depth`
`output_format`	string	No	`standard` or `visual`. Default `standard`
`visual_design_mode`	string	No	`template`, `custom`, or `user-template` when using visual output
`selected_template_id`	UUID	Conditional	Required when `visual_design_mode` is `user-template`
`target_geo_overrides`	array	No	Up to 50 `{ element_id, priority }` geography overrides
`auto_compliance`	boolean	No	Automatically run compliance check after generation. Default `false`
`auto_content_tools`	boolean	No	Automatically generate content tools after generation. Default `false`

For qa and expert, include selected_staff in the create request or save it first with PATCH /ideaclouds/{id}/settings. The base PATCH /ideaclouds/{id} path is not an endpoint.

Example

curl -X POST https://api.app.hrizn.io/v1/public/content \
  -H "X-API-Key: hzk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "ideacloud_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "article_type": "comparison",
    "selected_question_ids": [
      "q1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "q2b3c4d5-e6f7-8901-bcde-f12345678901"
    ],
    "auto_compliance": true,
    "auto_content_tools": true
  }'

const res = await fetch("https://api.app.hrizn.io/v1/public/content", {
  method: "POST",
  headers: {
    "X-API-Key": "hzk_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ideacloud_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    article_type: "comparison",
    selected_question_ids: [
      "q1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "q2b3c4d5-e6f7-8901-bcde-f12345678901",
    ],
    auto_compliance: true,
    auto_content_tools: true,
  }),
});
const data = await res.json();

import requests

response = requests.post(
    "https://api.app.hrizn.io/v1/public/content",
    headers={"X-API-Key": "hzk_your_key_here"},
    json={
        "ideacloud_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "article_type": "comparison",
        "selected_question_ids": [
            "q1a2b3c4-d5e6-7890-abcd-ef1234567890",
            "q2b3c4d5-e6f7-8901-bcde-f12345678901",
        ],
        "auto_compliance": True,
        "auto_content_tools": True,
    },
)
data = response.json()

$ch = curl_init("https://api.app.hrizn.io/v1/public/content");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: hzk_your_key_here",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "ideacloud_id" => "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "article_type" => "comparison",
        "selected_question_ids" => [
            "q1a2b3c4-d5e6-7890-abcd-ef1234567890",
            "q2b3c4d5-e6f7-8901-bcde-f12345678901",
        ],
        "auto_compliance" => true,
        "auto_content_tools" => true,
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch));

Response — `202 Accepted`

{
  "data": {
    "id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
    "status": "generating",
    "article_type": "comparison",
    "title": "2026 Honda Civic vs Toyota Corolla: Complete Comparison",
    "created_at": "2026-02-01T15:00:00Z"
  }
}

Status codes

Code	Description
`202`	Content created and generation started
`400`	Validation error, including missing or invalid `selected_staff` for `qa`/`expert`
`401`	Missing or invalid API key
`403`	API key does not have `content:write` scope
`404`	IdeaCloud not found
`429`	Rate limit exceeded
`500`	Internal server error

Create content in batch

POST /public/content/batch

Creates multiple content items in a single request. Each item is processed independently.

Request body

Field	Type	Required	Description
`items`	array	Yes	Array of content objects (1-10 items)

Each item accepts the same fields as the single Create content endpoint.

Example

curl -X POST https://api.app.hrizn.io/v1/public/content/batch \
  -H "X-API-Key: hzk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "ideacloud_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "article_type": "comparison",
        "auto_compliance": true
      },
      {
        "ideacloud_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "article_type": "basic",
        "auto_content_tools": true
      }
    ]
  }'

const res = await fetch("https://api.app.hrizn.io/v1/public/content/batch", {
  method: "POST",
  headers: {
    "X-API-Key": "hzk_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [
      {
        ideacloud_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        article_type: "comparison",
        auto_compliance: true,
      },
      {
        ideacloud_id: "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        article_type: "basic",
        auto_content_tools: true,
      },
    ],
  }),
});
const data = await res.json();

import requests

response = requests.post(
    "https://api.app.hrizn.io/v1/public/content/batch",
    headers={"X-API-Key": "hzk_your_key_here"},
    json={
        "items": [
            {
                "ideacloud_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "article_type": "comparison",
                "auto_compliance": True,
            },
            {
                "ideacloud_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
                "article_type": "basic",
                "auto_content_tools": True,
            },
        ],
    },
)
data = response.json()

$ch = curl_init("https://api.app.hrizn.io/v1/public/content/batch");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: hzk_your_key_here",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "items" => [
            [
                "ideacloud_id" => "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "article_type" => "comparison",
                "auto_compliance" => true,
            ],
            [
                "ideacloud_id" => "b2c3d4e5-f6a7-8901-bcde-f12345678901",
                "article_type" => "basic",
                "auto_content_tools" => true,
            ],
        ],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch));

Response — `202 Accepted`

{
  "data": {
    "items": [
      {
        "id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
        "status": "generating",
        "article_type": "comparison",
        "title": "2026 Honda Civic vs Toyota Corolla: Complete Comparison",
        "created_at": "2026-02-01T15:00:00Z"
      },
      {
        "id": "e5f6a7b8-c9d0-1234-ef01-56789abcdef0",
        "status": "generating",
        "article_type": "basic",
        "title": "Top 10 Family SUVs for 2026",
        "created_at": "2026-02-01T15:00:01Z"
      }
    ]
  }
}

Response — Partial failure

{
  "data": {
    "items": [
      {
        "id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
        "status": "generating",
        "article_type": "comparison",
        "title": "2026 Honda Civic vs Toyota Corolla",
        "created_at": "2026-02-01T15:00:00Z"
      },
      {
        "article_type": "basic",
        "status": "failed",
        "error": "Failed to create content"
      }
    ]
  }
}

Status codes

Code	Description
`202`	Batch accepted (check individual item statuses)
`400`	Validation error (empty array, exceeds 10 items, or invalid fields)
`401`	Missing or invalid API key
`403`	API key does not have `content:write` scope
`429`	Rate limit exceeded
`500`	Internal server error

Regenerate content

POST /public/content/{id}/generate

Re-triggers article body generation for content that is already linked to an IdeaCloud. Question selection is fixed at creation time — use Create content to choose questions. This endpoint accepts optional updates to title, brand voice, language, and content depth.

Path parameters

Name	Type	Required	Description
`id`	string (UUID)	Yes	Content ID to regenerate

Request body

Field	Type	Required	Description
`brand_voice_id`	string	No	Brand voice ID
`title`	string	No	Custom content title (max 500 chars)
`language`	string	No	Language for generated content
`content_depth`	string	No	Content depth preset (`concise`, `steady`, `balanced`, `substantial`, `in-depth`)

Example

curl -X POST https://api.app.hrizn.io/v1/public/content/d4e5f6a7-b8c9-0123-def0-456789abcdef/generate \
  -H "X-API-Key: hzk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_voice_id": "bv-premium-001",
    "title": "Honda Civic vs Toyota Corolla: Which Should You Buy?",
    "content_depth": "substantial"
  }'

const res = await fetch(
  "https://api.app.hrizn.io/v1/public/content/d4e5f6a7-b8c9-0123-def0-456789abcdef/generate",
  {
    method: "POST",
    headers: {
      "X-API-Key": "hzk_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      brand_voice_id: "bv-premium-001",
      title: "Honda Civic vs Toyota Corolla: Which Should You Buy?",
      content_depth: "substantial",
    }),
  }
);
const data = await res.json();

import requests

response = requests.post(
    "https://api.app.hrizn.io/v1/public/content/d4e5f6a7-b8c9-0123-def0-456789abcdef/generate",
    headers={"X-API-Key": "hzk_your_key_here"},
    json={
        "brand_voice_id": "bv-premium-001",
        "title": "Honda Civic vs Toyota Corolla: Which Should You Buy?",
        "content_depth": "substantial",
    },
)
data = response.json()

$ch = curl_init("https://api.app.hrizn.io/v1/public/content/d4e5f6a7-b8c9-0123-def0-456789abcdef/generate");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: hzk_your_key_here",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "brand_voice_id" => "bv-premium-001",
        "title" => "Honda Civic vs Toyota Corolla: Which Should You Buy?",
        "content_depth" => "substantial",
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch));

Response — `202 Accepted`

{
  "data": {
    "id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
    "status": "generating"
  }
}

Status codes

Code	Description
`202`	Generation started
`400`	Validation error or content not linked to an IdeaCloud
`401`	Missing or invalid API key
`403`	API key does not have `content:write` scope
`404`	Content not found
`500`	Internal server error

Error response — Missing scope

If your API key does not include content:write, any request to these endpoints returns:

{
  "error": {
    "code": "forbidden",
    "message": "This API key requires one of the following scopes: content:write",
    "details": {
      "required_scopes": ["content:write"]
    }
  }
}

Getting Started

Concepts

Guides

Scopes

Endpoints

Report external publication

Create content

Request body

Example

Response — `202 Accepted`

Status codes

Create content in batch

Request body

Example

Response — `202 Accepted`

Response — Partial failure

Status codes

Regenerate content

Path parameters

Request body

Example

Response — `202 Accepted`

Status codes

Error response — Missing scope

​Endpoints

​Report external publication

​Create content

​Request body

​Example

​Response — 202 Accepted

​Status codes

​Create content in batch

​Request body

​Example

​Response — 202 Accepted

​Response — Partial failure

​Status codes

​Regenerate content

​Path parameters

​Request body

​Example

​Response — 202 Accepted

​Status codes

​Error response — Missing scope

Endpoints

Report external publication

Create content

Request body

Example

Response — `202 Accepted`

Status codes

Create content in batch

Request body

Example

Response — `202 Accepted`

Response — Partial failure

Status codes

Regenerate content

Path parameters

Request body

Example

Response — `202 Accepted`

Status codes

Error response — Missing scope