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

# Hrizn Public API

> Programmatically create content, manage research, and access dealership data

## Welcome

The Hrizn Public API enables partners and integrators to build powerful automations around the Hrizn content platform. Create IdeaClouds, generate content, run compliance checks, manage inventory descriptions, and receive real-time webhook notifications.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get up and running in 5 minutes with your first API call.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Learn how to create and manage API keys.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Browse the full endpoint reference.
  </Card>

  <Card title="Webhooks" icon="bell" href="/webhooks">
    Receive real-time notifications when content is ready.
  </Card>
</CardGroup>

## Content Creation Pipeline

The API follows a research-first workflow. Every piece of content starts with an IdeaCloud that gathers questions and clusters them by intent, then flows through generation, quality checks, and enrichment.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    Keyword["Keyword / Topic"] --> IdeaCloud["POST /ideaclouds"]
    IdeaCloud --> Research["IdeaCloud researching..."]
    Research --> Content["POST /content"]
    Content --> Generate["Content generating..."]
    Generate --> HTML["GET /content/id/html"]
    Generate --> Components["GET /content/id/components"]
    Generate --> Compliance["POST /content/id/compliance"]
    Generate --> Tools["POST /content/id/content-tools"]
```

## Core Workflow

<Tabs>
  <Tab title="Quick Start">
    The fastest path from keyword to published content:

    <Steps>
      <Step title="Create an IdeaCloud">
        Send a keyword or topic to start research.

        <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 Chevrolet Silverado 1500 vs Ford F-150" }'
          ```

          ```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 Chevrolet Silverado 1500 vs Ford F-150"},
          )
          ```

          ```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 Chevrolet Silverado 1500 vs Ford F-150" }),
          });
          ```
        </CodeGroup>
      </Step>

      <Step title="Generate Content">
        Once the IdeaCloud is complete, create content from it.

        <CodeGroup>
          ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
          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": "...",
              "article_type": "comparison",
              "auto_compliance": true,
              "auto_content_tools": true
            }'
          ```

          ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
          response = requests.post(
              "https://api.app.hrizn.io/v1/public/content",
              headers={"X-API-Key": "hzk_your_key_here"},
              json={
                  "ideacloud_id": "...",
                  "article_type": "comparison",
                  "auto_compliance": True,
                  "auto_content_tools": True,
              },
          )
          ```

          ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
          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: "...",
              article_type: "comparison",
              auto_compliance: true,
              auto_content_tools: true,
            }),
          });
          ```
        </CodeGroup>
      </Step>

      <Step title="Retrieve the Content">
        Fetch the full HTML and structured components.

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        GET /content/{id}/html
        GET /content/{id}/components
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Full Workflow">
    A production integration typically adds webhooks, compliance, and content tools:

    <Steps>
      <Step title="Register Webhooks">
        Subscribe to `ideacloud.completed`, `content.progress`, and `content.completed` events so you don't have to poll.
      </Step>

      <Step title="Create an IdeaCloud">
        `POST /ideaclouds` returns `202 Accepted`. Wait for the `ideacloud.completed` webhook.
      </Step>

      <Step title="Generate Content">
        `POST /content` with `auto_compliance: true` and `auto_content_tools: true`. Monitor `content.progress` webhooks for real-time stage updates.
      </Step>

      <Step title="Handle Completion">
        When `content.completed` fires, retrieve `GET /content/{id}/html` for the article and `GET /content/{id}/components` for SEO metadata, schemas, and social snippets.
      </Step>

      <Step title="Publish">
        Push the HTML and structured data to your CMS. The components endpoint returns everything you need: body, meta title, meta description, JSON-LD, FAQs, and more.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Tip>
  Instead of polling for status, set up [webhooks](/webhooks) to receive push notifications when IdeaClouds and content are ready. This is the recommended approach for production integrations.
</Tip>

## Features

<CardGroup cols={2}>
  <Card title="IdeaClouds" icon="cloud">
    AI-powered keyword research with clustered questions and intent analysis.
  </Card>

  <Card title="Content Generation" icon="file-lines">
    6 content types including comparisons, model landing pages, Q\&A, and sales events.
  </Card>

  <Card title="Compliance Checks" icon="shield-check">
    OEM-specific compliance analysis with scoring and violation details.
  </Card>

  <Card title="Content Tools" icon="wrench">
    SEO metadata, JSON-LD schemas, FAQ markup, and social media snippets.
  </Card>

  <Card title="Inventory" icon="car">
    Vehicle data, AI-generated descriptions, and feed exports.
  </Card>

  <Card title="Webhooks" icon="bell">
    Real-time push notifications with HMAC-SHA256 signing and retry logic.
  </Card>

  <Card title="Rate Limiting" icon="gauge-high">
    Configurable per-key rate limits with sliding window enforcement.
  </Card>

  <Card title="Scoped Access" icon="lock">
    Granular permissions per API key with preset configurations.
  </Card>
</CardGroup>

<Prompt>
  You are integrating with the Hrizn Public API at `https://api.app.hrizn.io/v1/public`. The API uses `X-API-Key` header authentication. Write operations return `202 Accepted` and complete asynchronously — use webhooks for notifications. Content creation follows: IdeaCloud → Content → HTML/Components.
</Prompt>