Create IdeaCloud

Create IdeaCloud

curl --request POST \
  --url https://api.app.hrizn.io/v1/public/ideaclouds \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "keyword": "<string>",
  "category_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "suggestion_id": "<string>",
  "content_suggestion_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "external_fingerprint": "<string>"
}
'

import requests

url = "https://api.app.hrizn.io/v1/public/ideaclouds"

payload = {
    "keyword": "<string>",
    "category_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "suggestion_id": "<string>",
    "content_suggestion_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "external_fingerprint": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    keyword: '<string>',
    category_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    suggestion_id: '<string>',
    content_suggestion_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    external_fingerprint: '<string>'
  })
};

fetch('https://api.app.hrizn.io/v1/public/ideaclouds', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    keyword: '<string>',
    category_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    suggestion_id: '<string>',
    content_suggestion_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    external_fingerprint: '<string>'
  })
};

fetch('https://api.app.hrizn.io/v1/public/ideaclouds', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.app.hrizn.io/v1/public/ideaclouds",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'keyword' => '<string>',
    'category_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'suggestion_id' => '<string>',
    'content_suggestion_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'external_fingerprint' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "id": "bd72cd59-beda-4ce5-a9a1-20acf16c9a5d",
    "status": "researching",
    "keyword": "2026 Chevrolet Equinox EV range and features",
    "created_at": "2026-02-28T11:39:55.287Z",
    "message": "Generation typically completes within a few minutes. Configure webhooks to receive real-time status notifications: https://api-docs.hrizn.io/webhooks"
  }
}

POST

ideaclouds

Create IdeaCloud

curl --request POST \
  --url https://api.app.hrizn.io/v1/public/ideaclouds \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "keyword": "<string>",
  "category_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "suggestion_id": "<string>",
  "content_suggestion_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "external_fingerprint": "<string>"
}
'

import requests

url = "https://api.app.hrizn.io/v1/public/ideaclouds"

payload = {
    "keyword": "<string>",
    "category_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "suggestion_id": "<string>",
    "content_suggestion_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "external_fingerprint": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    keyword: '<string>',
    category_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    suggestion_id: '<string>',
    content_suggestion_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    external_fingerprint: '<string>'
  })
};

fetch('https://api.app.hrizn.io/v1/public/ideaclouds', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    keyword: '<string>',
    category_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    suggestion_id: '<string>',
    content_suggestion_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    external_fingerprint: '<string>'
  })
};

fetch('https://api.app.hrizn.io/v1/public/ideaclouds', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.app.hrizn.io/v1/public/ideaclouds",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'keyword' => '<string>',
    'category_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'suggestion_id' => '<string>',
    'content_suggestion_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'external_fingerprint' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "id": "bd72cd59-beda-4ce5-a9a1-20acf16c9a5d",
    "status": "researching",
    "keyword": "2026 Chevrolet Equinox EV range and features",
    "created_at": "2026-02-28T11:39:55.287Z",
    "message": "Generation typically completes within a few minutes. Configure webhooks to receive real-time status notifications: https://api-docs.hrizn.io/webhooks"
  }
}

Creates a new IdeaCloud that researches a keyword or topic, gathers questions from the web, clusters them by intent, and identifies the best angles for content. Scope required: ideaclouds:write

Request body

string

The keyword or topic to research (1–500 characters). Optional when creating from a suggestion id.

string

Optional category UUID to associate with this IdeaCloud.

string

Id from List create suggestions (e.g. content:… or fast_start:…). Consumes the suggestion so it will not reappear in the app or API.

string

Clarity content suggestion UUID (act-on path).

string

One of fast_start, se_ranking, gsc, ga4 — with external_fingerprint.

string

Stable fingerprint for external/Fast Start suppressions.

Response

Returns 202 Accepted with the IdeaCloud ID and initial status.

string

UUID of the created IdeaCloud.

string

Initial status: researching.

string

The keyword being researched.

string

ISO 8601 timestamp.

string

Informational message about async processing and webhook configuration.

{
  "data": {
    "id": "bd72cd59-beda-4ce5-a9a1-20acf16c9a5d",
    "status": "researching",
    "keyword": "2026 Chevrolet Equinox EV range and features",
    "created_at": "2026-02-28T11:39:55.287Z",
    "message": "Generation typically completes within a few minutes. Configure webhooks to receive real-time status notifications: https://api-docs.hrizn.io/webhooks"
  }
}

IdeaCloud research is asynchronous and typically completes within a few minutes. Configure webhooks to receive real-time ideacloud.completed and ideacloud.failed notifications instead of polling.

Authorizations

X-API-Key

string

header

required

Your Hrizn API key (prefix hzk_)

Body

application/json

keyword

string

Keyword or topic to research (optional when creating from a suggestion)

Required string length: 1 - 500

category_id

string<uuid>

Optional category UUID

suggestion_id

string

Id from GET /ideaclouds/create-suggestions

content_suggestion_id

string<uuid>

external_source

enum<string>

Available options:

fast_start,

se_ranking,

gsc,

ga4

external_fingerprint

string

Response

IdeaCloud created and research started

data

object

Hide child attributes

data.id

string<uuid>

data.status

enum<string>

IdeaCloud research status

Available options:

researching,

complete,

failed

data.keyword

string

data.created_at

string<date-time>

data.message

string

Informational message about async processing and webhook configuration

Last modified on July 26, 2026

Overview

IdeaClouds

Content Intelligence

Content

Content Types

Compliance

Content Tools

Inventory

Market

Site

Dealership Config

Social

Webhooks

Reference

Health

Analytics

IdeaClouds

Content

Compliance

Content Tools

Inventory

Market

Site

Webhooks

Content Intelligence

Reference

Social

Request body

Response

Authorizations

Body

Response

​Request body

​Response

Authorizations

Body

Response

Request body

Response