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