> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.hrizn.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ideaclouds:write

> Create IdeaClouds individually or in batch to start keyword research

<code>ideaclouds:write</code>

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](/scopes/ideaclouds-read#get-ideacloud-details) 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

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"
    }'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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()
  ```

  ```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
  $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));
  ```
</CodeGroup>

### Response — `202 Accepted`

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

<Tip>
  Use the `Idempotency-Key` header to safely retry requests without creating duplicates. See [Idempotency](/concepts/idempotency) for details.
</Tip>

### 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

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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" }
      ]
    }'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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()
  ```

  ```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
  $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));
  ```
</CodeGroup>

### Response — `202 Accepted`

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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"`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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"
      }
    ]
  }
}
```

<Note>
  Failed items do not have an `id` field. Successful items always include `id` and `status: "researching"`.
</Note>

### 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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "forbidden",
    "message": "This API key requires one of the following scopes: ideaclouds:write",
    "details": {
      "required_scopes": ["ideaclouds:write"]
    }
  }
}
```