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

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.

string

required

Must be "knowledge-recommendations"

string

required

Must be "list"

object

Show properties

string

default:"pending"

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

string

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

number

default:"50"

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

string

Admin only. Scope to another user’s recommendations.

boolean

Whether the request succeeded.

object

Show properties

array

Show item properties

string

Recommendation UUID.

string | null

UUID of the associated document, or null.

string | null

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

string

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

string

Short summary of the recommendation.

object

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

string

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

string

ISO 8601 creation timestamp.

string | null

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

object | null

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

Show properties

string

Document UUID.

string

Document name.

string

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

string | null

Original source path or URL, or null.

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

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

{
  "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.

string

required

Must be "knowledge-recommendations"

string

required

Must be "accept"

object

Show properties

string

required

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

string

Admin only. Act on behalf of another user.

boolean

Whether the request succeeded.

object

Show properties

boolean

Always true on success.

boolean

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

const response = await ApiService.invoke(
  "knowledge-recommendations",
  "accept",
  undefined,
  { recommendationId: "rec-uuid-001" }
);
const { applied, refreshed } = response;

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

{
  "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.

string

required

Must be "knowledge-recommendations"

string

required

Must be "dismiss"

object

Show properties

string

required

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

string

Admin only. Act on behalf of another user.

boolean

Whether the request succeeded.

object

Show properties

boolean

Always true on success.

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

{
  "success": true,
  "data": { "dismissed": true }
}

Get settings

Returns the current knowledge watch mode for the authenticated user.

string

required

Must be "knowledge-recommendations"

string

required

Must be "get-settings"

object

Show properties

string

Admin only. Fetch settings for another user.

boolean

Whether the request succeeded.

object

Show properties

string

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

const response = await ApiService.invoke("knowledge-recommendations", "get-settings");
const { watchMode } = response;

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

{
  "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.

string

required

Must be "knowledge-recommendations"

string

required

Must be "update-settings"

object

required

Show properties

string

required

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

string

Admin only. Update settings for another user.

boolean

Whether the request succeeded.

object

Show properties

string

The newly applied watch mode.

const response = await ApiService.invoke(
  "knowledge-recommendations",
  "update-settings",
  undefined,
  { watchMode: "auto" }
);

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

{
  "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

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

Knowledge Recommendations

List recommendations

Accept recommendation

Dismiss recommendation

Get settings

Update settings

Error codes

​List recommendations

​Accept recommendation

​Dismiss recommendation

​Get settings

​Update settings

​Error codes

List recommendations

Accept recommendation

Dismiss recommendation

Get settings

Update settings

Error codes