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

# Act on recommendation

> Link a recommendation to the article or IdeaCloud created from it

Marks a recommendation as acted on, linking it to the article or IdeaCloud research graph that was created based on the recommendation. This closes the feedback loop, letting the content intelligence pipeline know that the gap has been addressed.

**Scope required:** `content_intelligence:write`

## Path parameters

<ParamField path="id" type="string" required>UUID of the content intelligence recommendation.</ParamField>

## Request body

Provide exactly one target:

<ParamField body="article_id" type="string">UUID of the article that was created from this recommendation.</ParamField>
<ParamField body="research_graph_id" type="string">UUID of the IdeaCloud research graph that was created from this recommendation.</ParamField>

## Workflow

The typical workflow for acting on a recommendation:

<Steps>
  <Step title="List recommendations">
    Call `GET /content-intelligence` to find actionable recommendations.
  </Step>

  <Step title="Check the actionable_via field">
    Use `GET /reference/content-intelligence-types` to determine which endpoint to call based on `suggestion_type`. For example, `missing_model_page` maps to `POST /model-landing-pages`.
  </Step>

  <Step title="Create the content">
    Call the appropriate content or IdeaCloud creation endpoint. The response includes the new article or research graph `id`.
  </Step>

  <Step title="Link the recommendation">
    Call `POST /content-intelligence/{id}/act` with either `article_id` or `research_graph_id` to mark the recommendation as acted on.
  </Step>
</Steps>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "data": {
      "id": "c3a1f8b2-7e4d-4a9c-b5e6-1234567890ab",
      "status": "acted_on",
      "acted_on_article_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
      "acted_on_research_graph_id": null,
      "updated_at": "2026-03-02T10:30:00.000Z"
    }
  }
  ```
</ResponseExample>

<Note>
  Only active recommendations can be acted on. Attempting to act on a dismissed, expired, or already acted-on recommendation will return a 404 error.
</Note>


## OpenAPI

````yaml POST /content-intelligence/{id}/act
openapi: 3.1.0
info:
  title: Hrizn Public API
  version: 1.2.0
  description: >
    The Hrizn Public API allows partners to programmatically create content,
    manage inventory descriptions, and integrate with the Hrizn platform.


    All endpoints are prefixed with `/public` and require an API key passed via
    the `X-API-Key` header (except the health check).
  contact:
    email: support@hrizn.io
servers:
  - url: https://api.app.hrizn.io/v1/public
    description: Production
security:
  - apiKeyAuth: []
tags:
  - name: IdeaClouds
    description: Create and manage AI-powered keyword research
  - name: Content Intelligence
    description: AI-powered content gap analysis and recommendations
  - name: Content
    description: Generate content from IdeaClouds
  - name: Compliance
    description: Run OEM compliance checks on content
  - name: Content Tools
    description: Generate SEO metadata, schemas, and social snippets
  - name: Inventory
    description: Access vehicle data and AI descriptions
  - name: Site
    description: View dealership details and configuration
  - name: Webhooks
    description: Manage webhook subscriptions for real-time events
  - name: Reference
    description: Look up available types, scopes, and events
  - name: Social
    description: >-
      Zernio-backed social posting and reviews across all connected platforms
      (X, Facebook, Instagram, LinkedIn, Google Business Profile)
  - name: Health
    description: Health check (no authentication)
paths:
  /content-intelligence/{id}/act:
    post:
      tags:
        - Content Intelligence
      summary: Act on recommendation
      description: >-
        Marks a recommendation as acted on, linking it to the article or
        IdeaCloud research graph that was created from this recommendation.
      operationId: actOnContentIntelligence
      parameters:
        - $ref: '#/components/parameters/ContentIntelligenceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActOnContentIntelligenceInput'
      responses:
        '200':
          description: Recommendation marked as acted on
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentIntelligenceActedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    ContentIntelligenceId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Content intelligence recommendation ID
  schemas:
    ActOnContentIntelligenceInput:
      type: object
      oneOf:
        - required:
            - article_id
        - required:
            - research_graph_id
      properties:
        article_id:
          type: string
          format: uuid
          description: ID of the article created from this recommendation.
        research_graph_id:
          type: string
          format: uuid
          description: ID of the IdeaCloud research graph created from this recommendation.
    ContentIntelligenceActedResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              format: uuid
            status:
              type: string
              example: acted_on
            acted_on_article_id:
              type: string
              format: uuid
              nullable: true
            acted_on_research_graph_id:
              type: string
              format: uuid
              nullable: true
            updated_at:
              type: string
              format: date-time
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: validation_error
            message:
              type: string
              example: 'keyword: Required'
            details:
              type: object
            request_id:
              type: string
  responses:
    BadRequest:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: API key lacks required scope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your Hrizn API key (prefix hzk_)

````