ideaclouds:write

ideaclouds:write The ideaclouds:write scope allows you to create IdeaClouds, which triggers the AI-powered keyword research pipeline. You can create a single IdeaCloud or submit a batch of up to 25 at once.

Endpoints

Method	Path	Description
`POST`	`/public/ideaclouds`	Create a single IdeaCloud
`POST`	`/public/ideaclouds/batch`	Create IdeaClouds in batch

Create IdeaCloud

POST /public/ideaclouds

Creates a new IdeaCloud and begins the research process. The response returns immediately with a researching status. Use the Get IdeaCloud endpoint or the ideacloud.completed webhook to check when research finishes.

Request body

Field	Type	Required	Description
`keyword`	string	Yes	The keyword or topic to research (1-500 characters)
`category_id`	string (UUID)	No	Category to assign the IdeaCloud to

Example

curl -X POST https://api.app.hrizn.io/v1/public/ideaclouds \
  -H "X-API-Key: hzk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "2026 Honda Civic vs Toyota Corolla",
    "category_id": "c9d8e7f6-5432-1098-abcd-fedcba987654"
  }'

const res = await fetch("https://api.app.hrizn.io/v1/public/ideaclouds", {
  method: "POST",
  headers: {
    "X-API-Key": "hzk_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    keyword: "2026 Honda Civic vs Toyota Corolla",
    category_id: "c9d8e7f6-5432-1098-abcd-fedcba987654",
  }),
});
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"},
    json={
        "keyword": "2026 Honda Civic vs Toyota Corolla",
        "category_id": "c9d8e7f6-5432-1098-abcd-fedcba987654",
    },
)
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",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "keyword" => "2026 Honda Civic vs Toyota Corolla",
        "category_id" => "c9d8e7f6-5432-1098-abcd-fedcba987654",
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch));

Response — `202 Accepted`

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "researching",
    "keyword": "2026 Honda Civic vs Toyota Corolla",
    "created_at": "2026-02-01T14:30:00Z"
  }
}

Use the Idempotency-Key header to safely retry requests without creating duplicates. See Idempotency for details.

Status codes

Code	Description
`202`	IdeaCloud created and research started
`400`	Validation error (missing or invalid fields)
`401`	Missing or invalid API key
`403`	API key does not have `ideaclouds:write` scope
`429`	Rate limit exceeded
`500`	Internal server error

Create IdeaClouds in batch

POST /public/ideaclouds/batch

Creates multiple IdeaClouds in a single request. Each item in the batch is processed independently — if one fails, the others still succeed.

Request body

Field	Type	Required	Description
`items`	array	Yes	Array of IdeaCloud objects (1-25 items)
`items[].keyword`	string	Yes	The keyword or topic to research (1-500 characters)
`items[].category_id`	string (UUID)	No	Category to assign the IdeaCloud to

Example

curl -X POST https://api.app.hrizn.io/v1/public/ideaclouds/batch \
  -H "X-API-Key: hzk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "keyword": "2026 Honda Civic vs Toyota Corolla" },
      { "keyword": "best SUVs for families 2026", "category_id": "c9d8e7f6-5432-1098-abcd-fedcba987654" },
      { "keyword": "electric vehicle tax credits 2026" }
    ]
  }'

const res = await fetch("https://api.app.hrizn.io/v1/public/ideaclouds/batch", {
  method: "POST",
  headers: {
    "X-API-Key": "hzk_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [
      { keyword: "2026 Honda Civic vs Toyota Corolla" },
      { keyword: "best SUVs for families 2026", category_id: "c9d8e7f6-5432-1098-abcd-fedcba987654" },
      { keyword: "electric vehicle tax credits 2026" },
    ],
  }),
});
const data = await res.json();

import requests

response = requests.post(
    "https://api.app.hrizn.io/v1/public/ideaclouds/batch",
    headers={"X-API-Key": "hzk_your_key_here"},
    json={
        "items": [
            {"keyword": "2026 Honda Civic vs Toyota Corolla"},
            {"keyword": "best SUVs for families 2026", "category_id": "c9d8e7f6-5432-1098-abcd-fedcba987654"},
            {"keyword": "electric vehicle tax credits 2026"},
        ]
    },
)
data = response.json()

$ch = curl_init("https://api.app.hrizn.io/v1/public/ideaclouds/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" => [
            ["keyword" => "2026 Honda Civic vs Toyota Corolla"],
            ["keyword" => "best SUVs for families 2026", "category_id" => "c9d8e7f6-5432-1098-abcd-fedcba987654"],
            ["keyword" => "electric vehicle tax credits 2026"],
        ],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch));

Response — `202 Accepted`

{
  "data": {
    "items": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "keyword": "2026 Honda Civic vs Toyota Corolla",
        "status": "researching"
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "keyword": "best SUVs for families 2026",
        "status": "researching"
      },
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "keyword": "electric vehicle tax credits 2026",
        "status": "researching"
      }
    ]
  }
}

Response — partial failure

If some items fail, they are included in the response with status: "failed":

{
  "data": {
    "items": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "keyword": "2026 Honda Civic vs Toyota Corolla",
        "status": "researching"
      },
      {
        "keyword": "best SUVs for families 2026",
        "status": "failed",
        "error": "Failed to create IdeaCloud"
      }
    ]
  }
}

Failed items do not have an id field. Successful items always include id and status: "researching".

Status codes

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

Error response — Missing scope

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

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

Getting Started

Concepts

Guides

Scopes

Endpoints

Create IdeaCloud

Request body

Example

Response — `202 Accepted`

Status codes

Create IdeaClouds in batch

Request body

Example

Response — `202 Accepted`

Response — partial failure

Status codes

Error response — Missing scope

​Endpoints

​Create IdeaCloud

​Request body

​Example

​Response — 202 Accepted

​Status codes

​Create IdeaClouds in batch

​Request body

​Example

​Response — 202 Accepted

​Response — partial failure

​Status codes

​Error response — Missing scope

Endpoints

Create IdeaCloud

Request body

Example

Response — `202 Accepted`

Status codes

Create IdeaClouds in batch

Request body

Example

Response — `202 Accepted`

Response — partial failure

Status codes

Error response — Missing scope