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

***

## List recommendations

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

**resource** `string` *required*

Must be `"knowledge-recommendations"`

**action** `string` *required*

Must be `"list"`

**data** `object`

**properties**

**status** `string` (default: pending)

Filter by recommendation status. One of `"pending"`, `"accepted"`, or `"dismissed"`.

**agentId** `string`

Filter to recommendations that apply to a specific genie — either directly agent-scoped or affecting a document attached to that genie.

**limit** `number` (default: 50)

Maximum number of results to return (1–200).

**userId** `string`

Admin only. Scope to another user's recommendations.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**recommendations** `array`

**item properties**

**id** `string`

Recommendation UUID.

**document\_id** `string | null`

UUID of the associated document, or `null`.

**agent\_id** `string | null`

UUID of the directly scoped genie, or `null` for account-level recommendations.

**kind** `string`

Recommendation type. Common values: `"source_changed"`, `"knowledge_gap"`, `"branded_doc"`.

**summary** `string`

Short summary of the recommendation.

**detail** `object`

Structured detail object. May include an `affected.agents` array listing genies impacted by the recommendation.

**status** `string`

Current status: `"pending"`, `"accepted"`, or `"dismissed"`.

**created\_at** `string`

ISO 8601 creation timestamp.

**resolved\_at** `string | null`

ISO 8601 timestamp when the recommendation was resolved, or `null`.

**documents** `object | null`

Source document summary, or `null` if no document is linked.

**properties**

**id** `string`

Document UUID.

**name** `string`

Document name.

**source\_type** `string`

Source type (e.g. `"url"`, `"file"`).

**source\_path** `string | null`

Original source path or URL, or `null`.

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

***

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

**resource** `string` *required*

Must be `"knowledge-recommendations"`

**action** `string` *required*

Must be `"accept"`

**data** `object`

**properties**

**recommendationId** `string` *required*

UUID of the recommendation to accept. Also accepted as the top-level `id` field.

**userId** `string`

Admin only. Act on behalf of another user.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**applied** `boolean`

Always `true` on success.

**refreshed** `boolean`

`true` when the document was automatically re-ingested (only for `source_changed` recommendations); `false` for acknowledgement-only accepts.

```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
  }
}
```

***

## Dismiss recommendation

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

**resource** `string` *required*

Must be `"knowledge-recommendations"`

**action** `string` *required*

Must be `"dismiss"`

**data** `object`

**properties**

**recommendationId** `string` *required*

UUID of the recommendation to dismiss. Also accepted as the top-level `id` field.

**userId** `string`

Admin only. Act on behalf of another user.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**dismissed** `boolean`

Always `true` on success.

```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 }
}
```

***

## Get settings

Returns the current knowledge watch mode for the authenticated user.

**resource** `string` *required*

Must be `"knowledge-recommendations"`

**action** `string` *required*

Must be `"get-settings"`

**data** `object`

**properties**

**userId** `string`

Admin only. Fetch settings for another user.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**watchMode** `string`

Current knowledge watch mode. One of `"notify"`, `"approve"`, or `"auto"`. Defaults to `"approve"` when not yet configured.

```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" }
}
```

***

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

**resource** `string` *required*

Must be `"knowledge-recommendations"`

**action** `string` *required*

Must be `"update-settings"`

**data** `object` *required*

**properties**

**watchMode** `string` *required*

New watch mode. Must be one of `"notify"`, `"approve"`, or `"auto"`.

**userId** `string`

Admin only. Update settings for another user.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**watchMode** `string`

The newly applied watch mode.

```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" }
}
```

***

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.