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

# Knowledge Recommendations

> Review, accept, dismiss, and configure automated knowledge base recommendations

Knowledge recommendations are tailored suggestions generated when the system detects that a genie's knowledge base may be out of date — for example when a source document has changed, a knowledge gap is identified, or a branded document needs regeneration.

<Note>
  Standard users manage their own recommendations. Admin users can act on behalf of another user by passing `userId` in `data`.
</Note>

***

## List recommendations

Returns pending (or filtered) knowledge recommendations for the authenticated user.

<ParamField body="resource" type="string" required>
  Must be `"knowledge-recommendations"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"list"`
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="status" type="string" default="pending">
      Filter by recommendation status. One of `"pending"`, `"accepted"`, or `"dismissed"`.
    </ParamField>

    <ParamField body="agentId" type="string">
      Filter to recommendations that apply to a specific genie — either directly agent-scoped or affecting a document attached to that genie.
    </ParamField>

    <ParamField body="limit" type="number" default="50">
      Maximum number of results to return (1–200).
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Scope to another user's recommendations.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="recommendations" type="array">
      <Expandable title="item properties">
        <ResponseField name="id" type="string">Recommendation UUID.</ResponseField>
        <ResponseField name="document_id" type="string | null">UUID of the associated document, or `null`.</ResponseField>
        <ResponseField name="agent_id" type="string | null">UUID of the directly scoped genie, or `null` for account-level recommendations.</ResponseField>

        <ResponseField name="kind" type="string">
          Recommendation type. Common values: `"source_changed"`, `"knowledge_gap"`, `"branded_doc"`.
        </ResponseField>

        <ResponseField name="summary" type="string">Short summary of the recommendation.</ResponseField>

        <ResponseField name="detail" type="object">
          Structured detail object. May include an `affected.agents` array listing genies impacted by the recommendation.
        </ResponseField>

        <ResponseField name="status" type="string">Current status: `"pending"`, `"accepted"`, or `"dismissed"`.</ResponseField>
        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
        <ResponseField name="resolved_at" type="string | null">ISO 8601 timestamp when the recommendation was resolved, or `null`.</ResponseField>

        <ResponseField name="documents" type="object | null">
          Source document summary, or `null` if no document is linked.

          <Expandable title="properties">
            <ResponseField name="id" type="string">Document UUID.</ResponseField>
            <ResponseField name="name" type="string">Document name.</ResponseField>
            <ResponseField name="source_type" type="string">Source type (e.g. `"url"`, `"file"`).</ResponseField>
            <ResponseField name="source_path" type="string | null">Original source path or URL, or `null`.</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("knowledge-recommendations", "list", undefined, {
    status: "pending",
    agentId: "550e8400-e29b-41d4-a716-446655440000",
  });
  const { recommendations } = response;
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "knowledge-recommendations",
      "action": "list",
      "data": { "status": "pending" }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "recommendations": [
        {
          "id": "rec-uuid-001",
          "document_id": "doc-uuid-001",
          "agent_id": null,
          "kind": "source_changed",
          "summary": "The source page for 'Product FAQ' has been updated",
          "detail": {
            "affected": {
              "agents": [
                { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Support Bot" }
              ]
            }
          },
          "status": "pending",
          "created_at": "2024-01-15T10:30:00.000Z",
          "resolved_at": null,
          "documents": {
            "id": "doc-uuid-001",
            "name": "Product FAQ",
            "source_type": "url",
            "source_path": "https://example.com/faq"
          }
        }
      ]
    }
  }
  ```
</CodeGroup>

***

## Accept recommendation

Accepts a pending recommendation. For `source_changed` recommendations, this re-ingests the updated document automatically. For other kinds (knowledge gaps, branded docs), accepting marks the item as acknowledged — the owner applies the change manually.

<ParamField body="resource" type="string" required>
  Must be `"knowledge-recommendations"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"accept"`
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="recommendationId" type="string" required>
      UUID of the recommendation to accept. Also accepted as the top-level `id` field.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Act on behalf of another user.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="applied" type="boolean">Always `true` on success.</ResponseField>

    <ResponseField name="refreshed" type="boolean">
      `true` when the document was automatically re-ingested (only for `source_changed` recommendations); `false` for acknowledgement-only accepts.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "knowledge-recommendations",
    "accept",
    undefined,
    { recommendationId: "rec-uuid-001" }
  );
  const { applied, refreshed } = response;
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "knowledge-recommendations",
      "action": "accept",
      "data": { "recommendationId": "rec-uuid-001" }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "applied": true,
      "refreshed": true
    }
  }
  ```
</CodeGroup>

***

## Dismiss recommendation

Dismisses a pending recommendation without taking action. The recommendation moves to `"dismissed"` status and no longer appears in the default pending list.

<ParamField body="resource" type="string" required>
  Must be `"knowledge-recommendations"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"dismiss"`
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="recommendationId" type="string" required>
      UUID of the recommendation to dismiss. Also accepted as the top-level `id` field.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Act on behalf of another user.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="dismissed" type="boolean">Always `true` on success.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "knowledge-recommendations",
      "action": "dismiss",
      "data": { "recommendationId": "rec-uuid-001" }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": { "dismissed": true }
  }
  ```
</CodeGroup>

***

## Get settings

Returns the current knowledge watch mode for the authenticated user.

<ParamField body="resource" type="string" required>
  Must be `"knowledge-recommendations"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"get-settings"`
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="userId" type="string">
      Admin only. Fetch settings for another user.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="watchMode" type="string">
      Current knowledge watch mode. One of `"notify"`, `"approve"`, or `"auto"`. Defaults to `"approve"` when not yet configured.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("knowledge-recommendations", "get-settings");
  const { watchMode } = response;
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{"resource": "knowledge-recommendations", "action": "get-settings"}'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": { "watchMode": "approve" }
  }
  ```
</CodeGroup>

***

## Update settings

Updates the knowledge watch mode for the authenticated user.

| Mode      | Behaviour                                                                |
| --------- | ------------------------------------------------------------------------ |
| `notify`  | The system notifies you about changes but takes no action.               |
| `approve` | Recommendations are surfaced for your review before anything is applied. |
| `auto`    | Changes are applied automatically without requiring manual approval.     |

<ParamField body="resource" type="string" required>
  Must be `"knowledge-recommendations"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"update-settings"`
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="watchMode" type="string" required>
      New watch mode. Must be one of `"notify"`, `"approve"`, or `"auto"`.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Update settings for another user.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="watchMode" type="string">The newly applied watch mode.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "knowledge-recommendations",
    "update-settings",
    undefined,
    { watchMode: "auto" }
  );
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "knowledge-recommendations",
      "action": "update-settings",
      "data": { "watchMode": "auto" }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": { "watchMode": "auto" }
  }
  ```
</CodeGroup>

***

## Error codes

| Code               | Status | Description                                  |
| ------------------ | ------ | -------------------------------------------- |
| `UNAUTHORIZED`     | 401    | Missing or invalid token                     |
| `FORBIDDEN`        | 403    | User lacks required permissions              |
| `NOT_FOUND`        | 404    | Recommendation not found or already resolved |
| `VALIDATION_ERROR` | 400    | Invalid or missing parameters                |
| `INTERNAL_ERROR`   | 500    | Server error                                 |