# Activation Packs
Source: https://docs.helpgenie.ai/api-reference/activation-packs

Create and manage launch packs that bundle a genie or portal with promotional copy, branding, and distribution channels

Activation packs tie a genie or portal to a collection of launch assets: channel configuration, branding overrides, promotional copy, and generated marketing materials. When a pack is created, promotional copy for all templates is automatically generated in the background.

<Note>
  Standard users can only access their own activation packs. Admin users can access any user's packs by passing `adminMode: true` and `userId`.
</Note>

***

## List activation packs

Returns a paginated list of activation packs for the authenticated user.

<ParamField type="string">
  `activation-packs`
</ParamField>

<ParamField type="string">
  `list`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Filter to packs linked to a specific genie.
    </ParamField>

    <ParamField type="string">
      Filter to packs linked to a specific portal.
    </ParamField>

    <ParamField type="number">
      Results per page. Maximum 500.
    </ParamField>

    <ParamField type="number">
      Number of results to skip.
    </ParamField>

    <ParamField type="boolean">
      Admin only. Access packs belonging to another user.
    </ParamField>

    <ParamField type="string">
      Admin only. Target user ID when using `adminMode`.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="items" type="ActivationPack[]">
  Array of activation pack objects. See the `get` action for the full object shape.
</ResponseField>

<ResponseField name="count" type="number">
  Total number of matching packs.
</ResponseField>

<ResponseField name="limit" type="number">
  The limit that was applied.
</ResponseField>

<ResponseField name="offset" type="number">
  The offset that was applied.
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activation-packs",
    action: "list",
    data: {
      agent_id: "genie-uuid",
      limit: 20,
      offset: 0,
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activation-packs \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "list",
      "data": {
        "agent_id": "genie-uuid",
        "limit": 20,
        "offset": 0
      }
    }'
  ```
</CodeGroup>

***

## Get activation pack

Retrieves a single activation pack by ID, including nested genie and portal data.

<ParamField type="string">
  `activation-packs`
</ParamField>

<ParamField type="string">
  `get`
</ParamField>

<ParamField type="string">
  The activation pack UUID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      Admin only. Fetch a pack owned by another user.
    </ParamField>

    <ParamField type="string">
      Admin only. Target user ID when using `adminMode`.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="activationPack" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">Pack UUID.</ResponseField>
    <ResponseField name="name" type="string">Pack name.</ResponseField>
    <ResponseField name="description" type="string | null">Pack description.</ResponseField>
    <ResponseField name="agent_id" type="string | null">Linked genie UUID, or `null` if linked to a portal.</ResponseField>
    <ResponseField name="portal_id" type="string | null">Linked portal UUID, or `null` if linked to a genie.</ResponseField>

    <ResponseField name="channels" type="object">
      Enabled distribution channels. Boolean flags for `web_widget`, `phone`, `sms`, `whatsapp`, and similar channels.
    </ResponseField>

    <ResponseField name="branding_overrides" type="object | null">
      Optional branding overrides applied on top of the linked genie or portal branding.
    </ResponseField>

    <ResponseField name="asset_config" type="object | null">
      Configuration for generated marketing assets (QR codes, banners, etc.).
    </ResponseField>

    <ResponseField name="generated_assets" type="object | null">
      Results of the most recent asset generation run.
    </ResponseField>

    <ResponseField name="promo_content" type="object | null">
      Generated promotional copy, keyed by template then tone. For example `promo_content.launch_email.friendly.body`.
    </ResponseField>

    <ResponseField name="touchpoints" type="object | null">
      Distribution touchpoint configuration.
    </ResponseField>

    <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
    <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>

    <ResponseField name="agent" type="object | null">
      Nested genie data, present when `agent_id` is set.

      <Expandable title="properties">
        <ResponseField name="id" type="string">Genie ID.</ResponseField>
        <ResponseField name="name" type="string">Genie name.</ResponseField>
        <ResponseField name="branding" type="object | null">Genie branding configuration.</ResponseField>
        <ResponseField name="page" type="object | null">Public page info. Contains `url_name`.</ResponseField>
        <ResponseField name="phone" type="object | null">Phone number info. Contains `phone_number`.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="portal" type="object | null">
      Nested portal data, present when `portal_id` is set.

      <Expandable title="properties">
        <ResponseField name="id" type="string">Portal ID.</ResponseField>
        <ResponseField name="name" type="string">Portal name.</ResponseField>
        <ResponseField name="slug" type="string">Portal URL slug.</ResponseField>
        <ResponseField name="branding" type="object | null">Portal branding configuration.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activation-packs",
    action: "get",
    id: "pack-uuid",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activation-packs \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "get",
      "id": "pack-uuid"
    }'
  ```
</CodeGroup>

***

## Create activation pack

Creates a new activation pack linked to a genie or portal. After creation, promotional copy for all templates is generated automatically in the background.

<ParamField type="string">
  `activation-packs`
</ParamField>

<ParamField type="string">
  `create`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Pack display name.
    </ParamField>

    <ParamField type="string">
      Link this pack to a specific genie. Either `agent_id` or `portal_id` should be provided.
    </ParamField>

    <ParamField type="string">
      Link this pack to a specific portal. Either `agent_id` or `portal_id` should be provided.
    </ParamField>

    <ParamField type="string">
      Pack description.
    </ParamField>

    <ParamField type="object">
      Distribution channel flags. For example `{ "web_widget": true, "phone": false }`.
    </ParamField>

    <ParamField type="object">
      Branding values that override the linked genie or portal branding.
    </ParamField>

    <ParamField type="object">
      Configuration for marketing asset generation.
    </ParamField>

    <ParamField type="object">
      Distribution touchpoint configuration.
    </ParamField>

    <ParamField type="string">
      Base URL used when generating promotional copy. Defaults to `"https://helpgenie.ai"`. Not persisted to the pack.
    </ParamField>

    <ParamField type="boolean">
      Admin only. Create on behalf of another user.
    </ParamField>

    <ParamField type="string">
      Admin only. Target user ID when using `adminMode`.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="activationPack" type="object">
  The newly created pack. See the `get` action for the full object shape.
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activation-packs",
    action: "create",
    data: {
      name: "Summer Launch",
      agent_id: "genie-uuid",
      description: "Launch pack for our summer campaign",
      channels: {
        web_widget: true,
        phone: true,
        sms: false,
      },
      baseUrl: "https://mycompany.com",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activation-packs \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "create",
      "data": {
        "name": "Summer Launch",
        "agent_id": "genie-uuid",
        "channels": { "web_widget": true, "phone": true },
        "baseUrl": "https://mycompany.com"
      }
    }'
  ```
</CodeGroup>

<Note>
  Creating a pack triggers background generation of promotional copy for all five templates at their default tones. By the time you navigate to the pack detail, copy is usually ready.
</Note>

***

## Update activation pack

Updates fields on an existing activation pack. Only provided fields are written; omitted fields remain unchanged.

<ParamField type="string">
  `activation-packs`
</ParamField>

<ParamField type="string">
  `update`
</ParamField>

<ParamField type="string">
  The activation pack UUID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">Updated pack name.</ParamField>
    <ParamField type="string">Updated description.</ParamField>
    <ParamField type="string">Link to a different genie. Exactly one of `agent_id` or `portal_id` must remain set after the update.</ParamField>
    <ParamField type="string">Link to a different portal. Exactly one of `agent_id` or `portal_id` must remain set after the update.</ParamField>
    <ParamField type="object">Updated channel flags.</ParamField>
    <ParamField type="object">Updated branding overrides.</ParamField>
    <ParamField type="object">Updated asset configuration.</ParamField>
    <ParamField type="object">Updated print-kit configuration (copy used on printed materials).</ParamField>
    <ParamField type="object">Updated touchpoints.</ParamField>
    <ParamField type="object">Updated promo content map.</ParamField>

    <ParamField type="object">
      Publish completed generated assets back to the pack. **Must be sent in isolation** — no other fields may be included in the same request. Requires the three revision tokens below.
    </ParamField>

    <ParamField type="string">
      UUID of the pack revision the asset build was started against. Required when publishing `generated_assets`.
    </ParamField>

    <ParamField type="string">
      UUID of the asset-cache revision the build expected to replace. Required when publishing `generated_assets`.
    </ParamField>

    <ParamField type="string">
      New UUID to stamp the published asset cache with. Required when publishing `generated_assets`. Must differ from `expectedAssetCacheRevision`.
    </ParamField>

    <ParamField type="boolean">Admin only.</ParamField>
    <ParamField type="string">Admin only. Target user ID.</ParamField>
  </Expandable>
</ParamField>

<Note>
  Changing `name`, `description`, `agent_id`, `portal_id`, `channels`, `branding_overrides`, `asset_config`, `print_kit`, or `touchpoints` automatically clears the pack's cached generated assets so stale artwork is never served. Changing `name`, `description`, `agent_id`, or `portal_id` also clears `promo_content`.
</Note>

<ResponseField name="activationPack" type="object">
  The updated pack object.
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activation-packs",
    action: "update",
    id: "pack-uuid",
    data: {
      name: "Summer Launch v2",
      channels: { web_widget: true, phone: true, sms: true },
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activation-packs \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "update",
      "id": "pack-uuid",
      "data": {
        "name": "Summer Launch v2",
        "channels": { "web_widget": true, "phone": true, "sms": true }
      }
    }'
  ```

  ```bash cURL (publish generated assets) theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activation-packs \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "update",
      "id": "pack-uuid",
      "data": {
        "generated_assets": { "qr_code": "...", "banner": "..." },
        "expectedAssetInputRevision": "aaaaaaaa-0000-0000-0000-000000000001",
        "expectedAssetCacheRevision": "bbbbbbbb-0000-0000-0000-000000000002",
        "nextAssetCacheRevision": "cccccccc-0000-0000-0000-000000000003"
      }
    }'
  ```
</CodeGroup>

***

## Delete activation pack

Permanently deletes an activation pack.

<ParamField type="string">
  `activation-packs`
</ParamField>

<ParamField type="string">
  `delete`
</ParamField>

<ParamField type="string">
  The activation pack UUID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">Admin only.</ParamField>
    <ParamField type="string">Admin only. Target user ID.</ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  `true` when the pack was deleted.
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activation-packs",
    action: "delete",
    id: "pack-uuid",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activation-packs \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "delete",
      "id": "pack-uuid"
    }'
  ```
</CodeGroup>

<Warning>
  This action is permanent and cannot be undone.
</Warning>

***

## Generate assets

Triggers the asset generation workflow for an activation pack (QR codes, banners, and other visual materials). The actual generation is performed client-side by the asset generation workflow after this endpoint confirms the pack exists.

<ParamField type="string">
  `activation-packs`
</ParamField>

<ParamField type="string">
  `generate-assets`
</ParamField>

<ParamField type="string">
  The activation pack UUID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">Admin only.</ParamField>
    <ParamField type="string">Admin only. Target user ID.</ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  `true` when the pack was found and the asset generation signal was sent.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="activationPackId" type="string">
  The pack ID that should receive the generated assets.
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activation-packs",
    action: "generate-assets",
    id: "pack-uuid",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activation-packs \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "generate-assets",
      "id": "pack-uuid"
    }'
  ```
</CodeGroup>

***

## Generate promotional copy

Generates a single piece of promotional copy for an activation pack and persists it to the pack's `promo_content` field. Use this to regenerate a specific template/tone combination on demand.

<ParamField type="string">
  `activation-packs`
</ParamField>

<ParamField type="string">
  `generate-promo`
</ParamField>

<ParamField type="string">
  The activation pack UUID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The promotional template to generate. One of:

      * `launch_email` — 90–140 word customer-facing launch email body
      * `social_post` — LinkedIn-ready post (70–110 words)
      * `customer_sms` — SMS message (160 characters or fewer)
      * `team_announcement` — Internal staff announcement (100–160 words)
      * `website_banner` — Two-line homepage banner headline + supporting copy
    </ParamField>

    <ParamField type="string">
      Copy tone. One of `professional`, `friendly`, `punchy`. Default varies by template (`friendly` for most, `professional` for team announcements, `punchy` for banners).
    </ParamField>

    <ParamField type="string">
      URL included in the generated copy for readers to act on. Defaults to `"https://helpgenie.ai"`.
    </ParamField>

    <ParamField type="boolean">Admin only.</ParamField>
    <ParamField type="string">Admin only. Target user ID.</ParamField>
  </Expandable>
</ParamField>

<ResponseField name="template" type="string">
  The template that was generated.
</ResponseField>

<ResponseField name="tone" type="string">
  The tone that was used.
</ResponseField>

<ResponseField name="content" type="object">
  The generated copy.

  <Expandable title="properties">
    <ResponseField name="body" type="string">
      The main copy body.
    </ResponseField>

    <ResponseField name="subject" type="string">
      Email subject line. Present only for `launch_email` and `team_announcement` templates.
    </ResponseField>

    <ResponseField name="generated_at" type="string">
      ISO 8601 timestamp of when the copy was generated.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activation-packs",
    action: "generate-promo",
    id: "pack-uuid",
    data: {
      template: "launch_email",
      tone: "friendly",
      targetUrl: "https://mycompany.com/chat",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activation-packs \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "generate-promo",
      "id": "pack-uuid",
      "data": {
        "template": "launch_email",
        "tone": "friendly",
        "targetUrl": "https://mycompany.com/chat"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "template": "launch_email",
      "tone": "friendly",
      "content": {
        "subject": "Say hello to our new smart assistant",
        "body": "We have some exciting news to share. We have just launched a new assistant that is available 24/7 to answer your questions about our products and services...",
        "generated_at": "2024-06-26T10:00:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

<Note>
  Generated copy is automatically persisted to the pack's `promo_content` field under `promo_content[template][tone]`. Subsequent requests for the same template/tone overwrite the stored copy.
</Note>

***

## Error responses

| Status | Code               | Description                                                                                                                                |
| ------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 400    | `VALIDATION_ERROR` | Missing required fields (e.g. pack ID, template, revision tokens) or invalid combinations (e.g. `generated_assets` sent with other fields) |
| 403    | `FORBIDDEN`        | Non-admin user attempted to target another user                                                                                            |
| 404    | `NOT_FOUND`        | Activation pack or activation target not found                                                                                             |
| 409    | `CONFLICT`         | Asset publish failed because the pack was modified while its artwork was being built. Rebuild from the latest pack version.                |
| 500    | `INTERNAL_ERROR`   | Server error, including copy generation failure                                                                                            |


# Activities
Source: https://docs.helpgenie.ai/api-reference/activities

Query and create audit log entries that track user and system actions

## List activities

Retrieves a paginated, filterable list of activity log entries. Standard users see only their own activities. Admin users see all activities and can filter by user.

<ParamField type="string">
  `activities`
</ParamField>

<ParamField type="string">
  `all`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Maximum number of records to return. Defaults to `50`.
    </ParamField>

    <ParamField type="number">
      Number of records to skip for pagination. Defaults to `0`.
    </ParamField>

    <ParamField type="boolean">
      Admin only. When `true`, returns activities for all users.
    </ParamField>

    <ParamField type="string">
      Admin only. Filter activities to a specific user.
    </ParamField>

    <ParamField type="object">
      Optional filter criteria.

      <Expandable title="properties">
        <ParamField type="string">
          Filter by activity category.
        </ParamField>

        <ParamField type="string">
          Filter by activity type.
        </ParamField>

        <ParamField type="string">
          Filter by action performed.
        </ParamField>

        <ParamField type="string[]">
          Array of action values to exclude from results (e.g. `["viewed"]`).
        </ParamField>

        <ParamField type="string">
          ISO 8601 timestamp. Return activities created on or after this date.
        </ParamField>

        <ParamField type="string">
          ISO 8601 timestamp. Return activities created on or before this date.
        </ParamField>

        <ParamField type="string">
          Filter by the type of resource the activity relates to.
        </ParamField>

        <ParamField type="string">
          Filter by the ID of the resource the activity relates to.
        </ParamField>

        <ParamField type="string">
          Search term. Matches against the activity title, description, and resource name.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Common enum values

The following tables list the most commonly used values for the filter and data fields. These are not exhaustive -- custom values may appear as new features are added.

**`activity_type` values**

| Value          | Description                                          |
| -------------- | ---------------------------------------------------- |
| `genie`        | Actions related to genie (agent) management          |
| `document`     | Knowledge base document operations                   |
| `user`         | User account and profile changes                     |
| `team`         | Team membership and settings changes                 |
| `conversation` | Conversation lifecycle events                        |
| `system`       | System-generated events (billing, maintenance, etc.) |

**`action` values**

| Value      | Description                       |
| ---------- | --------------------------------- |
| `created`  | A resource was created            |
| `updated`  | A resource was modified           |
| `deleted`  | A resource was removed            |
| `viewed`   | A resource was accessed or opened |
| `exported` | Data was exported                 |
| `imported` | Data was imported                 |

**`category` values**

| Value                  | Description                                         |
| ---------------------- | --------------------------------------------------- |
| `agent_management`     | Genie creation, configuration, and deployment       |
| `knowledge_management` | Document uploads, processing, and organization      |
| `user_management`      | User invitations, role changes, and profile updates |
| `team_management`      | Team creation, member additions, and settings       |
| `conversation`         | Conversation syncing, analysis, and review          |

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activities",
    action: "all",
    data: {
      limit: 20,
      offset: 0,
      filters: {
        category: "agent_management",
        activityType: "genie",
        action: "created",
        startDate: "2025-01-01T00:00:00Z",
        endDate: "2025-12-31T23:59:59Z",
        searchTerm: "created",
      },
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activities \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "activities",
      "action": "all",
      "data": {
        "limit": 20,
        "offset": 0,
        "filters": {
          "category": "agent_management",
          "activityType": "genie",
          "action": "created",
          "startDate": "2025-01-01T00:00:00Z",
          "endDate": "2025-12-31T23:59:59Z"
        }
      }
    }'
  ```
</CodeGroup>

### Response

<ResponseField name="activities" type="Activity[]">
  Array of activity records.

  <Expandable title="Activity object">
    <ResponseField name="id" type="string">
      Unique activity identifier.
    </ResponseField>

    <ResponseField name="activity_type" type="string">
      The type of activity (e.g., `genie`, `document`, `system`).
    </ResponseField>

    <ResponseField name="action" type="string">
      The action performed (e.g., `created`, `updated`, `deleted`).
    </ResponseField>

    <ResponseField name="title" type="string">
      Human-readable title describing the activity.
    </ResponseField>

    <ResponseField name="category" type="string | null">
      Activity category for grouping.
    </ResponseField>

    <ResponseField name="description" type="string | null">
      Detailed description of the activity.
    </ResponseField>

    <ResponseField name="status" type="string | null">
      Activity status.
    </ResponseField>

    <ResponseField name="priority" type="string | null">
      Activity priority level.
    </ResponseField>

    <ResponseField name="resource_type" type="string | null">
      The type of resource this activity relates to.
    </ResponseField>

    <ResponseField name="resource_id" type="string | null">
      The ID of the related resource.
    </ResponseField>

    <ResponseField name="resource_name" type="string | null">
      The name of the related resource.
    </ResponseField>

    <ResponseField name="duration_ms" type="number | null">
      Duration of the activity in milliseconds, if applicable.
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Arbitrary metadata associated with the activity.
    </ResponseField>

    <ResponseField name="session_id" type="string | null">
      Session identifier for grouping related activities.
    </ResponseField>

    <ResponseField name="user_id" type="string | null">
      ID of the user who performed the activity.
    </ResponseField>

    <ResponseField name="is_visible" type="boolean | null">
      Whether the activity is visible in the UI.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the activity was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="number">
  Total number of matching activities.
</ResponseField>

<ResponseField name="limit" type="number">
  The limit that was applied.
</ResponseField>

<ResponseField name="offset" type="number">
  The offset that was applied.
</ResponseField>

***

## Get activity

Retrieves a single activity record by ID. Standard users can only access their own activities.

<ParamField type="string">
  `activities`
</ParamField>

<ParamField type="string">
  `get`
</ParamField>

<ParamField type="string">
  The activity ID.
</ParamField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activities",
    action: "get",
    id: "activity-uuid",
  });
  ```
</CodeGroup>

### Response

<ResponseField name="activity" type="Activity">
  The requested activity object. See [Activity object](#list-activities) for field details.
</ResponseField>

***

## Create activity

Creates a new activity record. Restricted to admin users and service-role callers.

<ParamField type="string">
  `activities`
</ParamField>

<ParamField type="string">
  `create`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The type of activity.
    </ParamField>

    <ParamField type="string">
      The action that was performed.
    </ParamField>

    <ParamField type="string">
      Human-readable title for the activity.
    </ParamField>

    <ParamField type="string">
      Activity category.
    </ParamField>

    <ParamField type="string">
      Detailed description.
    </ParamField>

    <ParamField type="string">
      Activity status.
    </ParamField>

    <ParamField type="string">
      Priority level.
    </ParamField>

    <ParamField type="string">
      Type of the related resource.
    </ParamField>

    <ParamField type="string">
      ID of the related resource.
    </ParamField>

    <ParamField type="string">
      Name of the related resource.
    </ParamField>

    <ParamField type="number">
      Duration in milliseconds.
    </ParamField>

    <ParamField type="object">
      Arbitrary metadata.
    </ParamField>

    <ParamField type="string">
      Session identifier for grouping.
    </ParamField>

    <ParamField type="string">
      User ID to attribute the activity to. Defaults to the authenticated user.
    </ParamField>

    <ParamField type="boolean">
      Whether the activity should be visible in the UI.
    </ParamField>
  </Expandable>
</ParamField>

<Note>
  Only admin users (`internal_*` role) and service-role callers can create activities. Standard users receive a `403 FORBIDDEN` error.
</Note>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activities",
    action: "create",
    data: {
      activity_type: "genie",
      action: "created",
      title: "New genie created: Sales Assistant",
      resource_type: "agent",
      resource_id: "agent-uuid",
      resource_name: "Sales Assistant",
      metadata: {
        voice_id: "voice-id",
      },
    },
  });
  ```
</CodeGroup>

### Response (status 201)

<ResponseField name="activity" type="Activity">
  The newly created activity object.
</ResponseField>

***

## Forbidden actions

The `update` and `delete` actions are not permitted on activities. All callers -- including admin users -- receive a `403 FORBIDDEN` error.

<CodeGroup>
  ```typescript Update (forbidden) theme={null}
  // Returns 403 FORBIDDEN
  const response = await ApiService.invoke({
    resource: "activities",
    action: "update",
    id: "activity-uuid",
    data: { title: "Updated title" },
  });
  ```

  ```typescript Delete (forbidden) theme={null}
  // Returns 403 FORBIDDEN
  const response = await ApiService.invoke({
    resource: "activities",
    action: "delete",
    id: "activity-uuid",
  });
  ```
</CodeGroup>

<Warning>
  Activity records are immutable once created. The `update` and `delete` actions return `403 FORBIDDEN` for **all** callers, including admin users and service-role tokens. This is by design -- audit logs must remain tamper-proof. If you need to correct an activity, create a new compensating entry instead.
</Warning>


# Agent mailboxes
Source: https://docs.helpgenie.ai/api-reference/agent-mailboxes

Admin management of genie email inbox provisioning state

`agent-mailboxes` is an admin-only resource for monitoring and managing the email inbox attached to each genie. Every genie that has email reception enabled gets a provisioned mailbox entry; this resource lets admins view the full mailbox roster and suspend, resume, or deprovision individual mailboxes.

<Warning>
  All actions on this resource require an internal admin account. Requests from non-admin users are rejected with `403 Forbidden`.
</Warning>

***

## List all mailboxes

Returns every genie mailbox across all users, joined with the owning genie and user details.

<ParamField type="string">
  Must be `"agent-mailboxes"`
</ParamField>

<ParamField type="string">
  Must be `"all"`
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="mailboxes" type="array">
      <Expandable title="item properties">
        <ResponseField name="id" type="string">Mailbox UUID.</ResponseField>
        <ResponseField name="agent_id" type="string">UUID of the genie this mailbox belongs to.</ResponseField>
        <ResponseField name="agent_name" type="string | null">Display name of the owning genie.</ResponseField>
        <ResponseField name="user_id" type="string | null">User ID of the genie owner.</ResponseField>
        <ResponseField name="user_email" type="string | null">Email address of the genie owner.</ResponseField>
        <ResponseField name="user_name" type="string | null">Full name of the genie owner.</ResponseField>
        <ResponseField name="email_address" type="string">The provisioned mailbox email address.</ResponseField>
        <ResponseField name="account_id" type="string | null">Internal account reference used by the mail system, or `null` if not yet provisioned.</ResponseField>
        <ResponseField name="grant_id" type="string | null">OAuth grant identifier for the mailbox connection, or `null`.</ResponseField>

        <ResponseField name="status" type="string">
          Current provisioning status. One of `"provisioned"`, `"suspended"`, or `"unavailable"`.
        </ResponseField>

        <ResponseField name="last_error" type="string | null">Most recent provisioning error message, or `null` if healthy.</ResponseField>
        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
        <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number">Total number of mailboxes returned.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("agent-mailboxes", "all");
  const { mailboxes, count } = response;
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_ADMIN_KEY" \
    -H "Content-Type: application/json" \
    -d '{"resource": "agent-mailboxes", "action": "all"}'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "mailboxes": [
        {
          "id": "mbx-uuid-001",
          "agent_id": "550e8400-e29b-41d4-a716-446655440000",
          "agent_name": "Support Genie",
          "user_id": "usr-uuid-456",
          "user_email": "owner@example.com",
          "user_name": "Jane Smith",
          "email_address": "support-genie@mail.helpgenie.ai",
          "account_id": "acct-abc123",
          "grant_id": "grant-xyz789",
          "status": "provisioned",
          "last_error": null,
          "created_at": "2024-01-10T08:00:00.000Z",
          "updated_at": "2024-01-10T08:00:00.000Z"
        }
      ],
      "count": 1
    }
  }
  ```
</CodeGroup>

***

## Update mailbox

Suspends or resumes a mailbox and/or updates the escalation address. At least one field (`action` or `escalation_address`) must be provided.

<ParamField type="string">
  Must be `"agent-mailboxes"`
</ParamField>

<ParamField type="string">
  Must be `"update"`
</ParamField>

<ParamField type="string">
  The mailbox UUID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Lifecycle transition. Must be `"suspend"` or `"resume"`. Omit to leave the current status unchanged.
    </ParamField>

    <ParamField type="string | null">
      Fallback email address for unhandled messages. Must be a valid email address, or `null` to clear the current value. Omit this key entirely to leave it unchanged.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="ok" type="boolean">
      `true` when the update was applied successfully.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  // Suspend a mailbox
  await ApiService.invoke("agent-mailboxes", "update", "mbx-uuid-001", {
    action: "suspend",
  });

  // Update escalation address only
  await ApiService.invoke("agent-mailboxes", "update", "mbx-uuid-001", {
    escalation_address: "oncall@example.com",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_ADMIN_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "agent-mailboxes",
      "action": "update",
      "id": "mbx-uuid-001",
      "data": { "action": "suspend" }
    }'
  ```

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

***

## Delete mailbox

Deprovisions a mailbox and marks it as `"unavailable"`. After deletion, the genie creation flow will not automatically re-provision the mailbox.

<ParamField type="string">
  Must be `"agent-mailboxes"`
</ParamField>

<ParamField type="string">
  Must be `"delete"`
</ParamField>

<ParamField type="string">
  The mailbox UUID.
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="ok" type="boolean">
      `true` when the mailbox was successfully deprovisioned.
    </ResponseField>
  </Expandable>
</ResponseField>

<Warning>
  This action deprovisions the mailbox in the mail system and removes the local mailbox record. It does not delete the underlying genie. The action is idempotent if the mailbox is already absent in the mail system (a `404` from the mail system is treated as success). The next update to the genie will automatically re-provision a fresh mailbox.
</Warning>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  await ApiService.invoke("agent-mailboxes", "delete", "mbx-uuid-001");
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_ADMIN_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "agent-mailboxes",
      "action": "delete",
      "id": "mbx-uuid-001"
    }'
  ```

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

***

## Error codes

| Code               | Status | Description                                                         |
| ------------------ | ------ | ------------------------------------------------------------------- |
| `FORBIDDEN`        | 403    | Caller is not an internal admin                                     |
| `NOT_FOUND`        | 404    | Mailbox not found                                                   |
| `VALIDATION_ERROR` | 400    | Missing ID, no valid update fields, or invalid `escalation_address` |
| `INVALID_ACTION`   | 400    | Unknown action                                                      |
| `INTERNAL_ERROR`   | 500    | Mail system error or local sync failure                             |


# Genie mailbox (self)
Source: https://docs.helpgenie.ai/api-reference/agent-mailboxes-self

Owner-facing provisioning and management of your genie's email inbox

`agent-mailboxes-self` is the owner-facing surface for managing the email inbox attached to your own genie. Every action is scoped to the caller's genie — you can only manage mailboxes you own.

<Note>
  To read the current mailbox state you can use either this resource's `get` action (documented below) or the `genies` resource (`get` or `all` action), which includes a `mailbox` field in every full genie response.
</Note>

***

## Get mailbox

Returns the current mailbox record for a genie you own. Use this to check provisioning status, retrieve the mailbox email address, or detect errors after provisioning.

<ParamField type="string">
  Must be `"agent-mailboxes-self"`
</ParamField>

<ParamField type="string">
  Must be `"get"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      UUID of the genie whose mailbox to retrieve.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  The mailbox record.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Mailbox UUID.</ResponseField>
    <ResponseField name="agent_id" type="string">UUID of the owning genie.</ResponseField>
    <ResponseField name="email_address" type="string">The provisioned mailbox email address.</ResponseField>
    <ResponseField name="account_id" type="string | null">Internal account reference used by the mail system, or `null` if provisioning is still in progress.</ResponseField>
    <ResponseField name="grant_id" type="string | null">Connection grant identifier, or `null`.</ResponseField>

    <ResponseField name="status" type="string">
      Current provisioning status. One of `"provisioned"`, `"pending"`, `"failed"`, or `"suspended"`.
    </ResponseField>

    <ResponseField name="last_error" type="string | null">Error message if provisioning failed, or `null`.</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
    <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const mailbox = await ApiService.invoke("agent-mailboxes-self", "get", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
  });
  console.log(mailbox.email_address); // e.g. "support-bot@mail.helpgenie.ai"
  console.log(mailbox.status);        // e.g. "provisioned"
  ```

  ```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": "agent-mailboxes-self",
      "action": "get",
      "data": {
        "agentId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "mbx-uuid-001",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "email_address": "support-bot@mail.helpgenie.ai",
      "account_id": "acct-abc123",
      "grant_id": null,
      "status": "provisioned",
      "last_error": null,
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    }
  }
  ```
</CodeGroup>

***

## Provision mailbox

Creates an email inbox for a genie that doesn't have one yet. If a `desiredLocalpart` is provided and the genie already has a mailbox, the existing inbox is deprovisioned and a new one is created at the requested address.

<ParamField type="string">
  Must be `"agent-mailboxes-self"`
</ParamField>

<ParamField type="string">
  Must be `"provision"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      UUID of the genie to provision a mailbox for.
    </ParamField>

    <ParamField type="string">
      Requested prefix for the mailbox email address (the part before the `@`). Must be 2–40 characters, using only lowercase letters, digits, and hyphens. Cannot start or end with a hyphen. Omit to let the system choose an address automatically.

      When provided for a genie that already has a mailbox, the current mailbox is deprovisioned and a new one is created at the requested address.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  The provisioned mailbox record.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Mailbox UUID.</ResponseField>
    <ResponseField name="agent_id" type="string">UUID of the owning genie.</ResponseField>
    <ResponseField name="email_address" type="string">The provisioned mailbox email address.</ResponseField>
    <ResponseField name="account_id" type="string | null">Internal account reference used by the mail system, or `null` if provisioning is still in progress.</ResponseField>
    <ResponseField name="grant_id" type="string | null">Connection grant identifier, or `null`.</ResponseField>

    <ResponseField name="status" type="string">
      Current provisioning status. One of `"provisioned"`, `"pending"`, `"failed"`, or `"suspended"`.
    </ResponseField>

    <ResponseField name="last_error" type="string | null">Error message if provisioning failed, or `null`.</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
    <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<Warning>
  When `desiredLocalpart` is provided for a genie that already has a mailbox, the existing inbox is permanently deprovisioned before the new one is created. Any emails in the old inbox will be lost.
</Warning>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  // Provision with a custom address prefix
  const mailbox = await ApiService.invoke("agent-mailboxes-self", "provision", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    desiredLocalpart: "support-bot",
  });

  // Provision with a system-chosen address
  const mailbox = await ApiService.invoke("agent-mailboxes-self", "provision", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
  });
  ```

  ```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": "agent-mailboxes-self",
      "action": "provision",
      "data": {
        "agentId": "550e8400-e29b-41d4-a716-446655440000",
        "desiredLocalpart": "support-bot"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "mbx-uuid-001",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "email_address": "support-bot@mail.helpgenie.ai",
      "account_id": "acct-abc123",
      "grant_id": null,
      "status": "provisioned",
      "last_error": null,
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    }
  }
  ```
</CodeGroup>

***

## Update mailbox

Suspends or resumes a genie's mailbox and/or updates its escalation address. At least one of `action` or `escalation_address` must be provided.

<ParamField type="string">
  Must be `"agent-mailboxes-self"`
</ParamField>

<ParamField type="string">
  Must be `"update"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      UUID of the genie whose mailbox to update.
    </ParamField>

    <ParamField type="string">
      Lifecycle transition. Must be `"suspend"` or `"resume"`. Omit to leave the current status unchanged.
    </ParamField>

    <ParamField type="string | null">
      Fallback email address for messages the genie cannot handle. Must be a valid email address, or `null` to clear the current value. Omit this key entirely to leave it unchanged.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="ok" type="boolean">
      `true` when the update was applied successfully.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  // Suspend the mailbox
  await ApiService.invoke("agent-mailboxes-self", "update", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    action: "suspend",
  });

  // Set an escalation address
  await ApiService.invoke("agent-mailboxes-self", "update", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    escalation_address: "oncall@example.com",
  });

  // Resume and clear escalation at the same time
  await ApiService.invoke("agent-mailboxes-self", "update", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    action: "resume",
    escalation_address: null,
  });
  ```

  ```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": "agent-mailboxes-self",
      "action": "update",
      "data": {
        "agentId": "550e8400-e29b-41d4-a716-446655440000",
        "action": "suspend"
      }
    }'
  ```

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

***

## Delete mailbox

Permanently deprovisions a genie's email inbox. After deletion, the genie will no longer receive email.

<ParamField type="string">
  Must be `"agent-mailboxes-self"`
</ParamField>

<ParamField type="string">
  Must be `"delete"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      UUID of the genie whose mailbox to deprovision.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="ok" type="boolean">
      `true` when the mailbox was successfully deprovisioned.
    </ResponseField>
  </Expandable>
</ResponseField>

<Warning>
  This action permanently deprovisions the mailbox and removes all associated records. It is idempotent if the mailbox is already absent in the mail system. The genie itself is not affected.
</Warning>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  await ApiService.invoke("agent-mailboxes-self", "delete", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
  });
  ```

  ```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": "agent-mailboxes-self",
      "action": "delete",
      "data": {
        "agentId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }'
  ```

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

***

## Send test email

Sends a test email into a genie's mailbox to verify it is provisioned and receiving correctly.

<ParamField type="string">
  Must be `"agent-mailboxes-self"`
</ParamField>

<ParamField type="string">
  Must be `"test"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      UUID of the genie whose mailbox to test.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  Result from the mail system's test endpoint. Shape may vary; a successful response indicates the test email was accepted for delivery.
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const result = await ApiService.invoke("agent-mailboxes-self", "test", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
  });
  ```

  ```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": "agent-mailboxes-self",
      "action": "test",
      "data": {
        "agentId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }'
  ```

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

***

## Check mail credentials (admin only)

Verifies that your team's stored mail service credentials are still valid and active. Use this to diagnose email delivery failures — for example, when the mail service returns authentication errors and you need to confirm whether the credentials have been rotated or revoked.

<Note>
  This action requires admin privileges. Non-admin callers receive a `FORBIDDEN` error.
</Note>

<ParamField type="string">
  Must be `"agent-mailboxes-self"`
</ParamField>

<ParamField type="string">
  Must be `"check-tenant-key"`
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="status" type="string">
      Current credential status as reported by the mail service (e.g. `"active"`). Returns `"unknown"` if the service does not provide a status.
    </ResponseField>

    <ResponseField name="revokedAt" type="string | null">
      ISO 8601 timestamp of when the credentials were revoked, or `null` if still active.
    </ResponseField>

    <ResponseField name="tenantId" type="string">
      Your team's mail tenant identifier.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const result = await ApiService.invoke("agent-mailboxes-self", "check-tenant-key");
  console.log(result.status);    // e.g. "active"
  console.log(result.revokedAt); // null if still valid
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_ADMIN_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "agent-mailboxes-self",
      "action": "check-tenant-key"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "status": "active",
      "revokedAt": null,
      "tenantId": "tenant-abc123"
    }
  }
  ```
</CodeGroup>

***

## Re-provision mail credentials (admin only)

Reissues your team's mail service credentials, replacing the current key with a fresh one. Use this when `check-tenant-key` reports that credentials are invalid or revoked.

<Note>
  This action requires admin privileges. Non-admin callers receive a `FORBIDDEN` error.
</Note>

<Warning>
  Re-provisioning invalidates the current credentials immediately. Any in-flight requests using the old key will fail until they re-authenticate. Only call this when `check-tenant-key` confirms the existing credentials are no longer valid.
</Warning>

<ParamField type="string">
  Must be `"agent-mailboxes-self"`
</ParamField>

<ParamField type="string">
  Must be `"reprovision-tenant-key"`
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="tenantId" type="string">
      Your team's mail tenant identifier (unchanged after re-provisioning).
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const result = await ApiService.invoke("agent-mailboxes-self", "reprovision-tenant-key");
  console.log(result.tenantId);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_ADMIN_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "agent-mailboxes-self",
      "action": "reprovision-tenant-key"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "tenantId": "tenant-abc123"
    }
  }
  ```
</CodeGroup>

***

## Error codes

| Code               | Status | Description                                                                                                                                                   |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UNAUTHORIZED`     | 401    | Caller does not own the specified genie                                                                                                                       |
| `FORBIDDEN`        | 403    | Admin-only action called by a non-admin                                                                                                                       |
| `NOT_FOUND`        | 404    | Genie, mailbox, or mail credentials not found                                                                                                                 |
| `VALIDATION_ERROR` | 400    | Missing `agentId`, invalid `desiredLocalpart`, no update fields provided, invalid `escalation_address`, or mailbox already exists when no rename is requested |
| `INVALID_ACTION`   | 400    | Unknown action                                                                                                                                                |
| `INTERNAL_ERROR`   | 500    | Mail system error or local sync failure                                                                                                                       |


# Agent Pages
Source: https://docs.helpgenie.ai/api-reference/agent-pages

Standalone landing pages for Genies.

<Warning>
  **Deprecated.** Agent Pages are superseded by [Genies](/api-reference/genies). Use the Genies API for all new integrations. Existing Agent Pages continue to work but no new features will be added.
</Warning>

Agent Pages are standalone public-facing pages for a Genie. The resource supports full CRUD plus helpers for generating embed codes, resolving public URLs, and handling access requests.

***

## Actions

### `all` / `list`

Returns all Agent Pages for the authenticated user.

**Parameters** — none

***

### `get`

Returns a single Agent Page by ID.

**Parameters**

| Field | Type   | Required | Description                  |
| ----- | ------ | -------- | ---------------------------- |
| `id`  | string | Yes      | Agent Page UUID (request ID) |

***

### `url`

Returns the public URL for an Agent Page.

**Parameters**

| Field | Type   | Required | Description                  |
| ----- | ------ | -------- | ---------------------------- |
| `id`  | string | Yes      | Agent Page UUID (request ID) |

***

### `create`

Creates a new Agent Page.

**Parameters** — standard Genie creation fields.

***

### `update`

Updates an existing Agent Page.

**Parameters**

| Field | Type   | Required | Description                  |
| ----- | ------ | -------- | ---------------------------- |
| `id`  | string | Yes      | Agent Page UUID (request ID) |

***

### `delete`

Deletes an Agent Page. Irreversible.

**Parameters**

| Field | Type   | Required | Description                  |
| ----- | ------ | -------- | ---------------------------- |
| `id`  | string | Yes      | Agent Page UUID (request ID) |

***

### `embed-code`

Returns the HTML embed snippet for an Agent Page.

**Parameters**

| Field | Type   | Required | Description                  |
| ----- | ------ | -------- | ---------------------------- |
| `id`  | string | Yes      | Agent Page UUID (request ID) |

***

### `request-access`

Submits an access request for a private Agent Page.

**Parameters**

| Field | Type   | Required | Description                  |
| ----- | ------ | -------- | ---------------------------- |
| `id`  | string | Yes      | Agent Page UUID (request ID) |


# Analytics
Source: https://docs.helpgenie.ai/api-reference/analytics

Account analytics, trends, genie performance, and period comparisons

Use the `analytics` resource to fetch overview metrics, conversation trends, genie performance breakdowns, and period-over-period comparisons.

Supported actions: `all`, `overview`, `trends`, `genie-performance`, `compare`.

***

## Overview

Returns account-level aggregate counts for genies, conversations, leads, and knowledge base documents. `all` and `overview` are equivalent.

<ParamField type="string">
  Must be `"analytics"`.
</ParamField>

<ParamField type="string">
  `"all"` or `"overview"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      Admin only. View analytics across all users.
    </ParamField>

    <ParamField type="string">
      Admin only. Scope analytics to a specific user.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="stats" type="object">
      <Expandable title="properties">
        <ResponseField name="genies" type="number">
          Total number of genies.
        </ResponseField>

        <ResponseField name="conversations" type="number">
          Total number of conversations.
        </ResponseField>

        <ResponseField name="leads" type="number">
          Total number of leads.
        </ResponseField>

        <ResponseField name="knowledgeBaseDocuments" type="number">
          Total number of knowledge base documents.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```json Request body theme={null}
  {
    "resource": "analytics",
    "action": "overview"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "stats": {
        "genies": 4,
        "conversations": 312,
        "leads": 58,
        "knowledgeBaseDocuments": 19
      }
    }
  }
  ```
</CodeGroup>

***

## Trends

Returns daily conversation trend data points over a time period.

<ParamField type="string">
  Must be `"analytics"`.
</ParamField>

<ParamField type="string">
  Must be `"trends"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Time period. One of `"7d"`, `"30d"`, `"90d"`. Default: `"30d"`.
    </ParamField>

    <ParamField type="boolean">
      Admin only.
    </ParamField>

    <ParamField type="string">
      Admin only.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/analytics \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "action": "trends", "data": { "period": "30d" } }'
  ```
</CodeGroup>

***

## Genie performance

Returns conversation volume grouped by genie, filtered by time period. Supports custom date ranges.

<ParamField type="string">
  Must be `"analytics"`.
</ParamField>

<ParamField type="string">
  Must be `"genie-performance"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Time period. One of `"7d"`, `"30d"`, `"90d"`. Default: `"30d"`.
    </ParamField>

    <ParamField type="string">
      ISO 8601 start timestamp for custom date range.
    </ParamField>

    <ParamField type="string">
      ISO 8601 end timestamp for custom date range.
    </ParamField>

    <ParamField type="boolean">
      Admin only.
    </ParamField>

    <ParamField type="string">
      Admin only.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/analytics \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "genie-performance",
      "data": { "period": "30d" }
    }'
  ```
</CodeGroup>

***

## Compare

Returns a period-over-period conversation comparison (e.g., this week vs last week).

<ParamField type="string">
  Must be `"analytics"`.
</ParamField>

<ParamField type="string">
  Must be `"compare"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Time period. One of `"7d"`, `"30d"`, `"90d"`. Default: `"30d"`.
    </ParamField>

    <ParamField type="boolean">
      Admin only.
    </ParamField>

    <ParamField type="string">
      Admin only.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/analytics \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "action": "compare", "data": { "period": "7d" } }'
  ```
</CodeGroup>


# API keys
Source: https://docs.helpgenie.ai/api-reference/api-keys

Create, list, revoke, and delete developer API keys for programmatic access

Use `api-keys` to create, list, revoke, and delete API keys for the authenticated user.

Supported actions: `all`, `list`, `create`, `revoke`, `delete`.

## Authentication model

<Warning>
  API key management endpoints require a session token (JWT). You cannot manage API keys using another API key.
</Warning>

***

## List API keys

Retrieves all API keys for the authenticated user. Both `all` and `list` return the same result.

<ParamField type="string">
  Must be `"api-keys"`.
</ParamField>

<ParamField type="string">
  `"all"` or `"list"`.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="api_keys" type="object[]">
      <Expandable title="key properties">
        <ResponseField name="id" type="string" />

        <ResponseField name="name" type="string" />

        <ResponseField name="key_prefix" type="string">
          First 8 characters of the key (for display).
        </ResponseField>

        <ResponseField name="is_active" type="boolean" />

        <ResponseField name="last_used_at" type="string | null" />

        <ResponseField name="created_at" type="string" />

        <ResponseField name="revoked_at" type="string | null" />
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    api_keys: ApiKey[];
    count: number;
  }>({
    resource: "api-keys",
    action: "all",
  });
  ```

  ```bash cURL theme={null}
  curl -s https://api.helpgenie.ai/v1/api-keys \
    -H "Authorization: Bearer <session_token>"
  ```
</CodeGroup>

***

## Create API key

Creates a new API key. The full key is returned **once** in the response and cannot be retrieved again.

<ParamField type="string">
  Must be `"api-keys"`.
</ParamField>

<ParamField type="string">
  Must be `"create"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Display name for the key (e.g. `"Production"`).
    </ParamField>
  </Expandable>
</ParamField>

### Response (status 201)

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="api_key" type="object">
      <Expandable title="properties">
        <ResponseField name="id" type="string" />

        <ResponseField name="name" type="string" />

        <ResponseField name="key_prefix" type="string" />

        <ResponseField name="key" type="string">
          The full API key. **Returned only at creation time.** Store it securely.
        </ResponseField>

        <ResponseField name="is_active" type="boolean" />

        <ResponseField name="last_used_at" type="string | null" />

        <ResponseField name="created_at" type="string" />

        <ResponseField name="revoked_at" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ api_key: ApiKey }>(
    {
      resource: "api-keys",
      action: "create",
      data: { name: "Production" },
    },
    201
  );

  // Save response.api_key.key — it won't be shown again
  ```

  ```bash cURL theme={null}
  curl -s -X POST https://api.helpgenie.ai/v1/api-keys \
    -H "Authorization: Bearer <session_token>" \
    -H "Content-Type: application/json" \
    -d '{ "action": "create", "data": { "name": "Production" } }'
  ```
</CodeGroup>

***

## Revoke API key

Revokes a key immediately. Any subsequent requests using the revoked key will return `401`.

<ParamField type="string">
  Must be `"api-keys"`.
</ParamField>

<ParamField type="string">
  Must be `"revoke"`.
</ParamField>

<ParamField type="string">
  The API key ID to revoke.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="message" type="string">
      `"API key revoked successfully"`
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X PATCH https://api.helpgenie.ai/v1/api-keys/KEY_UUID \
    -H "Authorization: Bearer <session_token>"
  ```
</CodeGroup>

***

## Delete API key

Permanently deletes an API key record.

<ParamField type="string">
  Must be `"api-keys"`.
</ParamField>

<ParamField type="string">
  Must be `"delete"`.
</ParamField>

<ParamField type="string">
  The API key ID to delete.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="message" type="string">
      `"API key deleted permanently"`
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X DELETE https://api.helpgenie.ai/v1/api-keys/KEY_UUID \
    -H "Authorization: Bearer <session_token>"
  ```
</CodeGroup>

***

## Using API keys

Once created, pass your API key on every request:

```
Authorization: Bearer hg_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
```

or:

```
X-API-Key: hg_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
```

API keys inherit the same permissions as the user who created them.

## Operational limits

* Maximum **5** active keys per user.
* Rate limit of **60 requests/minute** per key.

***

## Error responses

| Status | Code                  | Description                                                      |
| ------ | --------------------- | ---------------------------------------------------------------- |
| 400    | `VALIDATION_ERROR`    | Maximum 5 active API keys allowed. Revoke an existing key first. |
| 401    | `INVALID_TOKEN`       | Invalid or revoked API key                                       |
| 429    | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded                                              |


# Billing
Source: https://docs.helpgenie.ai/api-reference/billing

Subscription, usage, and Stripe delegated billing actions

Use the `billing` resource for plan retrieval and billing lifecycle actions.

**Direct actions** (handled locally): `all`, `get`, `create`, `update`, `delete`, `calls`, `phones`

**Stripe-delegated actions** (proxied to `stripe-handler`): `checkout`, `billing-portal`, `update-subscription`, `sync`, `check-status`, `purchase-calls`, `cancel-calls`, `add-phone-number`, `remove-phone-number`

<Note>
  The previously documented `plan`, `usage`, and `invoices` action names do not exist — use `get` and `all` to retrieve billing data.
</Note>


# Brand Integrity
Source: https://docs.helpgenie.ai/api-reference/brand-integrity

Run and manage Brand Integrity audits — automated tests that verify your Genie behaves on-brand across a suite of conversation scenarios.

Brand Integrity lets you simulate conversations with a Genie and score the results against expected behaviour. Audits run asynchronously; progress is broadcast over the `brand-tests` Supabase Realtime channel. Workspace members share access to their owner's test runs.

***

## Actions

### `all`

Returns all **completed** test runs for a specific Genie, each with its results array embedded.

**Parameters**

| Field       | Type    | Required | Description                                                                  |
| ----------- | ------- | -------- | ---------------------------------------------------------------------------- |
| `agentId`   | string  | Yes      | Genie UUID to fetch runs for                                                 |
| `dateRange` | string  | No       | Filter by recency — e.g. `"7d"`, `"30d"`. Omit or pass `"all"` for no filter |
| `adminMode` | boolean | No       | Admin only — bypass ownership filter                                         |
| `userId`    | string  | No       | Admin only — target a specific user                                          |

**Response**

```json theme={null}
{
  "items": [
    {
      "id": "run-uuid",
      "agent_id": "agent-uuid",
      "status": "completed",
      "run_type": "full_audit",
      "total_tests": 12,
      "progress": 12,
      "started_at": "2024-01-01T00:00:00Z",
      "completed_at": "2024-01-01T00:05:00Z",
      "results": [ /* brand_test_results rows */ ]
    }
  ]
}
```

***

### `get`

Returns a single test run by ID with its full results array.

**Parameters**

| Field | Type   | Required | Description                          |
| ----- | ------ | -------- | ------------------------------------ |
| `id`  | string | Yes      | Test run UUID (passed as request ID) |

**Response**

```json theme={null}
{
  "testRun": {
    "id": "run-uuid",
    "agent_id": "agent-uuid",
    "status": "completed",
    "results": [ /* brand_test_results rows */ ]
  }
}
```

***

### `list`

Paginated list of test runs across one or more Genies, optionally filtered by status.

**Parameters**

| Field          | Type      | Required | Description                                  |
| -------------- | --------- | -------- | -------------------------------------------- |
| `agentId`      | string    | No       | Filter to a single Genie                     |
| `agentIds`     | string\[] | No       | Filter to multiple Genies                    |
| `dateRange`    | string    | No       | e.g. `"7d"`, `"30d"`, `"all"`                |
| `statusFilter` | string    | No       | `"all"` (default), `"passed"`, or `"failed"` |
| `page`         | number    | No       | Page number, default `1`                     |
| `pageSize`     | number    | No       | Results per page, default `20`, max `100`    |
| `adminMode`    | boolean   | No       | Admin only                                   |
| `userId`       | string    | No       | Admin only                                   |

**Response**

```json theme={null}
{
  "items": [ /* test runs with embedded results */ ],
  "totalCount": 42,
  "page": 1,
  "pageSize": 20
}
```

***

### `list-results`

Returns all individual test results for a specific run.

**Parameters**

| Field | Type   | Required | Description   |
| ----- | ------ | -------- | ------------- |
| `id`  | string | Yes      | Test run UUID |

**Response**

```json theme={null}
{
  "items": [ /* brand_test_results rows, ordered by created_at asc */ ]
}
```

***

### `list-scenarios`

Returns all custom (non-predefined) test scenarios belonging to the authenticated user or workspace.

**Parameters** — none

**Response**

```json theme={null}
{
  "items": [
    {
      "id": "scenario-uuid",
      "name": "Refund Policy Check",
      "description": "Verifies agent handles refund requests correctly",
      "testPrompts": ["I want a refund", "My order never arrived"],
      "isCustom": true,
      "userId": "user-uuid",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}
```

***

### `create-scenario`

Creates a custom test scenario.

**Parameters**

| Field         | Type      | Required | Description                                 |
| ------------- | --------- | -------- | ------------------------------------------- |
| `name`        | string    | Yes      | Scenario name                               |
| `testPrompts` | string\[] | Yes      | Non-empty array of user prompts to simulate |
| `description` | string    | No       | Optional description                        |
| `category`    | string    | No       | Category label, defaults to `"custom"`      |

**Response** — `201`

```json theme={null}
{
  "scenario": {
    "id": "scenario-uuid",
    "name": "Refund Policy Check",
    "testPrompts": ["I want a refund"],
    "isCustom": true,
    "createdAt": "2024-01-01T00:00:00Z"
  }
}
```

***

### `delete-scenario`

Deletes a custom scenario. Only the owner (or an admin) can delete.

**Parameters**

| Field | Type   | Required | Description   |
| ----- | ------ | -------- | ------------- |
| `id`  | string | Yes      | Scenario UUID |

**Response**

```json theme={null}
{ "success": true }
```

***

### `get-audit-scenarios`

Returns AI-generated scenarios that were created for a specific audit run.

**Parameters**

| Field | Type   | Required | Description                                  |
| ----- | ------ | -------- | -------------------------------------------- |
| `id`  | string | Yes      | Audit run ID (numeric, passed as request ID) |

**Response**

```json theme={null}
{
  "items": [ /* brand_test_scenarios rows ordered by severity asc */ ]
}
```

***

### `save-manual-test`

Saves a manually recorded conversation as a completed test run. Useful for logging quick-test sessions from the UI.

**Parameters**

| Field                      | Type   | Required | Description                                  |
| -------------------------- | ------ | -------- | -------------------------------------------- |
| `agentId`                  | string | Yes      | Genie UUID                                   |
| `transcript`               | array  | Yes      | Non-empty array of conversation turn objects |
| `elevenlabsConversationId` | string | No       | Associated ElevenLabs conversation ID        |
| `durationSeconds`          | number | No       | Duration of the conversation                 |

**Response** — `201`

```json theme={null}
{
  "testRun": { /* brand_test_runs row */ }
}
```

***

### `run-full-audit`

Kicks off a full automated Brand Integrity audit for a Genie. Creates a test run in `generating` state, then asynchronously generates scenarios and executes them. Returns immediately with the `testRunId` — subscribe to the `brand-tests` Realtime channel for progress updates.

The Genie must have a voice configured (`elevenlabs_id`).

**Parameters**

| Field                  | Type    | Required | Description                                                                             |
| ---------------------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| `agentId`              | string  | Yes      | Genie UUID to audit                                                                     |
| `regenerate`           | boolean | No       | Force regeneration of scenarios even if they exist                                      |
| `scenariosPerCategory` | object  | No       | Map of `{ [categoryId]: count }` to control scenario volume per category (clamped 1–20) |

**Response** — `201`

```json theme={null}
{
  "testRunId": "run-uuid"
}
```

***

### `run-custom-audit`

Runs a custom audit using a specific selection of categories, AI-suggested tests, and/or saved custom scenario IDs. Returns immediately with `testRunId`; execution is asynchronous.

**Parameters**

| Field            | Type      | Required | Description                                                                                          |
| ---------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `agentId`        | string    | Yes      | Genie UUID                                                                                           |
| `elevenlabsId`   | string    | Yes      | ElevenLabs agent ID for the Genie                                                                    |
| `categories`     | string\[] | No       | Category IDs to include                                                                              |
| `suggestedTests` | object\[] | No       | AI-suggested test objects (`id`, `name`, `description`, `simulatedUserPrompt`, `evaluationCriteria`) |
| `customTestIds`  | string\[] | No       | Saved custom scenario UUIDs to run                                                                   |

**Response** — `201`

```json theme={null}
{
  "testRunId": "run-uuid",
  "status": "running"
}
```

***

## Error codes

| Code               | Meaning                               |
| ------------------ | ------------------------------------- |
| `VALIDATION_ERROR` | Missing or invalid required parameter |
| `NOT_FOUND`        | Test run or scenario not found        |
| `FORBIDDEN`        | You do not own this resource          |
| `AGENT_NOT_FOUND`  | Genie does not exist                  |
| `INTERNAL_ERROR`   | Unexpected server error               |


# Branding
Source: https://docs.helpgenie.ai/api-reference/branding

Manage team-level branding (logo, colors, QR code, embed styles) and generate AI logos.

All requests use a single endpoint: `POST /functions/v1/api` with `resource: "branding"`.

## Access control

<Note>
  All branding actions require authentication. The user must belong to a team. Branding is stored at the team level.
</Note>

| Action          | Any user | Team member | Team owner | Admin |
| --------------- | -------- | ----------- | ---------- | ----- |
| `get` / `all`   | No       | Yes         | Yes        | Yes   |
| `update`        | No       | No          | Yes        | Yes   |
| `clear`         | No       | No          | Yes        | Yes   |
| `generate-logo` | No       | Yes         | Yes        | Yes   |

***

## Get branding

Retrieves the team's branding configuration.

<ParamField type="string">
  Must be `"branding"`
</ParamField>

<ParamField type="string">
  Must be `"get"` or `"all"`
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const { team, branding } = await ApiService.invoke({
    resource: "branding",
    action: "get",
  });
  ```

  ```bash cURL theme={null}
  curl https://api.helpgenie.ai/v1/branding \
    -H "Authorization: Bearer hg_live_..."
  ```
</CodeGroup>

<ResponseField name="team" type="object">
  Team object with `id`, `name`, `branding`
</ResponseField>

<ResponseField name="branding" type="object | null">
  The branding object, or `null` if no branding is set. Contains `primaryColor`, `secondaryColor`, `logoUrl`, `gradientEnabled`, `gradientAngle`, `qrCodeStyle`, `embedStyle`, `extractedPalette`, etc.
</ResponseField>

***

## Update branding

Updates the team's branding configuration.

<ParamField type="string">
  Must be `"branding"`
</ParamField>

<ParamField type="string">
  Must be `"update"`
</ParamField>

<ParamField type="object">
  The branding object to set. Replaces the entire branding configuration.
</ParamField>

<ParamField type="string">
  Optional team name update (applied alongside branding).
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const { team, branding } = await ApiService.invoke({
    resource: "branding",
    action: "update",
    data: {
      branding: {
        primaryColor: "#1B5E8C",
        secondaryColor: "#4E9CFF",
        logoUrl: "https://...",
        gradientEnabled: true,
        gradientAngle: 135,
      },
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/branding \
    -H "Authorization: Bearer hg_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "action": "update",
      "branding": {
        "primaryColor": "#1B5E8C",
        "secondaryColor": "#4E9CFF",
        "logoUrl": "https://...",
        "gradientEnabled": true
      }
    }'
  ```
</CodeGroup>

***

## Clear branding

Resets the team's branding to `null` (removes all custom branding).

<ParamField type="string">
  Must be `"branding"`
</ParamField>

<ParamField type="string">
  Must be `"clear"`
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const { team } = await ApiService.invoke({
    resource: "branding",
    action: "clear",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/branding \
    -H "Authorization: Bearer hg_live_..." \
    -H "Content-Type: application/json" \
    -d '{"action": "clear"}'
  ```
</CodeGroup>

***

## Generate logo

Generate a professional AI logo icon. Returns a transparent PNG uploaded to storage. The logo is an icon/symbol only (no text). Generation takes 15-60 seconds.

<ParamField type="string">
  Must be `"branding"`
</ParamField>

<ParamField type="string">
  Must be `"generate-logo"`
</ParamField>

<ParamField type="string">
  Brand or business name. Used as a thematic hint to inspire the icon design (not rendered as text in the logo).
</ParamField>

<ParamField type="string">
  Short business description for prompt context. Example: `"A residential plumbing business in Austin, TX"`
</ParamField>

<ParamField type="string">
  Style preset. One of: `modern` (default), `classic`, `bold`, `friendly`, `tech`, `luxury`.
</ParamField>

<ParamField type="string">
  Industry context for relevant iconography. One of: `automotive`, `marine`, `appliances`, `office-equipment`, `home-builders`, `travel-hospitality`, `manufacturing`, `industrial`, `trades`, `plumbing`, `electrical`, `hvac`, `landscaping`, `real-estate`, `healthcare`, `fitness`, `restaurant`, `retail`, `technology`, `education`, `finance`, `legal`.
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const { image_url } = await ApiService.invoke({
    resource: "branding",
    action: "generate-logo",
    data: {
      name: "Plumbing Pros",
      description: "Residential plumbing in Austin, TX",
      industry: "plumbing",
      style: "modern",
    },
  });

  // Then apply the logo to branding:
  await ApiService.invoke({
    resource: "branding",
    action: "update",
    data: {
      branding: { ...existingBranding, logoUrl: image_url },
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/branding \
    -H "Authorization: Bearer hg_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "action": "generate-logo",
      "name": "Plumbing Pros",
      "description": "Residential plumbing in Austin, TX",
      "industry": "plumbing",
      "style": "modern"
    }'
  ```
</CodeGroup>

<ResponseField name="image_url" type="string">
  Public URL of the generated logo PNG (transparent background). Can be used directly as the `logoUrl` in a branding update.
</ResponseField>

<ResponseField name="storage_path" type="string">
  Supabase Storage path: `generated-logos/{filename}.png`
</ResponseField>

<ResponseField name="replicate_prediction_id" type="string">
  Replicate prediction ID for debugging/tracking.
</ResponseField>

<Note>
  The generated logo is a transparent PNG icon/symbol with no text. To apply it to your branding, take the returned `image_url` and pass it as `logoUrl` in a subsequent `update` call.
</Note>


# Capabilities
Source: https://docs.helpgenie.ai/api-reference/capabilities

Runtime discovery of resources and supported actions

Use `capabilities` to discover available API resources/actions dynamically.

Supported actions: `all`, `list`, `get`.


# Context Sources
Source: https://docs.helpgenie.ai/api-reference/context-sources

Manage live data integrations that supply real-time context to your Genies during conversations.

Context sources connect your Genies to external data — via a REST API, an MCP server, or a static text document. When a source is attached to a Genie, its capabilities are discovered automatically and made available during conversations.

Supported `source_type` values: `api`, `mcp`, `text_document`.

Workspace members share access to their owner's context sources.

***

## Actions

### `get`

Returns a single context source by ID.

**Parameters**

| Field       | Type    | Required | Description                                |
| ----------- | ------- | -------- | ------------------------------------------ |
| `id`        | string  | Yes      | Context source UUID (passed as request ID) |
| `adminMode` | boolean | No       | Admin only — bypass ownership filter       |

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "source-uuid",
    "source_type": "api",
    "config": { },
    "capabilities": [ ],
    "last_capabilities_fetch": "2024-01-01T00:00:00Z"
  }
}
```

***

### `list`

Returns all context sources for the authenticated user, optionally filtered to sources attached to a specific Genie.

**Parameters**

| Field       | Type    | Required | Description                                |
| ----------- | ------- | -------- | ------------------------------------------ |
| `agentId`   | string  | No       | Only return sources attached to this Genie |
| `adminMode` | boolean | No       | Admin only                                 |

**Response**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "source-uuid",
      "source_type": "mcp",
      "config": { },
      "capabilities": [ ],
      "agents": [ { "agent_id": "agent-uuid" } ]
    }
  ]
}
```

***

### `create`

Creates a new context source and immediately fetches its capabilities from the remote endpoint.

For `mcp` sources, `credential_value` is required for capability discovery. The credential is stored encrypted in the vault automatically.

**Parameters**

| Field              | Type   | Required | Description                                                    |
| ------------------ | ------ | -------- | -------------------------------------------------------------- |
| `source_type`      | string | Yes      | `"api"`, `"mcp"`, or `"text_document"`                         |
| `config`           | object | Yes      | Source-specific configuration (URL, headers, etc.)             |
| `credential_value` | string | No       | API key or bearer token — stored encrypted. Required for `mcp` |

**Response**

```json theme={null}
{
  "success": true,
  "data": { /* context_sources row */ }
}
```

***

### `attach`

Attaches an existing context source to a Genie.

**Parameters**

| Field      | Type   | Required | Description         |
| ---------- | ------ | -------- | ------------------- |
| `agentId`  | string | Yes      | Genie UUID          |
| `sourceId` | string | Yes      | Context source UUID |

**Response**

```json theme={null}
{
  "success": true,
  "data": { /* context_sources row */ }
}
```

***

### `upsert`

Creates or updates a context source and attaches it to a Genie in a single operation. Capabilities are fetched at write time.

**Parameters**

| Field              | Type   | Required | Description                                          |
| ------------------ | ------ | -------- | ---------------------------------------------------- |
| `agentId`          | string | Yes      | Genie UUID to attach to                              |
| `source_type`      | string | Yes      | `"api"`, `"mcp"`, or `"text_document"`               |
| `config`           | object | Yes      | Source configuration                                 |
| `sourceId`         | string | No       | UUID of an existing source to update; omit to create |
| `credential_value` | string | No       | API key or bearer token. Required for `mcp`          |

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "source-uuid",
    "source_type": "api",
    "capabilities": [ ]
  }
}
```

***

### `update`

Updates mutable fields on a context source. Currently supports toggling `is_active`.

**Parameters**

| Field       | Type    | Required | Description                  |
| ----------- | ------- | -------- | ---------------------------- |
| `id`        | string  | Yes      | Context source UUID          |
| `is_active` | boolean | Yes      | Enable or disable the source |

**Response**

```json theme={null}
{ "success": true }
```

***

### `delete`

Detaches a context source from a Genie (removes the `agent_context_source` association). The source itself is not deleted.

**Parameters**

| Field      | Type   | Required | Description                                                               |
| ---------- | ------ | -------- | ------------------------------------------------------------------------- |
| `agentId`  | string | Yes      | Genie UUID                                                                |
| `sourceId` | string | No       | Specific source UUID to detach. Omit to detach all sources from the Genie |

**Response**

```json theme={null}
{ "success": true }
```

***

### `delete-source`

Permanently deletes a context source and its associated credential from the vault. Irreversible.

**Parameters**

| Field      | Type   | Required | Description         |
| ---------- | ------ | -------- | ------------------- |
| `sourceId` | string | Yes      | Context source UUID |

**Response**

```json theme={null}
{ "success": true }
```

***

### `refresh-capabilities`

Re-fetches and updates the capability list for the context source attached to a Genie. Useful after the remote API changes.

**Parameters**

| Field     | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| `agentId` | string | Yes      | Genie UUID whose attached source to refresh |

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "capabilities": [ /* updated capability list */ ]
  }
}
```

***

## Error codes

| Code               | Meaning                                                    |
| ------------------ | ---------------------------------------------------------- |
| `VALIDATION_ERROR` | Missing or invalid parameter, or unsupported `source_type` |
| `NOT_FOUND`        | Source or agent-source association not found               |
| `UNAUTHORIZED`     | You do not have access to this Genie                       |
| `INTERNAL_ERROR`   | Unexpected server error                                    |


# Conversations
Source: https://docs.helpgenie.ai/api-reference/conversations

List, retrieve, sync, analyze, update, and delete conversation records

## List conversations

Retrieves a paginated list of conversations. Standard users see only conversations belonging to their own genies. Admin users see all conversations.

<ParamField type="string">
  `conversations`
</ParamField>

<ParamField type="string">
  `all`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string[]">
      Filter conversations to specific genies by UUID array. When omitted, returns conversations for all genies the user owns.
    </ParamField>

    <ParamField type="number">
      Maximum number of records to return per page. Defaults to `30`, maximum `500`.
    </ParamField>

    <ParamField type="string">
      Cursor returned from a previous response as `nextCursor`. Pass it unchanged to fetch the next page.
    </ParamField>

    <ParamField type="string">
      Relative time filter. Format: `{value}{unit}` where unit is `h` (hours), `d` (days), or `m` (minutes). For example, `"24h"` returns conversations from the last 24 hours.
    </ParamField>

    <ParamField type="boolean">
      When `true`, excludes conversations with `type = "mailbox"`.
    </ParamField>

    <ParamField type="string">
      Filter by conversation type. Accepted values:

      * `"regular"` — conversations that are not setup or mailbox type
      * `"setup"` — setup conversations
      * `"mailbox"` — mailbox-originated conversations
    </ParamField>

    <ParamField type="string">
      Filter by the channel the conversation originated from. Accepted values:

      * `"phone"` — inbound phone calls
      * `"email"` — email conversations
      * `"app"` — mobile or native app
      * `"link"` — link or QR code
      * `"web"` — web widget (default fallback for unrecognized sources)
    </ParamField>

    <ParamField type="string">
      Admin only. Filter conversations to genies owned by this user ID.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "conversations",
    action: "list",
    data: {
      agentIds: ["agent-uuid"],
      limit: 30,
      channel: "phone",
      conversationType: "regular",
    },
  });
  ```

  ```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": "conversations",
      "action": "list",
      "data": {
        "agentIds": ["agent-uuid"],
        "limit": 30,
        "channel": "phone",
        "conversationType": "regular"
      }
    }'
  ```
</CodeGroup>

### Response

<ResponseField name="conversations" type="Conversation[]">
  Array of conversation objects, each joined with basic genie info.

  <Expandable title="Conversation object">
    <ResponseField name="id" type="number">
      Unique conversation identifier.
    </ResponseField>

    <ResponseField name="agent_id" type="string | null">
      ID of the genie this conversation belongs to.
    </ResponseField>

    <ResponseField name="el_agent_id" type="string | null">
      External agent ID from the voice platform.
    </ResponseField>

    <ResponseField name="user_id" type="string | null">
      ID of the user who owns the genie.
    </ResponseField>

    <ResponseField name="status" type="string | null">
      Conversation status.
    </ResponseField>

    <ResponseField name="type" type="string | null">
      Conversation type.
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Arbitrary metadata associated with the conversation.
    </ResponseField>

    <ResponseField name="viewed" type="boolean">
      Whether the conversation has been viewed.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the conversation was created.
    </ResponseField>

    <ResponseField name="agents" type="object | null">
      Joined genie data.

      <Expandable title="properties">
        <ResponseField name="id" type="string">
          Genie ID.
        </ResponseField>

        <ResponseField name="name" type="string">
          Genie name.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextCursor" type="string | null">
  Opaque cursor string. Pass as `cursor` in the next request to fetch the next page. `null` when there are no more results.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  Whether more results are available beyond this page.
</ResponseField>

***

## Get conversation

Retrieves a single conversation by ID, including analysis details and associated media. The conversation is automatically marked as viewed on fetch. If analysis details exist but are incomplete, analysis runs automatically before the response is returned.

<ParamField type="string">
  `conversations`
</ParamField>

<ParamField type="string">
  `get`
</ParamField>

<ParamField type="string">
  The conversation ID.
</ParamField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "conversations",
    action: "get",
    id: "123",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/conversations \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "get",
      "id": "123"
    }'
  ```
</CodeGroup>

### Response

Returns the full conversation object spread directly into `data`, with nested genie, analysis details, and media.

<ResponseField name="id" type="string">
  Unique conversation identifier.
</ResponseField>

<ResponseField name="agent_id" type="string | null">
  ID of the genie this conversation belongs to.
</ResponseField>

<ResponseField name="status" type="string | null">
  Conversation status.
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Arbitrary metadata associated with the conversation.
</ResponseField>

<ResponseField name="viewed" type="boolean">
  Whether the conversation has been viewed. Always `true` after a successful `get` call — the conversation is marked viewed automatically.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<ResponseField name="agent" type="object | null">
  The genie that handled this conversation, including its full configuration and lead-info preset.
</ResponseField>

<ResponseField name="conversation_details" type="object[] | null">
  Analysis details for this conversation. Contains `summary`, `transcript`, `goals`, `topics`, `lead_info`, and `analysis_result`. If these fields were missing when the conversation was fetched, analysis is triggered automatically and the populated details are returned in this response.
</ResponseField>

<ResponseField name="medias" type="object[]">
  Media records (recordings, attachments) associated with this conversation. Empty array when no media exists.

  <Expandable title="item properties">
    <ResponseField name="id" type="string">Media record ID.</ResponseField>
    <ResponseField name="metadata" type="object">Media metadata, including `conversations_id`.</ResponseField>
  </Expandable>
</ResponseField>

***

## Sync conversations

Triggers a sync of conversations from the voice agent system for a specific genie.

<ParamField type="string">
  `conversations`
</ParamField>

<ParamField type="string">
  `sync`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The genie ID to sync conversations for. The user must own this genie.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "conversations",
    action: "sync",
    data: {
      agentId: "agent-uuid",
    },
  });
  ```
</CodeGroup>

### Response

<ResponseField name="success" type="boolean">
  `true` if the sync completed without errors.
</ResponseField>

<ResponseField name="synced" type="boolean">
  `true` if new conversation data was pulled from the voice agent system.
</ResponseField>

<ResponseField name="conversation" type="object">
  The synced conversation record with the latest data from the voice agent system.

  <Expandable title="properties">
    <ResponseField name="id" type="number">
      Unique conversation identifier.
    </ResponseField>

    <ResponseField name="agent_id" type="string">
      ID of the genie this conversation belongs to.
    </ResponseField>

    <ResponseField name="status" type="string">
      Updated conversation status from the voice platform.
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Conversation metadata, including any data synced from the voice platform.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Sync pulls the latest conversation data from the voice agent system, including updated transcripts, status, and metadata. The authenticated user must own the genie specified by `agentId`. A `403 FORBIDDEN` error is returned otherwise.
</Note>

***

## Analyze conversation

Runs an analysis on a specific conversation.

<ParamField type="string">
  `conversations`
</ParamField>

<ParamField type="string">
  `analyze`
</ParamField>

<ParamField type="string">
  The conversation ID to analyze.
</ParamField>

<ParamField type="object">
  Additional parameters to pass to the analysis function.
</ParamField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "conversations",
    action: "analyze",
    id: "123",
    data: {
      // optional analysis parameters
    },
  });
  ```
</CodeGroup>

### Response

Returns a detailed analysis object generated by the `handle-conversation` edge function.

<ResponseField name="analysis" type="object">
  The analysis result for the conversation.

  <Expandable title="Analysis object">
    <ResponseField name="sentiment" type="string">
      Overall sentiment of the conversation. One of `positive`, `negative`, `neutral`, or `mixed`.
    </ResponseField>

    <ResponseField name="summary" type="string">
      A concise natural-language summary of the conversation.
    </ResponseField>

    <ResponseField name="key_topics" type="string[]">
      Array of topics discussed during the conversation.
    </ResponseField>

    <ResponseField name="action_items" type="object[]">
      Extracted action items or follow-ups.

      <Expandable title="ActionItem object">
        <ResponseField name="description" type="string">
          Description of the action item.
        </ResponseField>

        <ResponseField name="assignee" type="string | null">
          Who the action item is assigned to, if identifiable.
        </ResponseField>

        <ResponseField name="priority" type="string">
          Priority level: `high`, `medium`, or `low`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="duration_analysis" type="object">
      Timing breakdown for the conversation.

      <Expandable title="properties">
        <ResponseField name="total_duration_seconds" type="number">
          Total duration of the conversation in seconds.
        </ResponseField>

        <ResponseField name="agent_talk_time_seconds" type="number">
          Time the genie spent speaking.
        </ResponseField>

        <ResponseField name="user_talk_time_seconds" type="number">
          Time the caller spent speaking.
        </ResponseField>

        <ResponseField name="silence_seconds" type="number">
          Total silence or dead air time.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="conversation_id" type="string">
      The ID of the analyzed conversation.
    </ResponseField>

    <ResponseField name="analyzed_at" type="string">
      ISO 8601 timestamp of when the analysis was performed.
    </ResponseField>
  </Expandable>
</ResponseField>

<Info>
  Analysis is performed asynchronously. For longer conversations, the response may take several seconds to return while the analysis is generated.
</Info>

***

## Update conversation

Updates metadata or fields on an existing conversation. Standard users can only update their own conversations.

<ParamField type="string">
  `conversations`
</ParamField>

<ParamField type="string">
  `update`
</ParamField>

<ParamField type="string">
  The conversation ID to update.
</ParamField>

<ParamField type="object">
  Fields to update. Can be provided directly or nested under an `updates` key.
  Allowed fields: `agent_id`, `el_agent_id`, `metadata`, `status`, `type`, `user_id`, `viewed`.

  <Expandable title="properties">
    <ParamField type="string">
      Updated conversation status.
    </ParamField>

    <ParamField type="object">
      Updated metadata object.
    </ParamField>

    <ParamField type="boolean">
      Mark conversation as viewed or unviewed.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "conversations",
    action: "update",
    id: "123",
    data: {
      viewed: true,
      metadata: { notes: "Follow up required" },
    },
  });
  ```
</CodeGroup>

### Response

Returns the updated conversation object directly in `data`.

***

## Delete conversation

Permanently deletes a conversation. Standard users can only delete their own conversations. Admin users can delete any conversation.

<ParamField type="string">
  `conversations`
</ParamField>

<ParamField type="string">
  `delete`
</ParamField>

<ParamField type="string">
  The conversation ID to delete.
</ParamField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "conversations",
    action: "delete",
    id: "123",
  });
  ```
</CodeGroup>

### Response

<ResponseField name="success" type="boolean">
  `true` if the conversation was deleted.
</ResponseField>

<ResponseField name="id" type="string">
  The ID of the deleted conversation.
</ResponseField>

<Warning>
  This action is permanent and cannot be undone.
</Warning>

***

## Mark all viewed

Marks all conversations as viewed for the authenticated user.

<ParamField type="string">
  `conversations`
</ParamField>

<ParamField type="string">
  `mark-all-viewed`
</ParamField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "conversations",
    action: "mark-all-viewed",
  });
  ```
</CodeGroup>

### Response

<ResponseField name="success" type="boolean">
  `true` if the operation completed.
</ResponseField>

***

## Clear agent data

Permanently deletes all conversation history and activity records for a specific genie. Typically used when reassigning a genie to a different customer to ensure no prior data carries over.

<Warning>
  This action is irreversible and restricted to admin users. All conversations, inbox records, conversation details, and activity logs for the specified genie are permanently removed.
</Warning>

<ParamField type="string">
  `conversations`
</ParamField>

<ParamField type="string">
  `clear-agent-data`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The genie ID whose conversation history should be cleared.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  `true` if the operation completed successfully.
</ResponseField>

<ResponseField name="deletedConversations" type="number">
  The number of conversation records that were deleted.
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke({
    resource: "conversations",
    action: "clear-agent-data",
    data: {
      agentId: "agent-uuid",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/conversations \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "conversations",
      "action": "clear-agent-data",
      "data": {
        "agentId": "agent-uuid"
      }
    }'
  ```

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

***

## Error responses

| Status | Code               | Description                                    |
| ------ | ------------------ | ---------------------------------------------- |
| 400    | `VALIDATION_ERROR` | Missing required fields (e.g. conversation ID) |
| 403    | `FORBIDDEN`        | User does not own the genie (for sync)         |
| 404    | `NOT_FOUND`        | Conversation not found or access denied        |
| 500    | `INTERNAL_ERROR`   | Server error                                   |


# Demo Genies
Source: https://docs.helpgenie.ai/api-reference/demo-genies

Demo genie provisioning and lifecycle

Demo genies are specialized genie records used for showcase/demo workflows.

Supported actions: `all`, `list`, `get`, `create`, `provision`, `update`, `delete`.


# Document Edit Links
Source: https://docs.helpgenie.ai/api-reference/doc-edit-link

Share a document for external editing — no login required. Generate tokenised edit links, optionally secure them with a PIN, and let anyone with the link view or update the document's content.

Document edit links let you share a knowledge-base document as a standalone editing page. Anyone with the link can view the current content and save changes without a HelpGenie account. When a save is made, all genies that use the document are automatically updated.

**Access model:**

* **Owner actions** (`get`, `generate`, `set-pin`, `revoke`) — require a valid Bearer token. Only the document owner or an admin may manage a link.
* **Public actions** (`public-get`, `public-update`) — authenticated by the unguessable link token alone. No login required. A bearer token is accepted if present but not mandatory.

**PIN protection:** The owner can optionally set a 4–8 digit numeric PIN. Viewing is always frictionless — the PIN is checked only on Save. After 5 consecutive wrong PINs the Save action is locked for 15 minutes.

***

## Get edit link

Returns the current edit link for a document, or `null` if no link has been generated yet.

<ParamField type="string">
  Must be `"doc-edit-link"`
</ParamField>

<ParamField type="string">
  Must be `"get"`
</ParamField>

<ParamField type="string">
  The document UUID.
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="link" type="object | null">
      The edit link object, or `null` if no link has been generated.

      <Expandable title="properties">
        <ResponseField name="documentId" type="string">Document UUID.</ResponseField>
        <ResponseField name="token" type="string">The unguessable share token (\~43 characters).</ResponseField>
        <ResponseField name="path" type="string">App-relative path for the public editing page, e.g. `"/update/abc123..."`.</ResponseField>
        <ResponseField name="requiresPin" type="boolean">Whether a PIN must be entered to save changes.</ResponseField>
        <ResponseField name="lastUsedAt" type="string | null">ISO 8601 timestamp of the last successful save, or `null`.</ResponseField>
        <ResponseField name="createdAt" type="string">ISO 8601 creation timestamp.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke({
    resource: "doc-edit-link",
    action: "get",
    id: "770e8400-e29b-41d4-a716-446655440002",
  });
  ```

  ```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": "doc-edit-link",
      "action": "get",
      "id": "770e8400-e29b-41d4-a716-446655440002"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "link": {
        "documentId": "770e8400-e29b-41d4-a716-446655440002",
        "token": "abc123XYZ...",
        "path": "/update/abc123XYZ...",
        "requiresPin": false,
        "lastUsedAt": null,
        "createdAt": "2024-06-01T10:00:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

***

## Generate edit link

Creates a shareable edit link for a document. Idempotent — returns the existing link unless `rotate: true` is passed, which mints a fresh token and immediately invalidates any previously shared URL.

<ParamField type="string">
  Must be `"doc-edit-link"`
</ParamField>

<ParamField type="string">
  Must be `"generate"`
</ParamField>

<ParamField type="string">
  The document UUID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      When `true`, invalidates the current token and issues a new one. Any brute-force lockout is also reset. Use this to retire a leaked or shared-too-widely link.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="link" type="object">
      The edit link object (see [Get edit link](#get-edit-link) for shape).
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Returns HTTP 201 when a brand-new link is created for the first time, and HTTP 200 when returning or rotating an existing one.
</Note>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  // Generate (or retrieve) an edit link
  const response = await ApiService.invoke({
    resource: "doc-edit-link",
    action: "generate",
    id: "770e8400-e29b-41d4-a716-446655440002",
  });

  // Rotate the token
  const rotated = await ApiService.invoke({
    resource: "doc-edit-link",
    action: "generate",
    id: "770e8400-e29b-41d4-a716-446655440002",
    data: { rotate: true },
  });
  ```

  ```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": "doc-edit-link",
      "action": "generate",
      "id": "770e8400-e29b-41d4-a716-446655440002"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "link": {
        "documentId": "770e8400-e29b-41d4-a716-446655440002",
        "token": "abc123XYZ...",
        "path": "/update/abc123XYZ...",
        "requiresPin": false,
        "lastUsedAt": null,
        "createdAt": "2024-06-01T10:00:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

***

## Set PIN

Sets, changes, or clears the Save-gate PIN for an edit link. The PIN must be set before viewers can be required to enter it. Any change resets the brute-force lockout counter.

A link must already exist before a PIN can be set — call `generate` first.

<ParamField type="string">
  Must be `"doc-edit-link"`
</ParamField>

<ParamField type="string">
  Must be `"set-pin"`
</ParamField>

<ParamField type="string">
  The document UUID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string | null">
      A 4–8 digit numeric string to require on Save. Pass `null` or omit to remove the PIN (Save becomes frictionless).
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="link" type="object">
      The updated edit link object. `requiresPin` reflects the new state.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  // Set a PIN
  await ApiService.invoke({
    resource: "doc-edit-link",
    action: "set-pin",
    id: "770e8400-e29b-41d4-a716-446655440002",
    data: { pin: "1234" },
  });

  // Clear the PIN
  await ApiService.invoke({
    resource: "doc-edit-link",
    action: "set-pin",
    id: "770e8400-e29b-41d4-a716-446655440002",
    data: { pin: null },
  });
  ```

  ```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": "doc-edit-link",
      "action": "set-pin",
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "data": { "pin": "1234" }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "link": {
        "documentId": "770e8400-e29b-41d4-a716-446655440002",
        "token": "abc123XYZ...",
        "path": "/update/abc123XYZ...",
        "requiresPin": true,
        "lastUsedAt": null,
        "createdAt": "2024-06-01T10:00:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

***

## Revoke edit link

Permanently destroys a document's edit link. Anyone who follows the old URL immediately loses access. This is the owner's kill switch for a leaked or retired link.

<ParamField type="string">
  Must be `"doc-edit-link"`
</ParamField>

<ParamField type="string">
  Must be `"revoke"`
</ParamField>

<ParamField type="string">
  The document UUID.
</ParamField>

<ResponseField name="success" type="boolean">
  `true` if the link was deleted (or did not exist).
</ResponseField>

<Warning>
  Revocation is immediate and irreversible. The shared URL stops working instantly. Generate a new link to re-enable external editing.
</Warning>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  await ApiService.invoke({
    resource: "doc-edit-link",
    action: "revoke",
    id: "770e8400-e29b-41d4-a716-446655440002",
  });
  ```

  ```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": "doc-edit-link",
      "action": "revoke",
      "id": "770e8400-e29b-41d4-a716-446655440002"
    }'
  ```

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

***

## Public — view document

Resolves a link token and returns the document's current text content so an editor can pre-fill. Viewing is always frictionless — no PIN is required to read; the PIN (if any) only gates Save.

Any invalid or revoked token returns a `404` response uniformly, so this endpoint does not reveal which tokens exist.

<Note>
  No `Authorization` header is required. This action is public and authenticated purely by the link token.
</Note>

<ParamField type="string">
  Must be `"doc-edit-link"`
</ParamField>

<ParamField type="string">
  Must be `"public-get"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The link token from the edit link URL.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="documentId" type="string">Document UUID.</ResponseField>
    <ResponseField name="documentName" type="string">Human-readable document name.</ResponseField>
    <ResponseField name="content" type="string">The document's current text content.</ResponseField>
    <ResponseField name="requiresPin" type="boolean">Whether a PIN must be entered before saving.</ResponseField>
    <ResponseField name="agentNames" type="string[]">Names of genies that use this document.</ResponseField>
    <ResponseField name="updatedAt" type="string | null">ISO 8601 timestamp of the last content update.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke({
    resource: "doc-edit-link",
    action: "public-get",
    data: { token: "abc123XYZ..." },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "doc-edit-link",
      "action": "public-get",
      "data": { "token": "abc123XYZ..." }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "documentId": "770e8400-e29b-41d4-a716-446655440002",
      "documentName": "Product FAQ",
      "content": "Q: What are your hours?\nA: Monday–Friday 9am–5pm.",
      "requiresPin": true,
      "agentNames": ["Customer Support Bot"],
      "updatedAt": "2024-06-01T12:00:00.000Z"
    }
  }
  ```
</CodeGroup>

***

## Public — save document

Saves new content for the linked document. If the link has a PIN, `pin` must match before the save is accepted. On success, all genies that use this document are automatically updated with the new content.

<Note>
  No `Authorization` header is required. This action is public and authenticated purely by the link token.
</Note>

<ParamField type="string">
  Must be `"doc-edit-link"`
</ParamField>

<ParamField type="string">
  Must be `"public-update"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The link token from the edit link URL.
    </ParamField>

    <ParamField type="string">
      The new document content. Must be a non-empty string, maximum 1,000,000 characters.
    </ParamField>

    <ParamField type="string">
      Required when `requiresPin` is `true`. A 4–8 digit numeric string.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  `true` when the document was saved successfully.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean">`true`</ResponseField>
    <ResponseField name="updatedAt" type="string">ISO 8601 timestamp of the save.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke({
    resource: "doc-edit-link",
    action: "public-update",
    data: {
      token: "abc123XYZ...",
      content: "Updated document content...",
      pin: "1234", // only required if requiresPin is true
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "doc-edit-link",
      "action": "public-update",
      "data": {
        "token": "abc123XYZ...",
        "content": "Updated document content...",
        "pin": "1234"
      }
    }'
  ```

  ```json Response (success) theme={null}
  {
    "success": true,
    "data": {
      "success": true,
      "updatedAt": "2024-06-01T14:30:00.000Z"
    }
  }
  ```

  ```json Response (wrong PIN) theme={null}
  {
    "success": false,
    "error": {
      "code": "FORBIDDEN",
      "message": "Incorrect PIN",
      "status": 403,
      "attemptsRemaining": 4
    }
  }
  ```
</CodeGroup>

<Warning>
  After 5 consecutive wrong PIN attempts, the Save action is locked for 15 minutes. The lockout resets automatically after the timeout or when the owner rotates the token or changes the PIN.
</Warning>

***

## Error codes

| Code                  | Status | Description                                         |
| --------------------- | ------ | --------------------------------------------------- |
| `VALIDATION_ERROR`    | 400    | Missing required parameter or invalid PIN format    |
| `FORBIDDEN`           | 403    | Wrong PIN, or you do not own the document           |
| `NOT_FOUND`           | 404    | Document or link not found / token invalid          |
| `RATE_LIMIT_EXCEEDED` | 429    | PIN lockout in effect — too many incorrect attempts |
| `INTERNAL_ERROR`      | 500    | Unexpected server error                             |


# Document folders
Source: https://docs.helpgenie.ai/api-reference/document-folders

Organize knowledge base documents into folders

Document folders let you organize knowledge base documents into logical groups. Each folder has a name, optional color, icon, and a position for display ordering.

<Note>
  Standard users can only manage their own folders. Admin users can manage folders for any user by passing `adminMode: true` and a `userId`.
</Note>

***

## List all folders

Retrieves all folders for the authenticated user with full folder fields including `user_id` and `updated_at`.

<ParamField type="string">
  Must be `"document-folders"`
</ParamField>

<ParamField type="string">
  Must be `"all"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      Admin only. Enables cross-user access.
    </ParamField>

    <ParamField type="string">
      Admin only. Target user whose folders to retrieve.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="folders" type="array">
      <Expandable title="item properties">
        <ResponseField name="id" type="string">Folder UUID.</ResponseField>
        <ResponseField name="name" type="string">Folder name.</ResponseField>
        <ResponseField name="color" type="string">Hex color code.</ResponseField>
        <ResponseField name="icon" type="string">Icon identifier.</ResponseField>
        <ResponseField name="position" type="number">Display order position.</ResponseField>
        <ResponseField name="user_id" type="string">Owner user ID.</ResponseField>
        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
        <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number">
      Total number of folders.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("document-folders", "all");
  ```

  ```json Request body theme={null}
  {
    "resource": "document-folders",
    "action": "all"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "folders": [
        {
          "id": "folder_123",
          "name": "Policies",
          "color": "#3B82F6",
          "icon": "folder",
          "position": 0,
          "user_id": "user_123",
          "created_at": "2026-02-19T10:00:00.000Z",
          "updated_at": "2026-02-19T10:00:00.000Z"
        }
      ],
      "count": 1
    }
  }
  ```
</CodeGroup>

***

## List folders (compact)

Retrieves folders in a compact format optimized for dropdowns and select menus. Excludes `user_id` and `updated_at`.

<ParamField type="string">
  Must be `"document-folders"`
</ParamField>

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

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      Admin only. Enables cross-user access.
    </ParamField>

    <ParamField type="string">
      Admin only. Target user whose folders to retrieve.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="folders" type="array">
      <Expandable title="item properties">
        <ResponseField name="id" type="string">Folder UUID.</ResponseField>
        <ResponseField name="name" type="string">Folder name.</ResponseField>
        <ResponseField name="color" type="string">Hex color code.</ResponseField>
        <ResponseField name="icon" type="string">Icon identifier.</ResponseField>
        <ResponseField name="position" type="number">Display order position.</ResponseField>
        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number">
      Total number of folders.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("document-folders", "list");
  ```

  ```json Request body theme={null}
  {
    "resource": "document-folders",
    "action": "list"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "folders": [
        {
          "id": "folder_123",
          "name": "Policies",
          "color": "#3B82F6",
          "icon": "folder",
          "position": 0,
          "created_at": "2026-02-19T10:00:00.000Z"
        }
      ],
      "count": 1
    }
  }
  ```
</CodeGroup>

***

## Get folder

Retrieves a single folder by ID.

<ParamField type="string">
  Must be `"document-folders"`
</ParamField>

<ParamField type="string">
  Must be `"get"`
</ParamField>

<ParamField type="string">
  The folder UUID to retrieve.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      Admin only. Enables cross-user access.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="folder" type="object">
      <Expandable title="properties">
        <ResponseField name="id" type="string">Folder UUID.</ResponseField>
        <ResponseField name="name" type="string">Folder name.</ResponseField>
        <ResponseField name="color" type="string">Hex color code.</ResponseField>
        <ResponseField name="icon" type="string">Icon identifier.</ResponseField>
        <ResponseField name="position" type="number">Display order position.</ResponseField>
        <ResponseField name="user_id" type="string">Owner user ID.</ResponseField>
        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
        <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "document-folders",
    "get",
    "folder_123"
  );
  ```

  ```json Request body theme={null}
  {
    "resource": "document-folders",
    "action": "get",
    "id": "folder_123"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "folder": {
        "id": "folder_123",
        "name": "Policies",
        "color": "#3B82F6",
        "icon": "folder",
        "position": 0,
        "user_id": "user_123",
        "created_at": "2026-02-19T10:00:00.000Z",
        "updated_at": "2026-02-19T10:00:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

***

## Create folder

Creates a new document folder. The folder is automatically assigned the next available position.

<ParamField type="string">
  Must be `"document-folders"`
</ParamField>

<ParamField type="string">
  Must be `"create"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Folder display name.
    </ParamField>

    <ParamField type="string">
      Hex color code for the folder (for example `"#10B981"`).
    </ParamField>

    <ParamField type="string">
      Icon identifier (for example `"folder"`, `"briefcase"`).
    </ParamField>

    <ParamField type="string">
      Admin only. Create the folder for a specific user.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="folder" type="object">
      The newly created folder with all fields including auto-assigned `position`.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "document-folders",
    "create",
    undefined,
    {
      name: "Training Materials",
      color: "#10B981",
      icon: "folder",
    }
  );
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/document-folders \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "create",
      "data": {
        "name": "Training Materials",
        "color": "#10B981",
        "icon": "folder"
      }
    }'
  ```

  ```json Request body theme={null}
  {
    "resource": "document-folders",
    "action": "create",
    "data": {
      "name": "Training Materials",
      "color": "#10B981",
      "icon": "folder"
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "folder": {
        "id": "folder_456",
        "name": "Training Materials",
        "color": "#10B981",
        "icon": "folder",
        "position": 1,
        "user_id": "user_123",
        "created_at": "2026-02-19T10:05:00.000Z",
        "updated_at": "2026-02-19T10:05:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

***

## Update folder

Updates an existing folder's properties. Only the fields you provide are changed.

<ParamField type="string">
  Must be `"document-folders"`
</ParamField>

<ParamField type="string">
  Must be `"update"`
</ParamField>

<ParamField type="string">
  The folder UUID to update.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Updated folder name.
    </ParamField>

    <ParamField type="string">
      Updated hex color code.
    </ParamField>

    <ParamField type="string">
      Updated icon identifier.
    </ParamField>

    <ParamField type="number">
      Updated display position.
    </ParamField>

    <ParamField type="boolean">
      Admin only. Enables cross-user access.
    </ParamField>

    <ParamField type="string">
      Admin only. Target user who owns the folder.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="folder" type="object">
      The updated folder with all current field values.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "document-folders",
    "update",
    "folder_123",
    {
      name: "Company Policies",
      color: "#F59E0B",
      icon: "briefcase",
    }
  );
  ```

  ```json Request body theme={null}
  {
    "resource": "document-folders",
    "action": "update",
    "id": "folder_123",
    "data": {
      "name": "Company Policies",
      "color": "#F59E0B",
      "icon": "briefcase"
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "folder": {
        "id": "folder_123",
        "name": "Company Policies",
        "color": "#F59E0B",
        "icon": "briefcase",
        "position": 0,
        "user_id": "user_123",
        "created_at": "2026-02-19T10:00:00.000Z",
        "updated_at": "2026-02-19T10:10:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

***

## Delete folder

Permanently deletes a folder. Documents in the folder are not deleted; they become uncategorized.

<Note>
  When a folder is deleted, any documents inside it are **unlinked**, not deleted. Their `folder_id` is set to `null`, making them appear as uncategorized in the knowledge base. You do not need to manually move documents before deleting a folder.
</Note>

<ParamField type="string">
  Must be `"document-folders"`
</ParamField>

<ParamField type="string">
  Must be `"delete"`
</ParamField>

<ParamField type="string">
  The folder UUID to delete.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      Admin only. Enables cross-user access.
    </ParamField>

    <ParamField type="string">
      Admin only. Target user who owns the folder.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean">Operation succeeded.</ResponseField>
    <ResponseField name="message" type="string">Confirmation message.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "document-folders",
    "delete",
    "folder_123"
  );
  ```

  ```json Request body theme={null}
  {
    "resource": "document-folders",
    "action": "delete",
    "id": "folder_123"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "success": true,
      "message": "Folder deleted successfully"
    }
  }
  ```
</CodeGroup>

***

## Reorder folders

Updates the display order of folders based on an ordered array of folder IDs. The position of each folder is set to its index in the array.

<ParamField type="string">
  Must be `"document-folders"`
</ParamField>

<ParamField type="string">
  Must be `"reorder"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string[]">
      Ordered array of folder UUIDs. The first ID gets position 0, the second gets position 1, and so on.
    </ParamField>

    <ParamField type="boolean">
      Admin only. Enables cross-user access.
    </ParamField>

    <ParamField type="string">
      Admin only. Target user whose folders to reorder.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean">Operation succeeded.</ResponseField>
    <ResponseField name="message" type="string">Confirmation message.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "document-folders",
    "reorder",
    undefined,
    {
      folderIds: ["folder_456", "folder_123", "folder_789"],
    }
  );
  ```

  ```json Request body theme={null}
  {
    "resource": "document-folders",
    "action": "reorder",
    "data": {
      "folderIds": ["folder_456", "folder_123", "folder_789"]
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "success": true,
      "message": "Folders reordered successfully"
    }
  }
  ```
</CodeGroup>

***

## Get folder document counts

Returns the number of documents in each folder. Useful for displaying counts in folder lists without fetching all documents.

<ParamField type="string">
  Must be `"document-folders"`
</ParamField>

<ParamField type="string">
  Must be `"counts"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      Admin only. Enables cross-user access.
    </ParamField>

    <ParamField type="string">
      Admin only. Target user whose folder counts to retrieve.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="counts" type="object">
      An object where keys are folder IDs and values are document counts.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("document-folders", "counts");
  ```

  ```json Request body theme={null}
  {
    "resource": "document-folders",
    "action": "counts"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "counts": {
        "folder_123": 5,
        "folder_456": 2
      }
    }
  }
  ```
</CodeGroup>

***

## Error codes

| Code               | Status | Description                                                    |
| ------------------ | ------ | -------------------------------------------------------------- |
| `UNAUTHORIZED`     | 401    | Missing or invalid authentication token                        |
| `FORBIDDEN`        | 403    | Only admins can manage folders for other users                 |
| `NOT_FOUND`        | 404    | Folder not found                                               |
| `VALIDATION_ERROR` | 400    | Missing or invalid parameters (for example folder ID required) |
| `INTERNAL_ERROR`   | 500    | Server-side error                                              |


# Email Logs
Source: https://docs.helpgenie.ai/api-reference/email-logs

Delivery log retrieval for outbound emails

Use `email-logs` to inspect status and failures for sent emails.

Supported actions: `all`, `list`, `get`.


# Email Templates
Source: https://docs.helpgenie.ai/api-reference/email-templates

Manage email template configurations for conversation reports and workflows

Use `email-templates` to manage per-user and per-genie email template configurations. Templates control the layout and content of outgoing emails such as conversation reports.

<Note>
  Standard users manage their own templates. Admin users can read or write templates for any user by passing `adminMode: true` and the target `userId`. Team members write to the team owner's templates by default; pass `personal: true` to write to your own account instead.
</Note>

***

## Get effective config

Returns the resolved template configuration for a given type. Looks up in priority order: genie-specific template → user-level template → system default. Returns `null` if no configuration exists at any level.

<ParamField type="string">
  Must be `"email-templates"`
</ParamField>

<ParamField type="string">
  Must be `"getConfig"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Template type identifier (for example `"report"`).
    </ParamField>

    <ParamField type="string">
      Genie UUID. When provided, a genie-specific template is checked first before falling back to the user-level template.
    </ParamField>

    <ParamField type="string">
      Admin only. Resolve the config for this user ID instead of the authenticated user.
    </ParamField>

    <ParamField type="boolean">
      Admin only. Must be `true` to use the `userId` parameter.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="config" type="object | null">
      The resolved template configuration object, or `null` if no template is configured at any level.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("email-templates", "getConfig", undefined, {
    type: "report",
    agent_id: "550e8400-e29b-41d4-a716-446655440000",
  });
  const config = response?.config;
  ```

  ```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": "email-templates",
      "action": "getConfig",
      "data": {
        "type": "report",
        "agent_id": "550e8400-e29b-41d4-a716-446655440000"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "config": {
        "subject": "Your conversation summary",
        "headerColor": "#4E9CFF",
        "logoUrl": "https://storage.example.com/logo.png"
      }
    }
  }
  ```
</CodeGroup>

***

## List templates

Returns a paginated list of email templates for the authenticated user, optionally filtered by type or genie.

<ParamField type="string">
  Must be `"email-templates"`
</ParamField>

<ParamField type="string">
  Must be `"list"` or `"all"` (both return the same result).
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Results per page. Maximum 500.
    </ParamField>

    <ParamField type="number">
      Number of results to skip.
    </ParamField>

    <ParamField type="string">
      Filter by template type.
    </ParamField>

    <ParamField type="string">
      Filter by genie UUID. Pass `null` to return only templates with no genie association.
    </ParamField>

    <ParamField type="string">
      Admin only. List templates for this user ID.
    </ParamField>

    <ParamField type="boolean">
      Admin only. Must be `true` to use the `userId` parameter.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="items" type="array">
      <Expandable title="item properties">
        <ResponseField name="id" type="string">Template UUID.</ResponseField>
        <ResponseField name="user_id" type="string">Owner user ID.</ResponseField>
        <ResponseField name="agent_id" type="string | null">Genie UUID this template is scoped to, or `null` for a user-level template.</ResponseField>
        <ResponseField name="agent_name" type="string | null">Genie display name, if `agent_id` is set.</ResponseField>
        <ResponseField name="type" type="string">Template type identifier.</ResponseField>
        <ResponseField name="config" type="object">Template configuration object.</ResponseField>
        <ResponseField name="is_default" type="boolean">Whether this is a system-default template.</ResponseField>
        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number">Total matching templates.</ResponseField>
    <ResponseField name="limit" type="number">Applied limit.</ResponseField>
    <ResponseField name="offset" type="number">Applied offset.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("email-templates", "list", undefined, {
    limit: 50,
    offset: 0,
    type: "report",
  });
  ```

  ```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": "email-templates",
      "action": "list",
      "data": { "limit": 50, "offset": 0, "type": "report" }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "items": [
        {
          "id": "tpl-uuid-123",
          "user_id": "usr-uuid-456",
          "agent_id": null,
          "agent_name": null,
          "type": "report",
          "config": { "subject": "Your conversation summary" },
          "is_default": false,
          "created_at": "2024-01-15T10:30:00.000Z"
        }
      ],
      "count": 1,
      "limit": 50,
      "offset": 0
    }
  }
  ```
</CodeGroup>

***

## Get template

Retrieves a single email template by ID.

<ParamField type="string">
  Must be `"email-templates"`
</ParamField>

<ParamField type="string">
  Must be `"get"`
</ParamField>

<ParamField type="string">
  The template UUID.
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="template" type="object">
      The full template object. Same shape as list items above, plus an embedded `agent` object when `agent_id` is set.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("email-templates", "get", "tpl-uuid-123");
  const template = response?.template;
  ```

  ```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": "email-templates",
      "action": "get",
      "id": "tpl-uuid-123"
    }'
  ```
</CodeGroup>

***

## Create template

Creates a new email template record.

<ParamField type="string">
  Must be `"email-templates"`
</ParamField>

<ParamField type="string">
  Must be `"create"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Template type identifier.
    </ParamField>

    <ParamField type="object">
      Template configuration object.
    </ParamField>

    <ParamField type="string">
      Genie UUID. When provided, the template is scoped to that genie only.
    </ParamField>

    <ParamField type="boolean">
      Whether to mark this as a default template.
    </ParamField>

    <ParamField type="boolean">
      Team members only. Pass `true` to create the template under your own account instead of the team owner's account.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="template" type="object">
      The newly created template.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("email-templates", "create", undefined, {
    type: "report",
    config: { subject: "Custom report subject" },
    agent_id: "550e8400-e29b-41d4-a716-446655440000",
  });
  ```

  ```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": "email-templates",
      "action": "create",
      "data": {
        "type": "report",
        "config": { "subject": "Custom report subject" },
        "agent_id": "550e8400-e29b-41d4-a716-446655440000"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "template": {
        "id": "tpl-new-uuid",
        "user_id": "usr-uuid-456",
        "agent_id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "report",
        "config": { "subject": "Custom report subject" },
        "is_default": false,
        "created_at": "2024-01-15T11:00:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

***

## Update template

Upserts a template identified by `type` and optionally `agent_id`. If a matching template already exists it is updated; otherwise a new one is created. Use `create` when you need the returned template object — `update` only returns the ID.

<ParamField type="string">
  Must be `"email-templates"`
</ParamField>

<ParamField type="string">
  Must be `"update"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Template type identifier.
    </ParamField>

    <ParamField type="object">
      Replacement configuration. The entire config is replaced, not merged.
    </ParamField>

    <ParamField type="string">
      Genie UUID. Scopes the upsert to a genie-specific template. Omit to target the user-level template for this type.
    </ParamField>

    <ParamField type="boolean">
      Team members only. Pass `true` to write to your own account instead of the team owner's account.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string | number">ID of the updated or created template.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("email-templates", "update", undefined, {
    type: "report",
    config: { subject: "Updated subject line" },
  });
  ```

  ```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": "email-templates",
      "action": "update",
      "data": {
        "type": "report",
        "config": { "subject": "Updated subject line" }
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": { "id": "tpl-uuid-123" }
  }
  ```
</CodeGroup>

***

## Delete template

Permanently deletes an email template by ID.

<ParamField type="string">
  Must be `"email-templates"`
</ParamField>

<ParamField type="string">
  Must be `"delete"`
</ParamField>

<ParamField type="string">
  The template UUID to delete.
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("email-templates", "delete", "tpl-uuid-123");
  ```

  ```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": "email-templates",
      "action": "delete",
      "id": "tpl-uuid-123"
    }'
  ```
</CodeGroup>

***

## Clone default template

Copies the system-default template of a given type into the user's account. If the user already has a template of that type, its config is replaced with the default. Returns the cloned config.

<ParamField type="string">
  Must be `"email-templates"`
</ParamField>

<ParamField type="string">
  Must be `"cloneDefault"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Template type to clone the default for.
    </ParamField>

    <ParamField type="string">
      Genie UUID. When provided, the clone is scoped to that genie.
    </ParamField>

    <ParamField type="boolean">
      Team members only. Pass `true` to clone into your own account rather than the team owner's account.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="config" type="object">The config copied from the system default.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("email-templates", "cloneDefault", undefined, {
    type: "report",
  });
  const config = response?.config;
  ```

  ```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": "email-templates",
      "action": "cloneDefault",
      "data": { "type": "report" }
    }'
  ```
</CodeGroup>

***

## Copy logo

Copies a logo image from an external storage location into HelpGenie-managed storage and returns the new URL. If the image is already in internal storage or the copy fails, the original URL is returned unchanged.

<ParamField type="string">
  Must be `"email-templates"`
</ParamField>

<ParamField type="string">
  Must be `"copyLogo"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Public URL of the logo to copy.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="logoUrl" type="string">
      The new internal URL, or the original URL if the copy was skipped or failed.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Error codes

| Code               | Status | Description                                |
| ------------------ | ------ | ------------------------------------------ |
| `UNAUTHORIZED`     | 401    | Missing or invalid authentication token    |
| `FORBIDDEN`        | 403    | User lacks permission for the operation    |
| `NOT_FOUND`        | 404    | Template not found                         |
| `VALIDATION_ERROR` | 400    | Missing required fields (`type`, `config`) |
| `INVALID_ACTION`   | 400    | Unknown action                             |
| `INTERNAL_ERROR`   | 500    | Server-side error                          |


# Escalation Webhooks
Source: https://docs.helpgenie.ai/api-reference/escalation-webhooks

Configure webhooks that fire when a Genie escalates a conversation to a human agent.

Each Genie can have one active escalation webhook. When a call is escalated, HelpGenie sends a signed POST request to the configured URL with a customisable payload.

Webhook payloads are HMAC-SHA256 signed using your `secret`. The signature is sent in the `X-HelpGenie-Signature` header by default, or in the header name you specify via `secret_header`.

***

## Actions

### `get`

Returns the escalation webhook configured for a Genie, or `null` if none exists.

**Parameters**

| Field     | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `agentId` | string | Yes      | Genie UUID  |

**Response**

```json theme={null}
{
  "id": "webhook-uuid",
  "agent_id": "agent-uuid",
  "url": "https://example.com/webhook",
  "secret": "••••••••",
  "secret_header": "X-HelpGenie-Signature",
  "custom_fields": [],
  "is_active": true,
  "updated_at": "2024-01-01T00:00:00Z"
}
```

Returns `null` if no webhook is configured.

***

### `upsert`

Creates or updates the escalation webhook for a Genie. Only one webhook per Genie is supported — calling this again replaces the existing configuration.

**Parameters**

| Field           | Type    | Required | Description                                                                                                                                                         |
| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agentId`       | string  | Yes      | Genie UUID                                                                                                                                                          |
| `url`           | string  | Yes      | HTTPS endpoint to POST to on escalation                                                                                                                             |
| `secret`        | string  | No       | Shared secret used to sign the payload (HMAC-SHA256)                                                                                                                |
| `secret_header` | string  | No       | Header name for the signature, defaults to `X-HelpGenie-Signature`                                                                                                  |
| `custom_fields` | array   | No       | Custom payload field definitions. Each item can be a string key or an object `{ key, hint, useForSignature }`. When empty, a default set of standard fields is used |
| `is_active`     | boolean | No       | Whether the webhook is active, defaults to `true`                                                                                                                   |

**Default payload fields** (used when `custom_fields` is empty):

`eventId`, `eventType`, `timestamp`, `callerNumber`, `callSid`, `reason`, `summary`, `agentSessionId`

**Response** — the saved webhook row.

```json theme={null}
{
  "id": "webhook-uuid",
  "agent_id": "agent-uuid",
  "url": "https://example.com/webhook",
  "is_active": true
}
```

***

### `delete`

Removes the escalation webhook for a Genie. No-ops silently if no webhook exists.

**Parameters**

| Field     | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `agentId` | string | Yes      | Genie UUID  |

**Response**

```json theme={null}
{ "success": true }
```

***

### `test`

Sends a test POST request to the webhook URL with a dummy escalation payload. Validates that the endpoint is reachable and returns the HTTP status and response body. Requires the webhook to be active.

**Parameters**

| Field     | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `agentId` | string | Yes      | Genie UUID  |

**Response**

```json theme={null}
{
  "payload": { /* test payload that was sent */ },
  "signature": "abc123...",
  "signatureHeader": "X-HelpGenie-Signature",
  "signed": true,
  "result": {
    "status": 200,
    "body": "ok"
  }
}
```

If the request fails at the network level, `result` will contain an `error` string instead of `status`/`body`.

***

## Error codes

| Code               | Meaning                                    |
| ------------------ | ------------------------------------------ |
| `VALIDATION_ERROR` | Missing required parameter                 |
| `NOT_FOUND`        | No active webhook found (test action only) |
| `UNAUTHORIZED`     | You do not have access to this Genie       |
| `INTERNAL_ERROR`   | Unexpected server error                    |


# Genie Access
Source: https://docs.helpgenie.ai/api-reference/genie-access

Manage access control for private Genies — create shareable access links, grant direct user access, and handle inbound access requests.

Genie Access gives you fine-grained control over who can interact with a private Genie. Access is tracked in two ways:

* **Access grants** — tokenised links with optional use-count limits and expiry dates, shareable with anyone.
* **Agent users** — direct per-user access records tied to a specific HelpGenie account.

When a visitor requests access to a private Genie, an `agent_access_requests` record is created and the Genie owner can approve or deny it via `resolve`.

***

## Actions

### `all`

Returns all users who have been granted direct access to a Genie.

**Parameters**

| Field | Type   | Required | Description                       |
| ----- | ------ | -------- | --------------------------------- |
| `id`  | string | Yes      | Genie UUID (passed as request ID) |

**Response**

```json theme={null}
{
  "users": [
    {
      "agent_id": "agent-uuid",
      "user_id": "user-uuid",
      "granted_by": "owner-uuid",
      "expires_at": null,
      "created_at": "2024-01-01T00:00:00Z",
      "profile": { "id": "user-uuid", "full_name": "Jane Doe", "email": "jane@example.com", "avatar_url": null }
    }
  ]
}
```

***

### `list`

Returns access grant links (token-based access, not per-user). When no Genie is specified, returns grants for all genies you own.

**Parameters**

| Field          | Type   | Required | Description                                                       |
| -------------- | ------ | -------- | ----------------------------------------------------------------- |
| `id`           | string | No       | Genie UUID (passed as request ID). Filters results to this genie. |
| `data.agentId` | string | No       | Alternative to `id` — Genie UUID passed in the request body.      |

When neither `id` nor `data.agentId` is provided, non-admin users receive grants for all genies they own. Admin users receive all grants across the platform.

**Response**

```json theme={null}
{
  "grants": [
    {
      "id": 1,
      "agent_id": "agent-uuid",
      "max_uses": 10,
      "use_count": 3,
      "expires_at": "2025-01-01T00:00:00Z",
      "last_used_at": "2024-06-01T00:00:00Z",
      "granted_by": "owner-uuid",
      "created_at": "2024-01-01T00:00:00Z",
      "label": "ab12cd",
      "token": "64-char-token"
    }
  ]
}
```

`token` is omitted for expired grants.

***

### `list-team-access`

Returns direct per-user access records for a Genie, with profile data for each user.

**Parameters**

| Field | Type   | Required | Description                       |
| ----- | ------ | -------- | --------------------------------- |
| `id`  | string | Yes      | Genie UUID (passed as request ID) |

**Response**

```json theme={null}
{
  "access": [
    {
      "agent_id": "agent-uuid",
      "user_id": "user-uuid",
      "granted_by": "owner-uuid",
      "expires_at": null,
      "created_at": "2024-01-01T00:00:00Z",
      "profile": { "id": "user-uuid", "full_name": "Jane Doe", "email": "jane@example.com", "avatar_url": null }
    }
  ]
}
```

***

### `create`

Creates a new access grant link for a Genie. Returns the full token (only shown once).

**Parameters**

| Field        | Type   | Required | Description                                                                 |
| ------------ | ------ | -------- | --------------------------------------------------------------------------- |
| `id`         | string | Yes      | Genie UUID (passed as request ID)                                           |
| `max_uses`   | number | No       | Maximum number of times the link can be used. `0` means unlimited (default) |
| `expires_at` | string | No       | ISO 8601 expiry datetime                                                    |

**Response** — `201`

```json theme={null}
{
  "grant": {
    "id": 1,
    "agent_id": "agent-uuid",
    "max_uses": 0,
    "use_count": 0,
    "expires_at": null,
    "granted_by": "owner-uuid",
    "created_at": "2024-01-01T00:00:00Z",
    "token": "64-char-token-shown-only-once"
  }
}
```

***

### `update`

Updates an existing access grant (use limit or expiry).

**Parameters**

| Field        | Type           | Required | Description                                     |
| ------------ | -------------- | -------- | ----------------------------------------------- |
| `id`         | string         | Yes      | Grant ID (numeric, passed as request ID)        |
| `max_uses`   | number         | No       | New maximum use count                           |
| `expires_at` | string \| null | No       | New expiry datetime, or `null` to remove expiry |

**Response**

```json theme={null}
{
  "grant": { /* updated grant row */ }
}
```

***

### `delete`

Deletes an access grant link. Anyone using the link after deletion will lose access.

**Parameters**

| Field | Type   | Required | Description                              |
| ----- | ------ | -------- | ---------------------------------------- |
| `id`  | string | Yes      | Grant ID (numeric, passed as request ID) |

**Response**

```json theme={null}
{ "deleted": true }
```

***

### `update-user`

Updates the expiry date for a specific user's direct access to a Genie.

**Parameters**

| Field        | Type           | Required | Description                                             |
| ------------ | -------------- | -------- | ------------------------------------------------------- |
| `agentId`    | string         | Yes      | Genie UUID                                              |
| `userId`     | string         | Yes      | User UUID                                               |
| `expires_at` | string \| null | No       | New expiry datetime, or `null` to make access permanent |

**Response**

```json theme={null}
{
  "agentUser": {
    "agent_id": "agent-uuid",
    "user_id": "user-uuid",
    "granted_by": "owner-uuid",
    "expires_at": "2025-01-01T00:00:00Z",
    "created_at": "2024-01-01T00:00:00Z"
  }
}
```

***

### `delete-user`

Revokes a specific user's direct access to a Genie.

**Parameters**

| Field     | Type   | Required | Description         |
| --------- | ------ | -------- | ------------------- |
| `agentId` | string | Yes      | Genie UUID          |
| `userId`  | string | Yes      | User UUID to revoke |

**Response**

```json theme={null}
{ "deleted": true }
```

***

### `requests`

Returns all inbound access requests for a Genie (visitors who clicked "Request access").

**Parameters**

| Field | Type   | Required | Description                       |
| ----- | ------ | -------- | --------------------------------- |
| `id`  | string | Yes      | Genie UUID (passed as request ID) |

**Response**

```json theme={null}
{
  "requests": [
    {
      "id": "request-uuid",
      "agent_id": "agent-uuid",
      "email": "requester@example.com",
      "requested_at": "2024-01-01T00:00:00Z",
      "resolved_at": null,
      "solution": null,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}
```

***

### `resolve`

Approves or denies an access request. On approval, the requester receives an email with an access link and (if they have a HelpGenie account) is added to the Genie's `agent_users`.

**Parameters**

| Field        | Type   | Required | Description                                   |
| ------------ | ------ | -------- | --------------------------------------------- |
| `requestId`  | string | Yes      | Access request UUID                           |
| `solution`   | string | Yes      | `"approved"` or `"denied"`                    |
| `expires_at` | string | No       | Expiry for the granted access (approval only) |

**Response**

```json theme={null}
{
  "resolved": true,
  "solution": "approved"
}
```

***

## Error codes

| Code               | Meaning                                                |
| ------------------ | ------------------------------------------------------ |
| `VALIDATION_ERROR` | Missing required parameter or request already resolved |
| `NOT_FOUND`        | Grant or access request not found                      |
| `FORBIDDEN`        | You do not own this Genie                              |
| `AGENT_NOT_FOUND`  | Genie does not exist                                   |
| `INTERNAL_ERROR`   | Unexpected server error                                |


# Genie Documents
Source: https://docs.helpgenie.ai/api-reference/genie-documents

Generate polished, ready-to-share documents from your Genie's knowledge base — FAQs, how-to guides, and one-pagers, all grounded in your own content.

Genie Documents lets you produce professionally written documents directly from the knowledge base attached to a Genie. You choose a template, select the source documents to draw from, and receive a structured, print-ready result in seconds.

All generated content is grounded strictly in the source material you provide — no facts are invented. The output is structured as an ordered list of sections, each with a heading and body, ready to render or export.

***

## Generate document

Produces a structured document from one or more knowledge-base documents using a Smart template. Only documents you own (or public documents) can be used as sources.

<ParamField type="string">
  Must be `"genie-documents"`
</ParamField>

<ParamField type="string">
  Must be `"generate"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The Genie UUID. Used to scope the request to a specific assistant.
    </ParamField>

    <ParamField type="string">
      The document template to use. One of:

      * `"faq"` — Frequently Asked Questions sheet (6–12 Q\&A pairs)
      * `"how-to"` — Step-by-step guide with an intro and next-steps section
      * `"one-pager"` — Concise 4–6 section overview of your business
    </ParamField>

    <ParamField type="string[]">
      Array of knowledge-base document UUIDs to use as source material. At least one document is required. Documents are combined up to an internal character limit; the largest documents are trimmed first if the total exceeds the limit.
    </ParamField>

    <ParamField type="string">
      Optional plain-text description of the document's focus (e.g. `"returning customer onboarding"`). When omitted, the template covers the most broadly useful information from the source material.
    </ParamField>

    <ParamField type="string">
      Display name of the business or assistant. Used to address the reader in the generated content. Defaults to `"your business"` if omitted.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="document" type="object">
      The generated document.

      <Expandable title="properties">
        <ResponseField name="title" type="string">Document title.</ResponseField>
        <ResponseField name="subtitle" type="string">Optional one-line subtitle or tagline. May be an empty string.</ResponseField>
        <ResponseField name="template" type="string">The template key that was used (`"faq"`, `"how-to"`, or `"one-pager"`).</ResponseField>

        <ResponseField name="sections" type="array">
          Ordered content sections.

          <Expandable title="item properties">
            <ResponseField name="heading" type="string">Section heading (or the question text for FAQs).</ResponseField>
            <ResponseField name="body" type="string">Section content as plain text. Paragraphs are separated by blank lines. Bullet points start with `"- "` and numbered steps start with `"1. "`.</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="meta" type="object">
      Generation metadata.

      <Expandable title="properties">
        <ResponseField name="sourceDocuments" type="string[]">Names of documents that contributed content to the output.</ResponseField>
        <ResponseField name="skippedDocuments" type="string[]">Names of documents that were skipped (no readable content yet, or access denied).</ResponseField>
        <ResponseField name="truncated" type="boolean">Whether any document content was trimmed to fit within the generation limit.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke({
    resource: "genie-documents",
    action: "generate",
    data: {
      agentId: "550e8400-e29b-41d4-a716-446655440000",
      template: "faq",
      documentIds: [
        "770e8400-e29b-41d4-a716-446655440002",
        "880e8400-e29b-41d4-a716-446655440003",
      ],
      purpose: "common questions from new customers",
      genieName: "Acme Support",
    },
  });
  ```

  ```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": "genie-documents",
      "action": "generate",
      "data": {
        "agentId": "550e8400-e29b-41d4-a716-446655440000",
        "template": "faq",
        "documentIds": [
          "770e8400-e29b-41d4-a716-446655440002",
          "880e8400-e29b-41d4-a716-446655440003"
        ],
        "purpose": "common questions from new customers",
        "genieName": "Acme Support"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "document": {
        "title": "Frequently Asked Questions",
        "subtitle": "Everything a new customer needs to know",
        "template": "faq",
        "sections": [
          {
            "heading": "What are your business hours?",
            "body": "We're open Monday through Friday, 9am to 5pm. Our team typically responds to messages within one business day."
          },
          {
            "heading": "How do I get started?",
            "body": "Simply create an account on our website and follow the setup wizard. The whole process takes under five minutes.\n\n1. Visit our website and click \"Sign up\"\n2. Enter your business details\n3. Connect your first channel"
          }
        ]
      },
      "meta": {
        "sourceDocuments": ["Product Overview", "Support Handbook"],
        "skippedDocuments": [],
        "truncated": false
      }
    }
  }
  ```
</CodeGroup>

***

## Save document

Persists a generated document as a permanent knowledge-base record linked to the specified Genie. Use this after `generate` to store the result so it can be managed, published, and surfaced on the Genie's Help Hub.

New documents are created as **private** (`is_public: false`) and are not pushed to the Genie's knowledge base automatically. Publishing is a separate action through the knowledge-base update path.

Pass `id` to update an existing branded document. Omit `id` to create a new one.

<ParamField type="string">
  Must be `"genie-documents"`
</ParamField>

<ParamField type="string">
  Must be `"save"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The Genie UUID. The document is linked to this Genie on save.
    </ParamField>

    <ParamField type="string">
      The document template key. One of `"faq"`, `"how-to"`, or `"one-pager"`. Must match the template used during generation.
    </ParamField>

    <ParamField type="string">
      Document title shown in the knowledge library and on the Help Hub.
    </ParamField>

    <ParamField type="array">
      Ordered content sections. At least one section is required. Maximum 40 sections.

      <Expandable title="item properties">
        <ParamField type="string">Section heading. Headings that end with `?` are automatically indexed as questions on the Help Hub.</ParamField>
        <ParamField type="string">Section body text. Maximum 12,000 characters per section.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      UUID of an existing branded document to update. When omitted a new document is created.
    </ParamField>

    <ParamField type="string">
      Optional subtitle shown below the title on the Help Hub guide card.
    </ParamField>

    <ParamField type="string">
      Optional format variant key (e.g. `"compact"`) passed through for client-side rendering. Not interpreted by the server.
    </ParamField>

    <ParamField type="string">
      Optional plain-text description of the document's focus, stored in metadata.
    </ParamField>

    <ParamField type="string[]">
      UUIDs of the knowledge-base documents used as source material during generation. Stored in metadata for reference. Maximum 50 IDs.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="document" type="object">
  The saved document row.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Document UUID.</ResponseField>
    <ResponseField name="name" type="string">Document title.</ResponseField>
    <ResponseField name="user_id" type="string">Owner user ID.</ResponseField>
    <ResponseField name="source_type" type="string">Always `"genie-document"` for documents saved through this action.</ResponseField>
    <ResponseField name="is_public" type="boolean">Always `false` on save. Publish separately through the knowledge-base API.</ResponseField>
    <ResponseField name="status" type="string">Always `"completed"` after a successful save.</ResponseField>
    <ResponseField name="metadata" type="object">Document metadata including `name`, `description`, `answers` (questions extracted from section headings), and the full `genie_document` structure.</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
    <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created" type="boolean">
  `true` when a new document was created; `false` when an existing document was updated.
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke({
    resource: "genie-documents",
    action: "save",
    data: {
      agentId: "550e8400-e29b-41d4-a716-446655440000",
      template: "faq",
      title: "Frequently Asked Questions",
      subtitle: "Everything a new customer needs to know",
      sections: [
        {
          heading: "What are your business hours?",
          body: "We're open Monday through Friday, 9am to 5pm.",
        },
        {
          heading: "How do I get started?",
          body: "Create an account and follow the setup wizard.",
        },
      ],
      sourceDocumentIds: [
        "770e8400-e29b-41d4-a716-446655440002",
      ],
    },
  });
  // response.created === true → new document
  // response.document.id   → UUID to use for subsequent updates
  ```

  ```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": "genie-documents",
      "action": "save",
      "data": {
        "agentId": "550e8400-e29b-41d4-a716-446655440000",
        "template": "faq",
        "title": "Frequently Asked Questions",
        "sections": [
          { "heading": "What are your business hours?", "body": "Monday–Friday, 9am–5pm." }
        ]
      }
    }'
  ```

  ```json Response (new document) theme={null}
  {
    "success": true,
    "data": {
      "document": {
        "id": "990e8400-e29b-41d4-a716-446655440004",
        "name": "Frequently Asked Questions",
        "source_type": "genie-document",
        "is_public": false,
        "status": "completed",
        "created_at": "2024-06-26T10:00:00.000Z",
        "updated_at": "2024-06-26T10:00:00.000Z"
      },
      "created": true
    }
  }
  ```
</CodeGroup>

<Note>
  Section headings that end with `?` are automatically extracted and stored as indexed questions. These questions appear on the Genie's Help Hub question band when the document is published.
</Note>

***

## Templates

| Template     | Key           | Description                                                                                                                        |
| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| FAQ Sheet    | `"faq"`       | 6–12 question-and-answer pairs written in the customer's voice. Each section heading is the question; the body is a direct answer. |
| How-To Guide | `"how-to"`    | Step-by-step walkthrough with a short intro, ordered sections, and an optional next-steps section.                                 |
| One-Pager    | `"one-pager"` | Concise 4–6 section overview covering what the business offers, who it is for, and the key things a customer should know.          |

***

## Error codes

| Code               | Status | Description                                                                                                                                                               |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VALIDATION_ERROR` | 400    | Missing required fields (`agentId`, `template`, `title`, `sections`, `documentIds`), invalid template key, no sections supplied, or trying to save a non-branded document |
| `NOT_FOUND`        | 404    | Specified document `id` not found (save), or none of the source document IDs exist (generate)                                                                             |
| `UNAUTHORIZED`     | 401    | Access to the Genie or document is denied                                                                                                                                 |
| `INTERNAL_ERROR`   | 500    | Document generation failed, returned no content, or storage upload failed                                                                                                 |


# Genie groups
Source: https://docs.helpgenie.ai/api-reference/genie-groups

Organize genies into groups for easier management

Genie groups let you organize your genies into logical categories such as "Sales Team" or "Support Team". Each group has a name, optional description, and a position for display ordering. Genies can be assigned to a group via the sync action.

<Note>
  Standard users can only manage their own groups. Admin users can manage groups for any user by passing a `userId`.
</Note>

***

## List groups

Retrieves all groups for the authenticated user.

<ParamField type="string">
  Must be `"genie-groups"`
</ParamField>

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

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      Admin only. Enables cross-user access.
    </ParamField>

    <ParamField type="string">
      Admin only. Target user whose groups to retrieve.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="groups" type="array">
      <Expandable title="item properties">
        <ResponseField name="id" type="number">Group ID.</ResponseField>
        <ResponseField name="name" type="string">Group name.</ResponseField>
        <ResponseField name="description" type="string">Group description.</ResponseField>
        <ResponseField name="user_id" type="string">Owner user ID.</ResponseField>
        <ResponseField name="position" type="number">Display order position.</ResponseField>
        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("genie-groups", "list");
  ```

  ```json Request body theme={null}
  {
    "resource": "genie-groups",
    "action": "list"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "groups": [
        {
          "id": 1,
          "name": "Sales Team",
          "description": "Genies for sales workflows",
          "user_id": "user_123",
          "position": 0,
          "created_at": "2026-02-19T10:00:00.000Z"
        }
      ]
    }
  }
  ```
</CodeGroup>

***

## Get group

Retrieves a single group by ID.

<ParamField type="string">
  Must be `"genie-groups"`
</ParamField>

<ParamField type="string">
  Must be `"get"`
</ParamField>

<ParamField type="string">
  The group ID to retrieve (passed as a string).
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      Admin only. Enables cross-user access.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="group" type="object">
      <Expandable title="properties">
        <ResponseField name="id" type="number">Group ID.</ResponseField>
        <ResponseField name="name" type="string">Group name.</ResponseField>
        <ResponseField name="description" type="string">Group description.</ResponseField>
        <ResponseField name="user_id" type="string">Owner user ID.</ResponseField>
        <ResponseField name="position" type="number">Display order position.</ResponseField>
        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("genie-groups", "get", "1");
  ```

  ```json Request body theme={null}
  {
    "resource": "genie-groups",
    "action": "get",
    "id": "1"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "group": {
        "id": 1,
        "name": "Sales Team",
        "description": "Genies for sales workflows",
        "user_id": "user_123",
        "position": 0,
        "created_at": "2026-02-19T10:00:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

***

## Create group

Creates a new genie group. The group is automatically assigned the next available position.

<ParamField type="string">
  Must be `"genie-groups"`
</ParamField>

<ParamField type="string">
  Must be `"create"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Group display name.
    </ParamField>

    <ParamField type="string">
      A short description of the group's purpose.
    </ParamField>

    <ParamField type="string">
      Admin only. Create the group for a specific user.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="group" type="object">
      The newly created group with all fields including auto-assigned `position`.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "genie-groups",
    "create",
    undefined,
    {
      name: "Support Team",
      description: "Genies for support workflows",
    }
  );
  ```

  ```json Request body theme={null}
  {
    "resource": "genie-groups",
    "action": "create",
    "data": {
      "name": "Support Team",
      "description": "Genies for support workflows"
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "group": {
        "id": 2,
        "name": "Support Team",
        "description": "Genies for support workflows",
        "user_id": "user_123",
        "position": 1,
        "created_at": "2026-02-19T10:05:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

***

## Update group

Updates an existing group's properties. Only the fields you provide are changed.

<ParamField type="string">
  Must be `"genie-groups"`
</ParamField>

<ParamField type="string">
  Must be `"update"`
</ParamField>

<ParamField type="string">
  The group ID to update (passed as a string).
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Updated group name.
    </ParamField>

    <ParamField type="string">
      Updated description.
    </ParamField>

    <ParamField type="number">
      Updated display position.
    </ParamField>

    <ParamField type="string">
      Admin only. Target user who owns the group.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="group" type="object">
      The updated group with all current field values.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("genie-groups", "update", "1", {
    name: "Updated Sales Team",
    description: "Updated description for sales genies",
    position: 2,
  });
  ```

  ```json Request body theme={null}
  {
    "resource": "genie-groups",
    "action": "update",
    "id": "1",
    "data": {
      "name": "Updated Sales Team",
      "description": "Updated description for sales genies",
      "position": 2
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "group": {
        "id": 1,
        "name": "Updated Sales Team",
        "description": "Updated description for sales genies",
        "user_id": "user_123",
        "position": 2,
        "created_at": "2026-02-19T10:00:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

***

## Delete group

Permanently deletes a group. Genies in the group are not deleted; their `group_id` is set to `null`.

<ParamField type="string">
  Must be `"genie-groups"`
</ParamField>

<ParamField type="string">
  Must be `"delete"`
</ParamField>

<ParamField type="string">
  The group ID to delete (passed as a string).
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Admin only. Target user who owns the group.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean">Operation succeeded.</ResponseField>
    <ResponseField name="message" type="string">Confirmation message.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("genie-groups", "delete", "1");
  ```

  ```json Request body theme={null}
  {
    "resource": "genie-groups",
    "action": "delete",
    "id": "1"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "success": true,
      "message": "Group deleted successfully"
    }
  }
  ```
</CodeGroup>

***

## Reorder groups

Updates the display order of groups based on an ordered array of group IDs. The position of each group is set to its index in the array.

<ParamField type="string">
  Must be `"genie-groups"`
</ParamField>

<ParamField type="string">
  Must be `"reorder"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number[]">
      Ordered array of group IDs. The first ID gets position 0, the second gets position 1, and so on.
    </ParamField>

    <ParamField type="string">
      Admin only. Target user whose groups to reorder.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean">Operation succeeded.</ResponseField>
    <ResponseField name="message" type="string">Confirmation message.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "genie-groups",
    "reorder",
    undefined,
    {
      groupIds: [1, 3, 2],
    }
  );
  ```

  ```json Request body theme={null}
  {
    "resource": "genie-groups",
    "action": "reorder",
    "data": {
      "groupIds": [1, 3, 2]
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "success": true,
      "message": "Groups reordered successfully"
    }
  }
  ```
</CodeGroup>

***

## Get group genie counts

Returns the number of genies in each group. Useful for displaying counts in group lists without fetching all genies.

<ParamField type="string">
  Must be `"genie-groups"`
</ParamField>

<ParamField type="string">
  Must be `"counts"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      Admin only. Enables cross-user access.
    </ParamField>

    <ParamField type="string">
      Admin only. Target user whose group counts to retrieve.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="counts" type="object">
      An object where keys are group IDs (as strings) and values are genie counts.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("genie-groups", "counts");
  ```

  ```json Request body theme={null}
  {
    "resource": "genie-groups",
    "action": "counts"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "counts": {
        "1": 5,
        "2": 2
      }
    }
  }
  ```
</CodeGroup>

***

## Sync genie to group

Assigns or clears a group for a specific genie. Pass a `groupId` to assign the genie to a group, or pass `null` to remove the genie from its current group.

<ParamField type="string">
  Must be `"genie-groups"`
</ParamField>

<ParamField type="string">
  Must be `"sync"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The genie ID to assign or unassign.
    </ParamField>

    <ParamField type="number | null">
      The group ID to assign the genie to, or `null` to remove the genie from its group.
    </ParamField>

    <ParamField type="string">
      Admin only. Target user who owns the genie.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="agent" type="object">
      <Expandable title="properties">
        <ResponseField name="id" type="string">Genie ID.</ResponseField>
        <ResponseField name="group_id" type="number | null">The new group ID, or `null` if unassigned.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="previousGroupId" type="number | null">
      The group ID the genie was previously in.
    </ResponseField>

    <ResponseField name="newGroupId" type="number | null">
      The group ID the genie is now in.
    </ResponseField>
  </Expandable>
</ResponseField>

<Tip>
  Use the `sync` action to move a genie between groups. To transfer a genie from one group to another, simply pass the new `groupId` -- the genie is automatically removed from its previous group. To remove a genie from all groups without assigning a new one, pass `groupId: null`.
</Tip>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  // Assign a genie to a group
  const response = await ApiService.invoke(
    "genie-groups",
    "sync",
    undefined,
    {
      agentId: "550e8400-e29b-41d4-a716-446655440000",
      groupId: 2,
    }
  );

  // Remove a genie from its group
  const response = await ApiService.invoke(
    "genie-groups",
    "sync",
    undefined,
    {
      agentId: "550e8400-e29b-41d4-a716-446655440000",
      groupId: null,
    }
  );
  ```

  ```bash cURL (assign to group) theme={null}
  curl -X POST https://api.helpgenie.ai/v1/genie-groups \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "sync",
      "data": {
        "agentId": "550e8400-e29b-41d4-a716-446655440000",
        "groupId": 2
      }
    }'
  ```

  ```bash cURL (remove from group) theme={null}
  curl -X POST https://api.helpgenie.ai/v1/genie-groups \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "sync",
      "data": {
        "agentId": "550e8400-e29b-41d4-a716-446655440000",
        "groupId": null
      }
    }'
  ```

  ```json Request body (assign) theme={null}
  {
    "resource": "genie-groups",
    "action": "sync",
    "data": {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "groupId": 2
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "agent": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "group_id": 2
      },
      "previousGroupId": 1,
      "newGroupId": 2
    }
  }
  ```
</CodeGroup>

***

## Error codes

| Code               | Status | Description                                                   |
| ------------------ | ------ | ------------------------------------------------------------- |
| `UNAUTHORIZED`     | 401    | Missing or invalid authentication token                       |
| `FORBIDDEN`        | 403    | Only admins can manage groups for other users                 |
| `NOT_FOUND`        | 404    | Group not found                                               |
| `VALIDATION_ERROR` | 400    | Missing or invalid parameters (for example group ID required) |
| `INTERNAL_ERROR`   | 500    | Server-side error                                             |


# Genies
Source: https://docs.helpgenie.ai/api-reference/genies

Create, configure, list, and manage voice AI genies

Genies are voice AI agents managed through our agent system. Each genie has its own system prompt, voice configuration, conversation settings, and optional phone number.

<Note>
  Standard users can only manage their own genies. Admin users can manage all genies and view owner information by passing `adminMode: true`.
</Note>

***

## List genies

Retrieves a paginated list of genies with essential fields. Optimized for selects, dropdowns, and summary views.

<ParamField type="string">
  Must be `"genies"`
</ParamField>

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

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Results per page. Maximum 500.
    </ParamField>

    <ParamField type="number">
      Number of results to skip.
    </ParamField>

    <ParamField type="string">
      Filter genies by name or description (case-insensitive). Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="string">
      Filter by category (e.g. `"Support"`, `"Sales"`). Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="string">
      Filter by voice label (partial match). Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="boolean">
      Filter by active status. Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="boolean">
      Filter to public or private genies. Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="boolean">
      Filter to demo genies only. Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="boolean">
      Filter to marketplace genies. Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="boolean">
      When `true`, return only marketplace genies (equivalent to `isMarketplaceGenie: true`).
    </ParamField>

    <ParamField type="boolean">
      When `true`, include marketplace genies in results (by default they are excluded).
    </ParamField>

    <ParamField type="object">
      Alternative nested form for any of the filter fields above (e.g. `filters.searchTerm`, `filters.category`). Also accepts the following admin-only field:

      <Expandable title="admin-only filter fields">
        <ParamField type="string">
          Admin only. Filter by owner's full name (partial, case-insensitive match). Only applies when `adminMode` is `true`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="boolean">
      Admin only. When `true`, includes owner profile in each item and allows `userId` filtering.
    </ParamField>

    <ParamField type="string">
      Admin only. Return genies owned by this user ID.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="agents" type="array">
      <Expandable title="item properties">
        <ResponseField name="id" type="string">
          Unique genie identifier (UUID).
        </ResponseField>

        <ResponseField name="user_id" type="string">
          Owner user ID.
        </ResponseField>

        <ResponseField name="name" type="string">
          Genie display name.
        </ResponseField>

        <ResponseField name="description" type="string">
          Genie description.
        </ResponseField>

        <ResponseField name="is_active" type="boolean">
          Whether the genie is currently active.
        </ResponseField>

        <ResponseField name="category" type="string">
          Genie category (for example `"Support"`, `"Sales"`).
        </ResponseField>

        <ResponseField name="purpose" type="string">
          Primary purpose of the genie (e.g. `"general"`, `"support"`).
        </ResponseField>

        <ResponseField name="branding" type="object">
          Branding configuration object, or `null`.
        </ResponseField>

        <ResponseField name="created_at" type="string">
          ISO 8601 creation timestamp.
        </ResponseField>

        <ResponseField name="owner" type="object">
          Owner profile — present only when `adminMode` is `true`.

          <Expandable title="properties">
            <ResponseField name="id" type="string">User ID.</ResponseField>
            <ResponseField name="full_name" type="string">Full name.</ResponseField>
            <ResponseField name="email" type="string">Email address.</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number">
      Total number of genies matching the filters.
    </ResponseField>

    <ResponseField name="limit" type="number">
      The limit that was applied.
    </ResponseField>

    <ResponseField name="offset" type="number">
      The offset that was applied.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("genies", "list", undefined, {
    limit: 30,
    offset: 0,
    searchTerm: "support",
    isActive: true,
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/genies \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "genies",
      "action": "list",
      "data": {
        "limit": 30,
        "offset": 0,
        "searchTerm": "support"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "agents": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "user_id": "660e8400-e29b-41d4-a716-446655440001",
          "name": "Customer Support Bot",
          "description": "AI-powered customer support assistant",
          "is_active": true,
          "category": "Support",
          "purpose": "general",
          "branding": null,
          "created_at": "2024-01-15T10:30:00.000Z"
        }
      ],
      "count": 1,
      "limit": 30,
      "offset": 0
    }
  }
  ```
</CodeGroup>

***

## Get all genies

Retrieves all genies with full configuration using cursor-based pagination. Returns complete genie objects including settings, phone, page, group, and knowledge base data.

<ParamField type="string">
  Must be `"genies"`
</ParamField>

<ParamField type="string">
  Must be `"all"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Results per page, between 1 and 500.
    </ParamField>

    <ParamField type="string">
      Opaque pagination cursor returned from a previous request as `nextCursor`. Pass it unchanged to fetch the next page.
    </ParamField>

    <ParamField type="string">
      Filter by name or description (case-insensitive). Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="string">
      Filter by category. Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="string">
      Filter by voice label (partial match). Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="boolean">
      Filter by active status. Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="boolean">
      Filter to public or private genies. Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="boolean">
      Filter to demo genies. Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="boolean">
      Filter to marketplace genies. Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="string">
      Filter by group UUID. Pass `"ungrouped"` to return genies not assigned to any group.
    </ParamField>

    <ParamField type="number">
      Filter to genies with this specific daily call limit. Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="string">
      Filter by the language model configured in the genie's settings. Can also be passed inside `filters`.
    </ParamField>

    <ParamField type="boolean">
      Admin only. When `true`, includes owner profile information in the response.
    </ParamField>

    <ParamField type="string">
      Admin only. Filter genies to those owned by a specific user.
    </ParamField>

    <ParamField type="string">
      Admin only. Filter by owner profile role (for example `"standard_user"`, `"internal_admin"`). Can also be passed inside `filters`.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="data" type="array">
      Array of full genie objects. Each item has the same shape as the `get` genie response — see below.
    </ResponseField>

    <ResponseField name="nextCursor" type="string | null">
      Opaque cursor string. Pass as `cursor` in the next request to fetch the next page. `null` when there are no more results.
    </ResponseField>

    <ResponseField name="hasMore" type="boolean">
      Whether more results are available beyond this page.
    </ResponseField>

    <ResponseField name="total" type="number">
      Total count of genies matching the filters.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  // First page
  const page1 = await ApiService.invoke("genies", "all", undefined, {
    limit: 25,
  });

  // Next page
  const page2 = await ApiService.invoke("genies", "all", undefined, {
    limit: 25,
    cursor: page1.nextCursor,
  });
  ```

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

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "data": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "user_id": "660e8400-e29b-41d4-a716-446655440001",
          "name": "Customer Support Bot",
          "description": "AI-powered customer support assistant",
          "brand": "Acme Corp",
          "is_active": true,
          "category": "Support",
          "voice": "EZ3epTG1EiOmx2GWRto6",
          "memory_enabled": false,
          "capture_leads": false,
          "purpose": "general",
          "settings": { "...": "full settings object" },
          "phone": { "id": "phone-123", "number": "+1234567890", "status": "active" },
          "transfer_phone": null,
          "page": { "id": "page-123", "url_name": "support-bot" },
          "group": { "id": "group-123", "name": "Support Genies" },
          "knowledge_base": [
            { "id": "doc-123", "name": "Product FAQ", "is_active": true }
          ],
          "escalation_webhook": null,
          "mailbox": null,
          "saved_qr_codes": [],
          "created_at": "2024-01-15T10:30:00.000Z",
          "updated_at": "2024-01-15T10:30:00.000Z"
        }
      ],
      "nextCursor": "eyJwb3NpdGlvbiI6MCwiY3JlYXRlZEF0IjoiMjAyNC0wMS0xNFQxNToyMDowMC4wMDBaIn0=",
      "hasMore": true,
      "total": 42
    }
  }
  ```
</CodeGroup>

<Note>
  When `adminMode` is `true`, each genie includes an `owner` field with `id`, `full_name`, and `email`. Standard users always see `owner: null`.
</Note>

***

## Get genie

Retrieves a single genie by ID with its full configuration, including settings, phone number, page, group, and knowledge base.

<ParamField type="string">
  Must be `"genies"`
</ParamField>

<ParamField type="string">
  Must be `"get"`
</ParamField>

<ParamField type="string">
  The UUID of the genie to retrieve.
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="agent" type="object">
      The full genie object.

      <Expandable title="properties">
        <ResponseField name="id" type="string">Unique genie identifier (UUID).</ResponseField>
        <ResponseField name="user_id" type="string">Owner user ID.</ResponseField>
        <ResponseField name="name" type="string">Genie display name.</ResponseField>
        <ResponseField name="description" type="string">Genie description.</ResponseField>
        <ResponseField name="brand" type="string">Brand or company name.</ResponseField>
        <ResponseField name="category" type="string">Genie category.</ResponseField>
        <ResponseField name="category_data" type="object">Extended category metadata, or `null`.</ResponseField>
        <ResponseField name="is_active" type="boolean">Whether the genie is active.</ResponseField>
        <ResponseField name="is_setup" type="boolean">Whether the genie has completed initial setup.</ResponseField>
        <ResponseField name="is_public" type="boolean">Whether the genie is publicly accessible.</ResponseField>
        <ResponseField name="is_marketplace_genie" type="boolean">Whether this genie is a marketplace genie.</ResponseField>
        <ResponseField name="is_demo_genie" type="boolean">Whether this genie is a demo genie.</ResponseField>
        <ResponseField name="voice" type="string">Voice identifier used by the voice platform.</ResponseField>
        <ResponseField name="voice_label" type="string">Human-readable label for the configured voice.</ResponseField>
        <ResponseField name="send_conv_reports" type="boolean">Whether conversation reports are sent after calls.</ResponseField>

        <ResponseField name="report_mode" type="string">
          When reports are sent. One of `"every_conversation"` or `"off"`.
        </ResponseField>

        <ResponseField name="report_digest_frequency" type="string">Frequency for digest reports, or `null`.</ResponseField>
        <ResponseField name="report_digest_day_of_week" type="number">Day of week for weekly digests (0 = Sunday), or `null`.</ResponseField>
        <ResponseField name="escalation_settings" type="object">Escalation configuration, or `null`.</ResponseField>
        <ResponseField name="redirect_url" type="string">URL to redirect visitors after a conversation ends.</ResponseField>
        <ResponseField name="capture_leads" type="boolean">Whether lead capture is enabled.</ResponseField>
        <ResponseField name="memory_enabled" type="boolean">Whether conversation memory is enabled for this genie.</ResponseField>
        <ResponseField name="voice_bridge_enabled" type="boolean">Whether the voice-to-human bridge feature is enabled, allowing live handoff to a human agent during a call.</ResponseField>
        <ResponseField name="voice_bridge_show_button" type="boolean">Whether the manual "Talk to a human" button is displayed on the genie page. Defaults to `true`. Only relevant when `voice_bridge_enabled` is `true`.</ResponseField>
        <ResponseField name="purpose" type="string">Primary purpose (e.g. `"general"`).</ResponseField>
        <ResponseField name="url_name" type="string">URL-friendly slug for the genie's web page.</ResponseField>
        <ResponseField name="welcome_message" type="string">Welcome message shown before a call begins.</ResponseField>
        <ResponseField name="info_links" type="array">Informational links attached to this genie, or `null`.</ResponseField>
        <ResponseField name="type" type="string">Genie type, or `null`.</ResponseField>
        <ResponseField name="goal" type="object">Goal or lead info presets, or `null`.</ResponseField>
        <ResponseField name="insights" type="object">Insights configuration, or `null`.</ResponseField>
        <ResponseField name="persona_id" type="string">Associated persona ID, or `null`.</ResponseField>

        <ResponseField name="settings" type="object">
          Full genie configuration including conversation config, TTS settings, and turn settings.

          <Expandable title="properties">
            <ResponseField name="name" type="string">Genie name in settings.</ResponseField>

            <ResponseField name="conversation_config" type="object">
              <Expandable title="properties">
                <ResponseField name="agent" type="object">
                  <Expandable title="properties">
                    <ResponseField name="first_message" type="string">Initial greeting message.</ResponseField>

                    <ResponseField name="prompt" type="object">
                      <Expandable title="properties">
                        <ResponseField name="prompt" type="string">System prompt.</ResponseField>
                        <ResponseField name="llm" type="string">Language model identifier.</ResponseField>
                        <ResponseField name="temperature" type="number">Model temperature (0–2).</ResponseField>
                        <ResponseField name="max_tokens" type="number">Maximum response tokens.</ResponseField>
                      </Expandable>
                    </ResponseField>
                  </Expandable>
                </ResponseField>

                <ResponseField name="tts" type="object">
                  <Expandable title="properties">
                    <ResponseField name="model_id" type="string">Voice synthesis model identifier.</ResponseField>
                    <ResponseField name="voice_id" type="string">Voice identifier used by the voice platform.</ResponseField>
                    <ResponseField name="stability" type="number">Voice stability (0–1).</ResponseField>
                    <ResponseField name="similarity_boost" type="number">Voice similarity (0–1).</ResponseField>
                    <ResponseField name="speed" type="number">Speech speed multiplier.</ResponseField>
                  </Expandable>
                </ResponseField>

                <ResponseField name="conversation" type="object">
                  <Expandable title="properties">
                    <ResponseField name="text_only" type="boolean">Whether voice is disabled.</ResponseField>
                    <ResponseField name="max_duration_seconds" type="number">Maximum conversation duration in seconds.</ResponseField>
                  </Expandable>
                </ResponseField>

                <ResponseField name="turn" type="object">
                  <Expandable title="properties">
                    <ResponseField name="turn_timeout" type="number">Seconds before a turn times out.</ResponseField>
                    <ResponseField name="silence_end_call_timeout" type="number">Seconds of silence before ending the call.</ResponseField>
                    <ResponseField name="mode" type="string">Turn detection mode (for example `"silence"`).</ResponseField>
                  </Expandable>
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="branding" type="object">Branding configuration, or `null`.</ResponseField>
        <ResponseField name="position" type="number">Display order position.</ResponseField>
        <ResponseField name="group_id" type="string">UUID of the group this genie belongs to, or `null`.</ResponseField>
        <ResponseField name="call_limit" type="number">Maximum number of concurrent calls allowed.</ResponseField>

        <ResponseField name="phone" type="object">
          Inbound phone number attached to this genie, or `null`.

          <Expandable title="properties">
            <ResponseField name="id" type="string">Phone record ID.</ResponseField>
            <ResponseField name="agent_id" type="string">Genie ID linked to this number.</ResponseField>
            <ResponseField name="number" type="string">Phone number in E.164 format.</ResponseField>
            <ResponseField name="friendly_name" type="string">Human-readable label for the number.</ResponseField>
            <ResponseField name="status" type="string">Phone status (e.g. `"active"`).</ResponseField>
            <ResponseField name="country_code" type="string">Two-letter country code.</ResponseField>
            <ResponseField name="metadata" type="object">Additional provider metadata, or `null`.</ResponseField>
            <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
            <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="transfer_phone" type="object">
          Phone number used for call transfers, or `null`. Same shape as `phone`.
        </ResponseField>

        <ResponseField name="page" type="object">
          Web page configuration, or `null`.

          <Expandable title="properties">
            <ResponseField name="id" type="string">Page record ID.</ResponseField>
            <ResponseField name="agent_id" type="string">Genie ID linked to this page.</ResponseField>
            <ResponseField name="url_name" type="string">URL-friendly page slug.</ResponseField>
            <ResponseField name="welcome_message" type="string">Welcome message displayed on the page.</ResponseField>
            <ResponseField name="target_audience" type="string">Target audience descriptor, or `null`.</ResponseField>
            <ResponseField name="genie_image_url" type="string">URL of the genie's avatar image, or `null`.</ResponseField>
            <ResponseField name="branding" type="object">Page-level branding overrides, or `null`.</ResponseField>

            <ResponseField name="flags" type="object">
              Feature flags for the page.

              <Expandable title="properties">
                <ResponseField name="feedback" type="boolean">Whether conversation feedback is enabled.</ResponseField>
                <ResponseField name="business_lead" type="boolean">Whether business lead capture is enabled.</ResponseField>
                <ResponseField name="consumer_lead" type="boolean">Whether consumer lead capture is enabled.</ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="metadata" type="object">
              Page metadata.

              <Expandable title="properties">
                <ResponseField name="redirect_url" type="string">Post-conversation redirect URL.</ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="sandbox_link" type="string">Link to the genie sandbox preview, or `null`.</ResponseField>
            <ResponseField name="info_links" type="array">Informational links shown on the page, or `null`.</ResponseField>
            <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
            <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="escalation_webhook" type="object">
          Escalation webhook status, or `null`.

          <Expandable title="properties">
            <ResponseField name="is_active" type="boolean">Whether the escalation webhook is active.</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="mailbox" type="object">
          Email inbox attached to this genie, or `null` if no mailbox has been provisioned.

          <Expandable title="properties">
            <ResponseField name="id" type="string">Mailbox UUID.</ResponseField>
            <ResponseField name="agent_id" type="string">UUID of the owning genie.</ResponseField>
            <ResponseField name="email_address" type="string">The provisioned mailbox email address.</ResponseField>
            <ResponseField name="account_id" type="string | null">Internal account reference used by the mail system, or `null` if not yet provisioned.</ResponseField>
            <ResponseField name="grant_id" type="string | null">Connection grant identifier, or `null`.</ResponseField>

            <ResponseField name="status" type="string">
              Current status. One of `"provisioned"`, `"suspended"`, or `"failed"`.
            </ResponseField>

            <ResponseField name="last_error" type="string | null">Most recent provisioning error, or `null` if healthy.</ResponseField>
            <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
            <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="group" type="object">
          Group the genie belongs to, or `null`.

          <Expandable title="properties">
            <ResponseField name="id" type="string">Group ID.</ResponseField>
            <ResponseField name="name" type="string">Group name.</ResponseField>
            <ResponseField name="description" type="string">Group description.</ResponseField>
            <ResponseField name="position" type="number">Group display order.</ResponseField>
            <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="knowledge_base" type="array">
          Documents attached to this genie.

          <Expandable title="item properties">
            <ResponseField name="id" type="string">Document ID.</ResponseField>
            <ResponseField name="name" type="string">Document name.</ResponseField>
            <ResponseField name="is_active" type="boolean">Whether the document is active.</ResponseField>
            <ResponseField name="status" type="string">Processing status of the document.</ResponseField>
            <ResponseField name="source_type" type="string">Source type (e.g. `"file"`, `"url"`).</ResponseField>
            <ResponseField name="folder_id" type="string">Folder this document belongs to, or `null`.</ResponseField>
            <ResponseField name="user_id" type="string">Owner user ID.</ResponseField>
            <ResponseField name="metadata" type="object">Document metadata, or `null`.</ResponseField>
            <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="saved_qr_codes" type="array">
          QR codes saved for this genie (excludes deleted codes).
        </ResponseField>

        <ResponseField name="owner" type="object">
          Owner profile — present only when `adminMode` is `true`.

          <Expandable title="properties">
            <ResponseField name="id" type="string">User ID.</ResponseField>
            <ResponseField name="full_name" type="string">Full name.</ResponseField>
            <ResponseField name="email" type="string">Email address.</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
        <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "genies",
    "get",
    "550e8400-e29b-41d4-a716-446655440000"
  );
  const genie = response?.agent;
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/genies \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "genies",
      "action": "get",
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "agent": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "user_id": "660e8400-e29b-41d4-a716-446655440001",
        "name": "Customer Support Bot",
        "description": "AI-powered customer support assistant",
        "brand": "Acme Corp",
        "category": "Support",
        "is_active": true,
        "is_setup": false,
        "is_public": false,
        "is_marketplace_genie": false,
        "is_demo_genie": false,
        "voice": "EZ3epTG1EiOmx2GWRto6",
        "voice_label": "Rachel",
        "send_conv_reports": true,
        "report_mode": "every_conversation",
        "capture_leads": false,
        "memory_enabled": false,
        "voice_bridge_enabled": false,
        "voice_bridge_show_button": true,
        "purpose": "general",
        "url_name": "support-bot",
        "welcome_message": "Let's connect with our support team",
        "redirect_url": null,
        "settings": {
          "name": "Customer Support Bot",
          "conversation_config": {
            "agent": {
              "first_message": "Hello! Welcome to our support team. How can I help you today?",
              "prompt": {
                "prompt": "You are a helpful customer support representative...",
                "llm": "gemini-3-flash-preview",
                "temperature": 0.7,
                "max_tokens": 8000
              }
            },
            "tts": {
              "model_id": "multilingual_v2",
              "voice_id": "550e8400-e29b-41d4-a716-446655440009",
              "stability": 0.5,
              "similarity_boost": 0.8,
              "speed": 1.0
            },
            "conversation": {
              "text_only": false,
              "max_duration_seconds": 600
            },
            "turn": {
              "turn_timeout": 7,
              "silence_end_call_timeout": 30,
              "mode": "silence"
            }
          }
        },
        "branding": null,
        "position": 0,
        "group_id": null,
        "call_limit": 10,
        "phone": {
          "id": "phone-123",
          "agent_id": "550e8400-e29b-41d4-a716-446655440000",
          "number": "+1234567890",
          "friendly_name": "Support Line",
          "status": "active",
          "country_code": "US",
          "metadata": null,
          "created_at": "2024-01-10T08:00:00.000Z",
          "updated_at": "2024-01-10T08:00:00.000Z"
        },
        "transfer_phone": null,
        "page": {
          "id": "page-123",
          "agent_id": "550e8400-e29b-41d4-a716-446655440000",
          "url_name": "support-bot",
          "welcome_message": "Let's connect with our support team",
          "target_audience": null,
          "genie_image_url": null,
          "branding": null,
          "flags": {
            "feedback": true,
            "business_lead": false,
            "consumer_lead": false
          },
          "metadata": { "redirect_url": null },
          "sandbox_link": null,
          "info_links": null,
          "created_at": "2024-01-15T10:30:00.000Z",
          "updated_at": "2024-01-15T10:30:00.000Z"
        },
        "escalation_webhook": null,
        "mailbox": {
          "id": "mbx-uuid-001",
          "agent_id": "550e8400-e29b-41d4-a716-446655440000",
          "email_address": "support-bot@mail.helpgenie.ai",
          "account_id": "acct-abc123",
          "grant_id": null,
          "status": "provisioned",
          "last_error": null,
          "created_at": "2024-01-15T10:30:00.000Z",
          "updated_at": "2024-01-15T10:30:00.000Z"
        },
        "group": null,
        "knowledge_base": [
          {
            "id": "doc-123",
            "name": "Product FAQ",
            "is_active": true,
            "status": "processed",
            "source_type": "file",
            "folder_id": null,
            "user_id": "660e8400-e29b-41d4-a716-446655440001",
            "metadata": null,
            "created_at": "2024-01-12T09:00:00.000Z"
          }
        ],
        "saved_qr_codes": [],
        "created_at": "2024-01-15T10:30:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

***

## Create genie

Creates a new voice AI genie with the specified configuration. The genie is automatically provisioned in the voice agent system.

<ParamField type="string">
  Must be `"genies"`
</ParamField>

<ParamField type="string">
  Must be `"create"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Display name for the genie.
    </ParamField>

    <ParamField type="string">
      Primary use case describing what the genie does.
    </ParamField>

    <ParamField type="string">
      System prompt defining the genie's behavior and personality.
    </ParamField>

    <ParamField type="string">
      Initial greeting message spoken when a conversation starts.
    </ParamField>

    <ParamField type="string">
      Welcome message displayed on the web interface before a call begins.
    </ParamField>

    <ParamField type="string">
      Voice identifier. Defaults to the platform default voice.
    </ParamField>

    <ParamField type="string">
      Language model identifier.
    </ParamField>

    <ParamField type="number">
      Model temperature between 0 and 2.
    </ParamField>

    <ParamField type="number">
      Maximum number of tokens in the response.
    </ParamField>

    <ParamField type="boolean">
      Enable multilingual voice support.
    </ParamField>

    <ParamField type="number">
      Voice stability between 0 and 1.
    </ParamField>

    <ParamField type="number">
      Voice similarity between 0 and 1.
    </ParamField>

    <ParamField type="number">
      Speech speed multiplier.
    </ParamField>

    <ParamField type="object">
      <Expandable title="properties">
        <ParamField type="number">
          Maximum conversation duration in seconds.
        </ParamField>

        <ParamField type="number">
          Seconds before a turn times out.
        </ParamField>

        <ParamField type="number">
          Seconds of silence before ending the call.
        </ParamField>

        <ParamField type="string">
          Turn detection mode.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Brand or company name.
    </ParamField>

    <ParamField type="string">
      Genie category or type.
    </ParamField>

    <ParamField type="string">
      Detailed description of the genie.
    </ParamField>

    <ParamField type="string[]">
      Email addresses for the support team.
    </ParamField>

    <ParamField type="boolean">
      Send email reports after each conversation.
    </ParamField>

    <ParamField type="boolean">
      Provision and attach a phone number to this genie.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">Genie UUID.</ResponseField>
    <ResponseField name="user_id" type="string">Owner user ID.</ResponseField>
    <ResponseField name="name" type="string">Genie name.</ResponseField>
    <ResponseField name="description" type="string">Genie description.</ResponseField>
    <ResponseField name="brand" type="string">Brand name.</ResponseField>
    <ResponseField name="category" type="string">Category.</ResponseField>
    <ResponseField name="is_active" type="boolean">Active status.</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
    <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("genies", "create", undefined, {
    genieName: "Customer Support Bot",
    useCase: "Handle customer support inquiries",
    systemPrompt:
      "You are a helpful customer support representative. Be friendly and professional.",
    firstMessage:
      "Hello! Welcome to our support team. How can I help you today?",
    webWelcomeMessage: "Let's connect with our support team",
    voiceId: "EZ3epTG1EiOmx2GWRto6",
    llmModel: "gemini-3-flash-preview",
    temperature: 0.7,
    maxTokens: 8000,
    brand: "Acme Corp",
    category: "Support",
    description: "AI-powered customer support assistant",
    supportEmails: ["support@acme.com"],
    sendConversationReports: true,
    attachPhoneNumber: false,
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/genies \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "genies",
      "action": "create",
      "data": {
        "genieName": "Customer Support Bot",
        "useCase": "Handle customer support inquiries",
        "systemPrompt": "You are a helpful customer support representative. Be friendly and professional.",
        "firstMessage": "Hello! Welcome to our support team. How can I help you today?",
        "webWelcomeMessage": "Let us connect with our support team",
        "voiceId": "EZ3epTG1EiOmx2GWRto6",
        "brand": "Acme Corp",
        "category": "Support",
        "description": "AI-powered customer support assistant",
        "supportEmails": ["support@acme.com"],
        "sendConversationReports": true,
        "attachPhoneNumber": false
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "message": "Genie created successfully",
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Customer Support Bot",
      "description": "AI-powered customer support assistant",
      "brand": "Acme Corp",
      "category": "Support",
      "is_active": true,
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    }
  }
  ```
</CodeGroup>

<Note>
  Admin users can create genies on behalf of other users by including `impersonatedUserId` in the data object.
</Note>

***

## Update genie

Updates an existing genie's configuration. Supports partial updates — only the fields you include will be changed.

<ParamField type="string">
  Must be `"genies"`
</ParamField>

<ParamField type="string">
  Must be `"update"`
</ParamField>

<ParamField type="string">
  The UUID of the genie to update.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Updated genie name.
    </ParamField>

    <ParamField type="string">
      Updated description.
    </ParamField>

    <ParamField type="object">
      Nested settings object. Fields are merged, not replaced.

      <Expandable title="properties">
        <ParamField type="object">
          <Expandable title="properties">
            <ParamField type="object">
              <Expandable title="properties">
                <ParamField type="string">Updated greeting.</ParamField>

                <ParamField type="object">
                  <Expandable title="properties">
                    <ParamField type="string">Updated system prompt.</ParamField>
                    <ParamField type="number">Model temperature (0–2).</ParamField>
                    <ParamField type="number">Max response tokens.</ParamField>
                  </Expandable>
                </ParamField>
              </Expandable>
            </ParamField>

            <ParamField type="object">
              <Expandable title="properties">
                <ParamField type="string">New voice identifier for the voice platform.</ParamField>
                <ParamField type="number">Voice stability (0–1).</ParamField>
                <ParamField type="number">Voice similarity (0–1).</ParamField>
                <ParamField type="number">Speech speed multiplier.</ParamField>
              </Expandable>
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      Branding configuration. Merged with existing branding.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">Genie UUID.</ResponseField>
    <ResponseField name="name" type="string">Updated genie name.</ResponseField>
    <ResponseField name="description" type="string">Updated description.</ResponseField>
    <ResponseField name="updated_at" type="string">ISO 8601 timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "genies",
    "update",
    "550e8400-e29b-41d4-a716-446655440000",
    {
      name: "Updated Bot Name",
      description: "Updated description",
      settings: {
        conversation_config: {
          agent: {
            first_message: "Updated greeting message",
            prompt: {
              prompt: "You are an advanced customer support AI...",
              temperature: 0.8,
              max_tokens: 2048,
            },
          },
          tts: {
            voice_id: "new-voice-id",
            stability: 0.8,
            similarity_boost: 0.9,
            speed: 1.05,
          },
        },
      },
    }
  );
  ```

  ```json Request body theme={null}
  {
    "resource": "genies",
    "action": "update",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "data": {
      "name": "Updated Bot Name",
      "description": "Updated description",
      "settings": {
        "conversation_config": {
          "agent": {
            "first_message": "Updated greeting message",
            "prompt": {
              "prompt": "You are an advanced customer support AI...",
              "temperature": 0.8,
              "max_tokens": 2048
            }
          },
          "tts": {
            "voice_id": "new-voice-id",
            "stability": 0.8,
            "similarity_boost": 0.9,
            "speed": 1.05
          }
        }
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "message": "Genie updated successfully",
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Updated Bot Name",
      "description": "Updated description",
      "updated_at": "2024-01-15T11:00:00.000Z"
    }
  }
  ```
</CodeGroup>

***

## Delete genie

Permanently deletes a genie, removes it from the voice agent system, and releases any associated phone numbers.

<ParamField type="string">
  Must be `"genies"`
</ParamField>

<ParamField type="string">
  Must be `"delete"`
</ParamField>

<ParamField type="string">
  The UUID of the genie to delete.
</ParamField>

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

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<Warning>
  This action is irreversible. The genie, its external agent instance, and any attached phone numbers will be permanently removed.
</Warning>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "genies",
    "delete",
    "550e8400-e29b-41d4-a716-446655440000"
  );
  ```

  ```json Request body theme={null}
  {
    "resource": "genies",
    "action": "delete",
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "message": "Genie deleted successfully"
  }
  ```
</CodeGroup>

***

## Clone genie

Creates a copy of an existing genie with all its configuration. Optionally rename the clone and apply text replacements to the system prompt and first message.

<ParamField type="string">
  Must be `"genies"`
</ParamField>

<ParamField type="string">
  Must be `"clone"`
</ParamField>

<ParamField type="string">
  The UUID of the genie to clone.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Name for the cloned genie. Defaults to `"Copy of {original name}"`.
    </ParamField>

    <ParamField type="array">
      Array of string replacements applied to the system prompt and first message. Useful for white-labeling.

      <Expandable title="item properties">
        <ParamField type="string">Text to find.</ParamField>
        <ParamField type="string">Replacement text.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Admin only. Create the clone under this user's account instead of the caller's.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="agent" type="object">The newly created clone.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.helpgenie.ai/v1/genies \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "genies",
      "action": "clone",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "data": {
        "name": "Support Bot v2",
        "promptReplacements": [
          { "from": "Acme Corp", "to": "New Brand" }
        ]
      }
    }'
  ```

  ```json Request body theme={null}
  {
    "resource": "genies",
    "action": "clone",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "data": {
      "name": "Support Bot v2",
      "promptReplacements": [
        { "from": "Acme Corp", "to": "New Brand" }
      ]
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "success": true,
      "agent": {
        "id": "new-genie-uuid",
        "name": "Support Bot v2",
        "created_at": "2024-01-15T12:00:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

<Note>
  Attached knowledge base documents are cloned and linked to the new genie automatically. If a document clone fails (for example due to a transient error), the genie itself is still created — only that document is skipped. Goal associations from the original genie are also copied to the clone.
</Note>

***

## Reorder genies

Updates the display order of genies. Pass an object mapping genie IDs to their desired position (zero-indexed).

<ParamField type="string">
  Must be `"genies"`
</ParamField>

<ParamField type="string">
  Must be `"reorder"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="object">
      An object where keys are genie UUIDs and values are integer positions starting from 0.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("genies", "reorder", undefined, {
    sort: {
      "550e8400-e29b-41d4-a716-446655440000": 0,
      "990e8400-e29b-41d4-a716-446655440004": 1,
      "aa0e8400-e29b-41d4-a716-446655440005": 2,
    },
  });
  ```

  ```json Request body theme={null}
  {
    "resource": "genies",
    "action": "reorder",
    "data": {
      "sort": {
        "550e8400-e29b-41d4-a716-446655440000": 0,
        "990e8400-e29b-41d4-a716-446655440004": 1,
        "aa0e8400-e29b-41d4-a716-446655440005": 2
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "message": "Genies reordered successfully"
  }
  ```
</CodeGroup>

***

## Analytics

Returns conversation analytics per genie — total conversations, recent conversations (last 7 days), and last-used timestamp.

<ParamField type="string">
  `analytics`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      Admin only. Return analytics across all users.
    </ParamField>

    <ParamField type="string">
      Admin only. Scope to a specific user.
    </ParamField>
  </Expandable>
</ParamField>

### Response

Returns an array of analytics objects (one per genie):

<ResponseField name="" type="array">
  <Expandable title="Item properties">
    <ResponseField name="id" type="string">Genie UUID.</ResponseField>
    <ResponseField name="name" type="string">Genie name.</ResponseField>
    <ResponseField name="conversationCount" type="number">Total conversation count.</ResponseField>
    <ResponseField name="recentConversations" type="number">Conversations in the last 7 days.</ResponseField>
    <ResponseField name="lastUsedAt" type="string | null">ISO 8601 timestamp of most recent conversation.</ResponseField>
    <ResponseField name="brand" type="string | null">Brand name.</ResponseField>
    <ResponseField name="isTeamAgent" type="boolean">Whether this genie belongs to a workspace owner rather than the authenticated user directly.</ResponseField>
    <ResponseField name="owner" type="object | null">Owner profile (admin mode only).</ResponseField>
  </Expandable>
</ResponseField>

***

## Limits

Returns the genie quota for the authenticated user's personal account and, if applicable, their workspace (team).

<ParamField type="string">
  `limits`
</ParamField>

### Response

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="personal" type="object">
      Quota for the authenticated user's own account.

      <Expandable title="properties">
        <ResponseField name="currentCount" type="number">Number of genies currently owned by the user.</ResponseField>
        <ResponseField name="maxGenies" type="number">Maximum genies allowed. Admin users have no enforced cap.</ResponseField>
        <ResponseField name="isAtLimit" type="boolean">Whether `currentCount` has reached `maxGenies`.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="team" type="object | null">
      Quota for the workspace owner's account — present when the caller is a team owner or team member, `null` otherwise. Same shape as `personal`.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("genies", "limits");
  const { personal, team } = 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": "genies", "action": "limits"}'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "personal": {
        "currentCount": 3,
        "maxGenies": 4,
        "isAtLimit": false
      },
      "team": null
    }
  }
  ```
</CodeGroup>

***

## Timeline

Returns a day-by-day conversation count for a genie over a specified date range.

<ParamField type="string">
  `timeline`
</ParamField>

<ParamField type="string">
  Genie UUID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      ISO 8601 start date (inclusive).
    </ParamField>

    <ParamField type="string">
      ISO 8601 end date (inclusive).
    </ParamField>
  </Expandable>
</ParamField>

### Response

```json theme={null}
{
  "agentId": "agent-uuid",
  "agentName": "Support Genie",
  "data": [
    { "date": "2024-01-01", "conversations": 3 },
    { "date": "2024-01-02", "conversations": 7 }
  ]
}
```

***

## URL

Returns the public URL for a genie's web page.

<ParamField type="string">
  `url`
</ParamField>

<ParamField type="string">
  Genie UUID.
</ParamField>

***

## Embed code

Returns an HTML embed snippet for embedding a genie on an external website.

<ParamField type="string">
  `embed-code`
</ParamField>

<ParamField type="string">
  Genie UUID.
</ParamField>

***

## Request access

Submits an access request for a private genie. Used when a visitor wants to access a genie they don't have permission for.

<ParamField type="string">
  `request-access`
</ParamField>

<ParamField type="string">
  Genie UUID.
</ParamField>

***

## Accept invite

Accepts an invitation to access a genie using an access token.

<ParamField type="string">
  `accept-invite`
</ParamField>

<ParamField type="string">
  Genie UUID.
</ParamField>

***

## Error codes

| Code               | Status | Description                      |
| ------------------ | ------ | -------------------------------- |
| `UNAUTHORIZED`     | 401    | Missing or invalid token         |
| `INVALID_TOKEN`    | 401    | Token validation failed          |
| `FORBIDDEN`        | 403    | User lacks required permissions  |
| `AGENT_NOT_FOUND`  | 404    | Genie not found or access denied |
| `VALIDATION_ERROR` | 400    | Invalid request parameters       |
| `INTERNAL_ERROR`   | 500    | Server error                     |


# Goals
Source: https://docs.helpgenie.ai/api-reference/goals

Manage goal records, outcomes, and lead-info presets for agents

Use `goals` to create, manage, and attach goal records to agents. Goals represent targets or outcomes that an agent should achieve, and can include lead-info field definitions.

Supported actions: `list`, `get`, `create`, `update`, `delete`, `attach`, `detach`, `generate`.

***

## List goals

Retrieves all goals for the authenticated user with optional filtering.

<ParamField type="string">
  Must be `"goals"`.
</ParamField>

<ParamField type="string">
  Must be `"list"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Results per page. Range: 1-1000. Default: `50`.
    </ParamField>

    <ParamField type="number">
      Pagination offset. Default: `0`.
    </ParamField>

    <ParamField type="string">
      Filter goals to a specific agent.
    </ParamField>

    <ParamField type="string">
      Filter by goal status.
    </ParamField>

    <ParamField type="string">
      Search goals by name.
    </ParamField>

    <ParamField type="boolean">
      Admin only. View other users' goals.
    </ParamField>

    <ParamField type="string">
      Admin only. Scope to a specific user's goals.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="items" type="object[]">
      Array of goal objects. See [goal object](#goal-object).
    </ResponseField>

    <ResponseField name="count" type="number" />

    <ResponseField name="limit" type="number" />

    <ResponseField name="offset" type="number" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    items: Goal[];
    count: number;
  }>({
    resource: "goals",
    action: "list",
    data: {
      agentId: "agent-uuid",
      status: "active",
      limit: 50,
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/goals \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "list",
      "data": { "agentId": "agent-uuid", "status": "active" }
    }'
  ```
</CodeGroup>

***

## Get a goal

Retrieves a specific goal by ID.

<ParamField type="string">
  Must be `"goals"`.
</ParamField>

<ParamField type="string">
  Must be `"get"`.
</ParamField>

<ParamField type="string">
  The goal UUID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      Admin only. Allows fetching other users' goals.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="goal" type="object">
      See [goal object](#goal-object).
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Create a goal

Creates a new goal associated with an agent.

<ParamField type="string">
  Must be `"goals"`.
</ParamField>

<ParamField type="string">
  Must be `"create"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Goal name.
    </ParamField>

    <ParamField type="string">
      Associated agent ID.
    </ParamField>

    <ParamField type="string">
      Goal description.
    </ParamField>

    <ParamField type="string">
      Goal status. Default: `"active"`.
    </ParamField>

    <ParamField type="number">
      Priority level.
    </ParamField>

    <ParamField type="string">
      Admin only. Create goal on behalf of another user.
    </ParamField>
  </Expandable>
</ParamField>

### Response (status 201)

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="goal" type="object">
      The created goal object.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Update a goal

Updates an existing goal. Supports partial updates.

<ParamField type="string">
  Must be `"goals"`.
</ParamField>

<ParamField type="string">
  Must be `"update"`.
</ParamField>

<ParamField type="string">
  The goal UUID.
</ParamField>

<ParamField type="object">
  Any combination of `name`, `description`, `status`, `priority`, `agent_id`.
</ParamField>

***

## Delete a goal

Permanently deletes a goal.

<ParamField type="string">
  Must be `"goals"`.
</ParamField>

<ParamField type="string">
  Must be `"delete"`.
</ParamField>

<ParamField type="string">
  The goal UUID.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="message" type="string" />

    <ResponseField name="goalId" type="string" />
  </Expandable>
</ResponseField>

***

## Attach goal to agent

Links a goal (lead-info preset) to an agent. Any existing attachment for that agent is replaced.

<ParamField type="string">
  Must be `"goals"`.
</ParamField>

<ParamField type="string">
  Must be `"attach"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The goal to attach.
    </ParamField>

    <ParamField type="string">
      The agent to attach the goal to.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="message" type="string" />
  </Expandable>
</ResponseField>

<Note>
  Verifies ownership of both the goal and the agent before attaching.
</Note>

<CodeGroup>
  ```typescript Example request theme={null}
  await ApiService.invoke({
    resource: "goals",
    action: "attach",
    data: {
      goalId: "goal-uuid",
      agentId: "agent-uuid",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/goals \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "attach",
      "data": {
        "goalId": "goal-uuid",
        "agentId": "agent-uuid"
      }
    }'
  ```
</CodeGroup>

***

## Detach goal from agent

Removes a goal attachment from an agent.

<ParamField type="string">
  Must be `"goals"`.
</ParamField>

<ParamField type="string">
  Must be `"detach"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The goal to detach.
    </ParamField>

    <ParamField type="string">
      The agent to detach the goal from.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="message" type="string" />
  </Expandable>
</ResponseField>

***

## Generate goal

Uses AI to generate a goal configuration from a natural-language description. Returns suggested fields that can be reviewed before saving.

<ParamField type="string">
  Must be `"goals"`.
</ParamField>

<ParamField type="string">
  Must be `"generate"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Natural-language description of the goal to generate.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="name" type="string">
      Suggested goal name.
    </ResponseField>

    <ResponseField name="description" type="string">
      Suggested goal description.
    </ResponseField>

    <ResponseField name="fields" type="object[]">
      Up to 50 suggested lead-info fields.

      <Expandable title="field properties">
        <ResponseField name="type" type="string">
          Field type: `text`, `email`, `phone`, `textarea`, or `select`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="confidence" type="number">
      Confidence score from 0 to 1.
    </ResponseField>
  </Expandable>
</ResponseField>

<Info>
  Generation uses AI (temperature 0.5). Results are suggestions — review before saving.
</Info>

<CodeGroup>
  ```typescript Example request theme={null}
  const result = await ApiService.invoke({
    resource: "goals",
    action: "generate",
    data: {
      description: "Collect customer name, email, and preferred contact time for callback scheduling",
    },
  });
  ```
</CodeGroup>

***

## Goal object

<ResponseField name="id" type="string" />

<ResponseField name="agent_id" type="string" />

<ResponseField name="name" type="string" />

<ResponseField name="description" type="string | null" />

<ResponseField name="status" type="string" />

<ResponseField name="priority" type="number | null" />

<ResponseField name="created_at" type="string" />

<ResponseField name="updated_at" type="string" />

<ResponseField name="owner" type="object">
  Present only in admin mode.

  <Expandable title="properties">
    <ResponseField name="id" type="string" />

    <ResponseField name="full_name" type="string" />

    <ResponseField name="email" type="string" />
  </Expandable>
</ResponseField>

***

## Error responses

| Status | Code               | Description                       |
| ------ | ------------------ | --------------------------------- |
| 400    | `VALIDATION_ERROR` | Invalid parameters                |
| 401    | `UNAUTHORIZED`     | Missing or invalid authentication |
| 403    | `FORBIDDEN`        | Access denied                     |
| 404    | `NOT_FOUND`        | Goal not found                    |
| 500    | `INTERNAL_ERROR`   | Server error                      |


# Insights
Source: https://docs.helpgenie.ai/api-reference/insights

Derived outcome signals and the 'needs attention' feed — powering the Activity page summary tiles and prioritised action list.

Insights aggregate conversation data into actionable signals. All data covers a rolling 7-day window. Workspace members have access to the same scope as their workspace owner.

***

## Actions

### `weekly-summary`

Returns a high-level summary of the past 7 days compared to the previous 7-day window. Powers the four summary tiles at the top of the Activity page.

**Parameters**

| Field       | Type    | Required | Description                             |
| ----------- | ------- | -------- | --------------------------------------- |
| `adminMode` | boolean | No       | Admin only — aggregate across all users |
| `userId`    | string  | No       | Admin only — scope to a specific user   |

**Response**

```json theme={null}
{
  "conversations": {
    "current": 42,
    "previous": 35,
    "delta": 20
  },
  "leads": {
    "current": 8,
    "previous": 6,
    "delta": 33
  },
  "afterHours": {
    "current": 11
  },
  "attention": {
    "current": 5,
    "escalations": 2,
    "lowSentiment": 2,
    "negativeFeedback": 1
  },
  "silentGenies": {
    "current": 1,
    "total": 4
  },
  "window": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-08T00:00:00Z"
  }
}
```

`delta` is the integer percentage change from the previous to the current window, or `null` if there is no previous data.

`afterHours.current` is the number of conversations in the window that occurred outside business hours (before 8 am, after 6 pm, or on a weekend), calculated in the account owner's timezone. Returns `null` when the account timezone is not configured.

`leads` is retained for API compatibility. The leads feature is being retired and `leads` will be removed in a future release — do not build new integrations against it.

***

### `needs-attention`

Returns a prioritised feed of items that require action — escalations, low-sentiment conversations, negative feedback, and Genies with no recent conversations. Up to 10 items per bucket, covering the last 7 days.

**Parameters**

| Field       | Type    | Required | Description |
| ----------- | ------- | -------- | ----------- |
| `adminMode` | boolean | No       | Admin only  |
| `userId`    | string  | No       | Admin only  |

**Response**

```json theme={null}
{
  "escalations": [
    {
      "id": "detail-id",
      "conversationId": "conv-id",
      "agentId": "agent-uuid",
      "agentName": "Support Genie",
      "agentBranding": null,
      "summary": "Caller requested human escalation.",
      "occurredAt": "2024-01-07T10:00:00Z",
      "reason": "requested_human"
    }
  ],
  "lowSentiment": [
    {
      "id": "detail-id",
      "conversationId": "conv-id",
      "agentId": "agent-uuid",
      "agentName": "Support Genie",
      "agentBranding": null,
      "summary": "Caller was frustrated with the response.",
      "score": 0.21,
      "occurredAt": "2024-01-07T11:00:00Z"
    }
  ],
  "negativeFeedback": [
    {
      "id": "feedback-id",
      "conversationId": "conv-id",
      "agentId": "agent-uuid",
      "agentName": "Support Genie",
      "agentBranding": null,
      "feedbackText": "Didn't answer my question.",
      "occurredAt": "2024-01-07T12:00:00Z"
    }
  ],
  "silentGenies": [
    {
      "agentId": "agent-uuid",
      "agentName": "Onboarding Genie",
      "agentBranding": null,
      "createdAt": "2023-12-01T00:00:00Z"
    }
  ],
  "threshold": 0.4,
  "window": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-08T00:00:00Z"
  }
}
```

`threshold` is the sentiment score below which a conversation is classified as low sentiment.

***

## Error codes

| Code             | Meaning                 |
| ---------------- | ----------------------- |
| `INTERNAL_ERROR` | Unexpected server error |


# API reference
Source: https://docs.helpgenie.ai/api-reference/introduction

Complete API conventions: auth, request formats, errors, and core resources

## Base URLs

HelpGenie supports both REST-style routes and direct Supabase function invocation.

```
Primary: https://api.helpgenie.ai/v1
Alternative: https://helpgenie.ai/api/v1
Direct Supabase: POST https://api.helpgenie.ai/v1
```

REST routes follow:

```
{BASE_URL}/{resource}[/{id}]
```

## Authentication

All auth methods use the `Authorization` header.

```
Authorization: Bearer <token>
```

### API key (recommended for external integrations)

```
Authorization: Bearer hg_live_...
```

* Prefix: `hg_live_`
* Rate limit: `60 requests/minute` per key
* Maximum `5` active keys per user

### Session JWT (browser/app context)

```
Authorization: Bearer <supabase_access_token>
```

### Service role key (server-to-server)

```
Authorization: Bearer <SUPABASE_SERVICE_ROLE_KEY>
x-user-id: <user-uuid>
Content-Type: application/json
```

## Request formats

### REST-style (recommended)

```
GET    /v1/{resource}         → action: "all"
GET    /v1/{resource}/list    → action: "list"
GET    /v1/{resource}/{id}    → action: "get"
POST   /v1/{resource}         → action: "create"
PATCH  /v1/{resource}/{id}    → action: "update"
DELETE /v1/{resource}/{id}    → action: "delete"
```

### Custom actions (POST body)

```json theme={null}
POST /v1/{resource}
{
  "action": "custom-action",
  "id": "optional-id",
  "data": {}
}
```

### Direct invocation (POST body)

```json theme={null}
POST https://api.helpgenie.ai/v1
{
  "resource": "genies",
  "action": "list",
  "id": null,
  "data": {}
}
```

<ParamField type="string">
  API resource name. Example: `genies`, `knowledge-base`, `integrations`, `api-keys`.
</ParamField>

<ParamField type="string">
  Action for the selected resource (for example `list`, `get`, `create`, `update`, `delete`).
</ParamField>

<ParamField type="string">
  Optional resource identifier for single-record actions.
</ParamField>

<ParamField type="object">
  Action-specific parameters (filters, pagination, payload fields).
</ParamField>

## Response envelope

```json theme={null}
{
  "success": true,
  "data": {
    // action-specific response data
  }
}
```

**Error (4xx / 5xx):**

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "status": 400
  }
}
```

## Error codes

| Code                  | Status | Description                             |
| --------------------- | ------ | --------------------------------------- |
| `UNAUTHORIZED`        | 401    | Missing or invalid Authorization header |
| `INVALID_TOKEN`       | 401    | Token is invalid or expired             |
| `FORBIDDEN`           | 403    | User lacks permission for the resource  |
| `NOT_FOUND`           | 404    | Resource not found                      |
| `AGENT_NOT_FOUND`     | 404    | Genie not found or access denied        |
| `VALIDATION_ERROR`    | 400    | Invalid request format or data          |
| `INVALID_ACTION`      | 400    | Action not supported for the resource   |
| `RATE_LIMIT_EXCEEDED` | 429    | Too many requests                       |
| `INTERNAL_ERROR`      | 500    | Server error                            |

## Access control

Roles determine access scope:

* **internal\_admin** - Full cross-account access.
* **standard\_user** - Access to their own business data.
* **consumer** - Limited read-only/interaction access.

Admin users can pass `adminMode: true` or a `userId` parameter to operate on resources owned by other users.

## Resource map

<CardGroup>
  <Card title="Genies" icon="robot" href="/api-reference/genies">
    Create, update, list, and delete voice AI genies
  </Card>

  <Card title="Genie groups" icon="layer-group" href="/api-reference/genie-groups">
    Group and organize genies
  </Card>

  <Card title="Conversations" icon="comments" href="/api-reference/conversations">
    Sync, analyze, and manage conversations
  </Card>

  <Card title="Knowledge base" icon="book" href="/api-reference/knowledge-base">
    Manage documents and attach them to genies
  </Card>

  <Card title="Document folders" icon="folder" href="/api-reference/document-folders">
    Organize knowledge base documents into folders
  </Card>

  <Card title="Voices" icon="microphone" href="/api-reference/voices">
    Manage voice favorites and track usage
  </Card>

  <Card title="Voice collections" icon="music" href="/api-reference/voice-collections">
    Create and manage curated voice collections
  </Card>

  <Card title="Leads" icon="user-plus" href="/api-reference/leads">
    Capture and manage customer leads
  </Card>

  <Card title="Lead notes" icon="sticky-note" href="/api-reference/lead-notes">
    Add and manage notes on leads
  </Card>

  <Card title="Marketplace" icon="store" href="/api-reference/marketplace">
    Browse and publish genie templates
  </Card>

  <Card title="Profiles" icon="user" href="/api-reference/profiles">
    Manage user profiles and settings
  </Card>

  <Card title="Teams" icon="users" href="/api-reference/teams">
    Create teams, invite members, manage roles
  </Card>

  <Card title="Activities" icon="clock" href="/api-reference/activities">
    Track platform activity and audit logs
  </Card>

  <Card title="Goals" icon="target" href="/api-reference/goals">
    Manage agent goals and outcomes
  </Card>

  <Card title="API keys" icon="key" href="/api-reference/api-keys">
    Create, revoke, and delete developer API keys
  </Card>

  <Card title="Phone numbers" icon="phone" href="/api-reference/phone-numbers">
    Provision, release, and manage Twilio phone numbers
  </Card>

  <Card title="QR codes" icon="qrcode" href="/api-reference/qr-code">
    Manage QR code images for genie pages
  </Card>

  <Card title="Worker genies" icon="gears" href="/api-reference/worker-genies">
    Autonomous background AI agents for tasks and integrations
  </Card>

  <Card title="Analytics" icon="chart-line" href="/api-reference/analytics">
    Platform analytics, trends, and genie performance
  </Card>

  <Card title="Billing" icon="credit-card" href="/api-reference/billing">
    Subscriptions, usage, invoices, and checkout
  </Card>

  <Card title="Branding" icon="palette" href="/api-reference/branding">
    Team branding, logos, and style configuration
  </Card>

  <Card title="Portals" icon="window" href="/api-reference/portals">
    Create multi-genie portal pages
  </Card>

  <Card title="Agent pages" icon="browser" href="/api-reference/agent-pages">
    Manage individual genie landing pages
  </Card>

  <Card title="Integrations" icon="plug" href="/api-reference/integrations">
    Connect external services and APIs
  </Card>

  <Card title="Automations" icon="bolt" href="/api-reference/automations">
    Create and manage automated workflows
  </Card>

  <Card title="Playbooks" icon="book-open" href="/api-reference/playbooks">
    Browse and apply pre-built genie playbooks
  </Card>

  <Card title="Capabilities" icon="sparkles" href="/api-reference/capabilities">
    Discover resources and actions at runtime
  </Card>
</CardGroup>


# Knowledge base
Source: https://docs.helpgenie.ai/api-reference/knowledge-base

Manage documents, attach them to genies, and sync content across agents

The knowledge base stores documents that genies reference during conversations. Documents can be created from PDFs, websites, YouTube videos, or plain text. Each document is stored both in the HelpGenie database and in the voice agent system.

<Note>
  Standard users can only access their own documents. Admin users can access all documents and filter by owner when passing `adminMode: true`.
</Note>

***

## List all documents

Retrieves all documents with pagination, filtering, and role-based access control. Returns documents along with their dependent agents.

<ParamField type="string">
  Must be `"knowledge-base"`
</ParamField>

<ParamField type="string">
  Must be `"all"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Results per page. Maximum 500.
    </ParamField>

    <ParamField type="number">
      Number of results to skip.
    </ParamField>

    <ParamField type="object">
      <Expandable title="properties">
        <ParamField type="string">
          Filter by document name (case-insensitive).
        </ParamField>

        <ParamField type="string">
          Filter by visibility: `"public"` or `"private"`.
        </ParamField>

        <ParamField type="string">
          Filter by document source type (for example `"pdf_upload"`, `"website"`, `"youtube"`).
        </ParamField>

        <ParamField type="string">
          Filter by active status: `"active"` or `"inactive"`.
        </ParamField>

        <ParamField type="string">
          Filter by processing status (for example `"completed"`, `"pending"`, `"failed"`).
        </ParamField>

        <ParamField type="string">
          Filter by folder ID. Pass `null` for uncategorized documents.
        </ParamField>

        <ParamField type="string">
          Filter to documents attached to a specific genie. Pass `"all"` or omit to include all documents.
        </ParamField>

        <ParamField type="boolean">
          When `true`, only returns documents that have been synced to the knowledge base system (have an active external document ID).
        </ParamField>

        <ParamField type="string">
          Admin only. Filter by owner name (partial match).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="documents" type="array">
      <Expandable title="item properties">
        <ResponseField name="id" type="string">Document UUID.</ResponseField>
        <ResponseField name="name" type="string">Document name.</ResponseField>
        <ResponseField name="url" type="string">Source URL or storage URL.</ResponseField>
        <ResponseField name="is_active" type="boolean">Whether the document is active.</ResponseField>
        <ResponseField name="is_public" type="boolean">Whether the document is publicly visible.</ResponseField>
        <ResponseField name="el_doc_id" type="string">External document identifier used by the voice platform.</ResponseField>
        <ResponseField name="user_id" type="string">Owner user ID.</ResponseField>
        <ResponseField name="folder_id" type="string | null">Folder ID, or `null` if uncategorized.</ResponseField>

        <ResponseField name="metadata" type="object">
          <Expandable title="properties">
            <ResponseField name="pdf_size" type="number">File size in bytes.</ResponseField>
            <ResponseField name="type" type="string">Document type (for example `"pdf_upload"`).</ResponseField>
            <ResponseField name="total_pages" type="number">Number of pages (PDFs only).</ResponseField>
            <ResponseField name="source" type="string">Source type.</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
        <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
        <ResponseField name="folder" type="object | null">Folder details, if assigned.</ResponseField>
        <ResponseField name="owner" type="object | null">Owner profile (admin mode only).</ResponseField>

        <ResponseField name="dependent_agents" type="array">
          Genies that use this document.

          <Expandable title="item properties">
            <ResponseField name="id" type="string">Genie ID.</ResponseField>
            <ResponseField name="name" type="string">Genie name.</ResponseField>
            <ResponseField name="category" type="string">Genie category.</ResponseField>
            <ResponseField name="is_active" type="boolean">Whether the genie is active.</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number">Total matching documents.</ResponseField>
    <ResponseField name="inKBCount" type="number">Number of matching documents that have been synced to the knowledge base system (i.e. have an active external document ID). Filters applied to the main query are also applied here.</ResponseField>
    <ResponseField name="limit" type="number">Applied limit.</ResponseField>
    <ResponseField name="offset" type="number">Applied offset.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("knowledge-base", "all", undefined, {
    limit: 50,
    offset: 0,
    filters: {
      searchTerm: "product",
      selectedPrivacy: "public",
      selectedSourceType: "pdf_upload",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "all",
      "data": {
        "limit": 50,
        "offset": 0,
        "filters": {
          "searchTerm": "product",
          "selectedPrivacy": "public",
          "selectedSourceType": "pdf_upload"
        }
      }
    }'
  ```

  ```json Request body theme={null}
  {
    "resource": "knowledge-base",
    "action": "all",
    "data": {
      "limit": 50,
      "offset": 0,
      "filters": {
        "searchTerm": "product",
        "selectedPrivacy": "public",
        "selectedSourceType": "pdf_upload"
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "documents": [
        {
          "id": "770e8400-e29b-41d4-a716-446655440002",
          "name": "Product Documentation",
          "url": "https://storage.example.com/documents/product-docs.pdf",
          "is_active": true,
          "is_public": true,
          "el_doc_id": "el-doc-123",
          "user_id": "660e8400-e29b-41d4-a716-446655440001",
          "folder_id": null,
          "metadata": {
            "pdf_size": 2048576,
            "type": "pdf_upload",
            "total_pages": 45,
            "source": "pdf_upload"
          },
          "created_at": "2024-01-15T10:30:00.000Z",
          "updated_at": "2024-01-15T10:30:00.000Z",
          "folder": null,
          "owner": null,
          "dependent_agents": [
            {
              "id": "880e8400-e29b-41d4-a716-446655440003",
              "name": "Customer Support",
              "category": "support",
              "is_active": true
            }
          ]
        }
      ],
      "count": 125,
      "inKBCount": 98,
      "limit": 50,
      "offset": 0
    }
  }
  ```
</CodeGroup>

***

## List documents

Retrieves a compact, paginated list of documents. Returns only essential fields — optimized for dropdowns, selects, and search results. For full document details including metadata and folder info, use the `all` action instead.

<ParamField type="string">
  Must be `"knowledge-base"`
</ParamField>

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

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Results per page. Maximum 500.
    </ParamField>

    <ParamField type="number">
      Number of results to skip.
    </ParamField>

    <ParamField type="object">
      <Expandable title="properties">
        <ParamField type="string">
          Filter by document name (case-insensitive).
        </ParamField>

        <ParamField type="string">
          Filter by visibility: `"public"` or `"private"`.
        </ParamField>

        <ParamField type="string">
          Filter by document type (for example `"pdf_upload"`, `"website"`).
        </ParamField>

        <ParamField type="string">
          Filter by folder ID. Pass `null` for uncategorized documents.
        </ParamField>

        <ParamField type="string">
          Filter to documents attached to a specific genie. Pass `"all"` or omit to include all documents.
        </ParamField>

        <ParamField type="string">
          Admin only. Filter by owner name (partial match).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="boolean">
      Admin only. When `true`, includes owner profile in each item and allows `userId` filtering.
    </ParamField>

    <ParamField type="string">
      Admin only. Return documents owned by this user ID.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="documents" type="array">
      <Expandable title="item properties">
        <ResponseField name="id" type="string">Document UUID.</ResponseField>
        <ResponseField name="name" type="string">Document name.</ResponseField>
        <ResponseField name="el_doc_id" type="string | null">External document identifier used by the voice platform, or `null` if not yet synced.</ResponseField>
        <ResponseField name="is_public" type="boolean">Whether the document is publicly visible.</ResponseField>
        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
        <ResponseField name="owner" type="object | null">Owner profile — present only when `adminMode` is `true`.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number">Total matching documents.</ResponseField>
    <ResponseField name="limit" type="number">Applied limit.</ResponseField>
    <ResponseField name="offset" type="number">Applied offset.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("knowledge-base", "list", undefined, {
    limit: 50,
    offset: 0,
    filters: {
      searchTerm: "FAQ",
      agentId: "550e8400-e29b-41d4-a716-446655440000",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "knowledge-base",
      "action": "list",
      "data": {
        "limit": 50,
        "offset": 0,
        "filters": {
          "searchTerm": "FAQ"
        }
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "documents": [
        {
          "id": "770e8400-e29b-41d4-a716-446655440002",
          "name": "Product FAQ",
          "el_doc_id": "el-doc-123",
          "is_public": true,
          "created_at": "2024-01-15T10:30:00.000Z"
        }
      ],
      "count": 1,
      "limit": 50,
      "offset": 0
    }
  }
  ```
</CodeGroup>

***

## Get document

Retrieves a single document by its UUID or 20-character external document ID. Returns full details including metadata, folder info, and dependent agents.

<ParamField type="string">
  Must be `"knowledge-base"`
</ParamField>

<ParamField type="string">
  Must be `"get"`
</ParamField>

<ParamField type="string">
  The document UUID or external document ID (`el_doc_id`).
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      Admin only. Include owner profile information.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="document" type="object">
      Full document object including `id`, `name`, `url`, `is_active`, `is_public`, `el_doc_id`, `user_id`, `folder_id`, `metadata`, `folder`, `owner`, `dependent_agents`, `created_at`, and `updated_at`.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "documents",
    "get",
    "770e8400-e29b-41d4-a716-446655440002"
  );
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "get",
      "id": "770e8400-e29b-41d4-a716-446655440002"
    }'
  ```

  ```json Request body theme={null}
  {
    "resource": "knowledge-base",
    "action": "get",
    "id": "770e8400-e29b-41d4-a716-446655440002"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "document": {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "name": "Product Documentation",
        "url": "https://storage.example.com/documents/product-docs.pdf",
        "is_active": true,
        "is_public": true,
        "el_doc_id": "el-doc-123",
        "user_id": "660e8400-e29b-41d4-a716-446655440001",
        "folder_id": "550e8400-e29b-41d4-a716-446655440000",
        "metadata": {
          "pdf_size": 2048576,
          "type": "pdf_upload",
          "total_pages": 45,
          "source": "pdf_upload"
        },
        "created_at": "2024-01-15T10:30:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z",
        "folder": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Documentation",
          "color": "#FF5733",
          "icon": "folder",
          "position": 0
        },
        "owner": null,
        "dependent_agents": [
          {
            "id": "880e8400-e29b-41d4-a716-446655440003",
            "name": "Customer Support",
            "category": "support",
            "is_active": true
          }
        ]
      }
    }
  }
  ```
</CodeGroup>

<Note>
  Non-admin users can only access their own documents or documents marked as public. Admin users with `adminMode: true` can access all documents and see owner information.
</Note>

***

## Get document content

Retrieves the plain-text content of a document. Uses a priority order: manual edits → optimised content → original parsed content.

<ParamField type="string">
  Must be `"knowledge-base"`
</ParamField>

<ParamField type="string">
  Must be `"get-content"`
</ParamField>

<ParamField type="string">
  The document UUID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      When `true` (default), optimised content is tried before falling back to the original parsed content. Set to `false` to skip the optimised version and fetch the raw parsed content directly.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="documentId" type="string">Document UUID.</ResponseField>
    <ResponseField name="name" type="string">Document name.</ResponseField>
    <ResponseField name="content" type="string">The document's text content.</ResponseField>

    <ResponseField name="source" type="string">
      Which content version was returned: `"edited"` (manual override), `"optimized"` (processed version), or `"parsed"` (original extraction).
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Non-admin users can only retrieve content for their own documents or documents marked as public. A `404` is returned when no readable content is available yet — the document may still be processing.
</Note>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke({
    resource: "knowledge-base",
    action: "get-content",
    id: "770e8400-e29b-41d4-a716-446655440002",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "knowledge-base",
      "action": "get-content",
      "id": "770e8400-e29b-41d4-a716-446655440002"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "documentId": "770e8400-e29b-41d4-a716-446655440002",
      "name": "Product Documentation",
      "content": "Welcome to Acme Products...\n\nThis guide covers installation, configuration, and troubleshooting.",
      "source": "optimized"
    }
  }
  ```
</CodeGroup>

***

## Create document (text)

The simplest way to add a knowledge base document. Pass `title` and `content` directly — no file upload needed. If you omit the nested `action` field, `create-notes` is used by default.

<ParamField type="string">
  Must be `"knowledge-base"`
</ParamField>

<ParamField type="string">
  Must be `"create"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Document name. Defaults to `"Notes {timestamp}"`.
    </ParamField>

    <ParamField type="string">
      Plain text content for the document.
    </ParamField>

    <ParamField type="string">
      Genie UUID. If provided, the document is automatically attached to this genie.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.helpgenie.ai/v1/knowledge-base \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "create",
      "title": "Company FAQ",
      "content": "Q: What are your hours?\nA: Monday-Friday 9am-5pm.",
      "agentId": "genie-uuid"
    }'
  ```

  ```json Request body theme={null}
  {
    "resource": "knowledge-base",
    "action": "create",
    "data": {
      "title": "Company FAQ",
      "content": "Q: What are your hours?\nA: Monday-Friday 9am-5pm.",
      "agentId": "genie-uuid"
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "success": true,
      "document": {
        "id": "doc-uuid",
        "name": "Company FAQ",
        "metadata": {
          "source": "notes",
          "status": "pending",
          "stage": "pending_extraction"
        }
      }
    }
  }
  ```
</CodeGroup>

<Note>
  Documents are processed asynchronously. After creation, the document transitions through stages: `pending_extraction` → `pending_optimization` → `completed`.
</Note>

***

## Create document (advanced)

For content sources other than text, use the nested sub-action pattern. The `create` action delegates to the internal document upload pipeline.

<ParamField type="string">
  Must be `"knowledge-base"`
</ParamField>

<ParamField type="string">
  Must be `"create"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The upload sub-action. One of:

      * `"upload-website"` -- Extract content from a URL
      * `"scrape-website"` -- Scrape and parse website content
      * `"extract-youtube"` -- Extract transcript from a YouTube video
      * `"upload-pdf"` -- Upload and process a PDF file
      * `"extract-document"` -- Extract content from various document formats
    </ParamField>

    <ParamField type="object">
      Sub-action-specific parameters. For `upload-website`, pass `{ "url": "https://..." }`.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="document" type="object">
      <Expandable title="properties">
        <ResponseField name="id" type="string">New document ID.</ResponseField>
        <ResponseField name="el_doc_id" type="string">External document ID used by the voice platform.</ResponseField>
        <ResponseField name="name" type="string">Extracted document name.</ResponseField>
        <ResponseField name="metadata" type="object">Source metadata.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<Info>
  The `create` action delegates to the internal document upload pipeline (`doc-upload` edge function). The nested `data.action` field determines which content source is used. Supported sub-actions:

  * `upload-website` -- Extract content from a single URL
  * `scrape-website` -- Crawl and parse website content
  * `extract-youtube` -- Extract the transcript from a YouTube video URL
  * `upload-pdf` -- Upload and process a PDF file
  * `extract-document` -- Extract content from various document formats (DOCX, TXT, etc.)
</Info>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("knowledge-base", "create", undefined, {
    action: "upload-website",
    data: {
      url: "https://example.com/documentation",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "create",
      "data": {
        "action": "upload-website",
        "data": {
          "url": "https://example.com/documentation"
        }
      }
    }'
  ```

  ```json Request body theme={null}
  {
    "resource": "knowledge-base",
    "action": "create",
    "data": {
      "action": "upload-website",
      "data": {
        "url": "https://example.com/documentation"
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "document": {
        "id": "doc-new-id",
        "el_doc_id": "el-doc-123",
        "name": "Extracted Document",
        "metadata": {
          "source": "website",
          "url": "https://example.com/documentation"
        }
      }
    }
  }
  ```
</CodeGroup>

***

## Update document (data mode)

Updates document metadata fields without changing the content. Only the fields you provide are updated. Metadata is intelligently merged with existing values. If the document name changes and the document has been synced with the voice platform, the name is also updated there.

<ParamField type="string">
  Must be `"knowledge-base"`
</ParamField>

<ParamField type="string">
  Must be `"update"`
</ParamField>

<ParamField type="string">
  The document UUID to update.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Use `"data"` to update metadata fields. Can be omitted — when no `content` field is present, `data` mode is inferred automatically.
    </ParamField>

    <ParamField type="string">
      New document name. If the document has been synced with the voice platform, it will be renamed there as well.
    </ParamField>

    <ParamField type="boolean">
      Active status.
    </ParamField>

    <ParamField type="boolean">
      Public visibility.
    </ParamField>

    <ParamField type="string | null">
      Folder ID for organization. Pass `null` to remove from any folder.
    </ParamField>

    <ParamField type="boolean">
      Personal document flag.
    </ParamField>

    <ParamField type="string">
      Admin only. Reassign document ownership to this user ID.
    </ParamField>

    <ParamField type="object">
      Custom metadata key-value pairs. Merged with existing metadata — not overwritten.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="document" type="object">
      The updated document object with all current field values.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "documents",
    "update",
    "770e8400-e29b-41d4-a716-446655440002",
    {
      mode: "data",
      name: "Updated Product Documentation",
      is_active: true,
      is_public: false,
      folder_id: "550e8400-e29b-41d4-a716-446655440000",
    }
  );
  ```

  ```json Request body theme={null}
  {
    "resource": "knowledge-base",
    "action": "update",
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "data": {
      "mode": "data",
      "name": "Updated Product Documentation",
      "is_active": true,
      "is_public": false,
      "folder_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "document": {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "name": "Updated Product Documentation",
        "is_active": true,
        "is_public": false,
        "folder_id": "550e8400-e29b-41d4-a716-446655440000",
        "metadata": {
          "pdf_size": 2048576,
          "type": "pdf_upload",
          "total_pages": 45,
          "source": "pdf_upload"
        },
        "updated_at": "2024-01-15T11:00:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

***

## Update document (content mode)

Replaces the document content. A new voice platform document is created with the updated content, and all dependent genies are automatically updated with the new external document ID (fire-and-forget sync). The new content is also saved to storage and a signed URL is returned.

<ParamField type="string">
  Must be `"knowledge-base"`
</ParamField>

<ParamField type="string">
  Must be `"update"`
</ParamField>

<ParamField type="string">
  The document UUID to update.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Use `"content"` to replace document content. Can be omitted — when a `content` string is present, content mode is inferred automatically.
    </ParamField>

    <ParamField type="string">
      The new document content (non-empty string).
    </ParamField>

    <ParamField type="boolean">
      When `true`, content is stored with an `_optimized` suffix and the document metadata is flagged as optimized. When `false`, content is stored with an `_edited` suffix.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="document" type="object">
      Updated document with the new `el_doc_id` and storage metadata.
    </ResponseField>

    <ResponseField name="contentType" type="string">
      Either `"edited"` or `"optimized"`.
    </ResponseField>

    <ResponseField name="storagePath" type="string">
      Path to the stored content file.
    </ResponseField>

    <ResponseField name="signedUrl" type="string">
      Signed URL for accessing the content (valid for 7 days).
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "documents",
    "update",
    "770e8400-e29b-41d4-a716-446655440002",
    {
      mode: "content",
      content: "Updated document content with revised product information...",
      isOptimized: false,
    }
  );
  ```

  ```json Request body theme={null}
  {
    "resource": "knowledge-base",
    "action": "update",
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "data": {
      "mode": "content",
      "content": "Updated document content with revised product information...",
      "isOptimized": false
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "document": {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "el_doc_id": "el-doc-new-id",
        "name": "Product Documentation",
        "metadata": {
          "pdf_size": 2048576,
          "type": "pdf_upload",
          "source": "pdf_upload",
          "edited_url": "https://signed.url/documents/edited/product_documentation_edited.txt?expires=..."
        },
        "updated_at": "2024-01-15T11:30:00.000Z"
      },
      "contentType": "edited",
      "storagePath": "documents/edited/product_documentation_edited.txt",
      "signedUrl": "https://signed.url/documents/edited/product_documentation_edited.txt?expires=..."
    }
  }
  ```
</CodeGroup>

<Note>
  Content mode deletes the old external document and creates a new one. All genies that depend on this document are automatically updated with the new external document ID.
</Note>

***

## Bulk update documents

Updates multiple documents at once. Only metadata fields can be bulk-updated — document content cannot be changed via this action.

<ParamField type="string">
  Must be `"knowledge-base"`
</ParamField>

<ParamField type="string">
  Must be `"bulk-update"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string[]">
      Array of document UUIDs to update. Must contain at least one ID.
    </ParamField>

    <ParamField type="object">
      Fields to apply across all listed documents. At least one field is required. Only the fields you include are written — unspecified fields are left unchanged.

      <Expandable title="properties">
        <ParamField type="boolean">Active status.</ParamField>
        <ParamField type="boolean">Public visibility.</ParamField>
        <ParamField type="boolean">Private visibility flag.</ParamField>
        <ParamField type="string | null">Folder assignment. Pass `null` to remove from any folder.</ParamField>
        <ParamField type="string | null">Associates the documents with a specific consumer genie. Pass `null` to clear the association.</ParamField>
        <ParamField type="string">Document processing status.</ParamField>
        <ParamField type="string">Source type override.</ParamField>
        <ParamField type="string">Admin only. Reassigns document ownership to this user ID.</ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">Whether all documents were updated successfully.</ResponseField>
<ResponseField name="message" type="string">Human-readable summary of the operation.</ResponseField>
<ResponseField name="updatedCount" type="number">Number of documents actually updated.</ResponseField>
<ResponseField name="documentIds" type="string[]">The document IDs that were targeted by the update.</ResponseField>
<ResponseField name="updates" type="object">The update payload that was applied, containing only the fields that were provided.</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("knowledge-base", "bulk-update", undefined, {
    documentIds: ["doc-id-1", "doc-id-2", "doc-id-3"],
    updates: {
      is_active: true,
      folder_id: "folder-uuid",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "bulk-update",
      "data": {
        "documentIds": ["doc-id-1", "doc-id-2", "doc-id-3"],
        "updates": {
          "is_active": true,
          "folder_id": "folder-uuid"
        }
      }
    }'
  ```

  ```json Request body theme={null}
  {
    "resource": "knowledge-base",
    "action": "bulk-update",
    "data": {
      "documentIds": ["doc-id-1", "doc-id-2", "doc-id-3"],
      "updates": {
        "is_active": true,
        "folder_id": "folder-uuid"
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "message": "Successfully updated 3 documents",
    "updatedCount": 3,
    "documentIds": ["doc-id-1", "doc-id-2", "doc-id-3"],
    "updates": {
      "is_active": true,
      "folder_id": "folder-uuid"
    }
  }
  ```
</CodeGroup>

***

## Delete document

Permanently deletes a document, removes it from storage and the voice agent system, and syncs the removal with all dependent agents.

<ParamField type="string">
  Must be `"knowledge-base"`
</ParamField>

<ParamField type="string">
  Must be `"delete"`
</ParamField>

<ParamField type="string">
  The document UUID to delete.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      When `true`, skips the step that removes the document from dependent genies after deletion. Use this when you are managing agent knowledge base membership separately or when the document was never synced with any genie.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="message" type="string">Confirmation message.</ResponseField>
    <ResponseField name="documentId" type="string">The ID of the deleted document.</ResponseField>

    <ResponseField name="errors" type="array">
      Present only when partial errors occurred during cleanup (for example, storage deletion failed but the database record was removed). The deletion is still considered complete if the database record was removed.

      <Expandable title="item properties">
        <ResponseField name="step" type="string">Which cleanup step failed (e.g. `"storage_deletion"`, `"agent_sync_initiation"`).</ResponseField>
        <ResponseField name="error" type="string">Error detail.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<Warning>
  This action is irreversible. The document, its storage file, and its external record will be permanently removed. All dependent genies will have the document removed from their knowledge base unless `skipAgentSync` is set to `true`.
</Warning>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke({
    resource: "knowledge-base",
    action: "delete",
    id: "770e8400-e29b-41d4-a716-446655440002",
    data: {
      skipAgentSync: false,
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "knowledge-base",
      "action": "delete",
      "id": "770e8400-e29b-41d4-a716-446655440002"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "success": true,
      "message": "Document deleted successfully",
      "documentId": "770e8400-e29b-41d4-a716-446655440002"
    }
  }
  ```
</CodeGroup>

***

## Attach documents to agent

Adds one or more documents to a genie's knowledge base. Duplicate documents are automatically skipped.

<ParamField type="string">
  Must be `"knowledge-base"`
</ParamField>

<ParamField type="string">
  Must be `"attach"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The genie ID to attach documents to.
    </ParamField>

    <ParamField type="array">
      Array of documents to attach.

      <Expandable title="item properties">
        <ParamField type="string">Document ID.</ParamField>
        <ParamField type="string">Document name.</ParamField>
        <ParamField type="string">Document type (for example `"file"`, `"url"`).</ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="message" type="string">
  Summary of attached documents.
</ResponseField>

<ResponseField name="attachedCount" type="number">
  Number of documents successfully attached.
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("knowledge-base", "attach", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    documents: [
      { id: "doc-id-1", name: "Product FAQ", type: "file" },
      { id: "doc-id-2", name: "Pricing Guide", type: "url" },
    ],
  });
  ```

  ```json Request body theme={null}
  {
    "resource": "knowledge-base",
    "action": "attach",
    "data": {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "documents": [
        { "id": "doc-id-1", "name": "Product FAQ", "type": "file" },
        { "id": "doc-id-2", "name": "Pricing Guide", "type": "url" }
      ]
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "message": "Attached 2 documents",
    "attachedCount": 2
  }
  ```
</CodeGroup>

***

## Detach documents from agent

Removes specific documents from a genie's knowledge base.

<ParamField type="string">
  Must be `"knowledge-base"`
</ParamField>

<ParamField type="string">
  Must be `"detach"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The genie ID to detach documents from.
    </ParamField>

    <ParamField type="string[]">
      Array of document IDs to remove.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="message" type="string">
  Summary of detached documents.
</ResponseField>

<ResponseField name="detachedCount" type="number">
  Number of documents successfully detached.
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("knowledge-base", "detach", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    documentIds: ["doc-id-1", "doc-id-2"],
  });
  ```

  ```json Request body theme={null}
  {
    "resource": "knowledge-base",
    "action": "detach",
    "data": {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "documentIds": ["doc-id-1", "doc-id-2"]
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "message": "Detached 2 documents",
    "detachedCount": 2
  }
  ```
</CodeGroup>

***

## Replace agent knowledge base

Atomically replaces a genie's entire knowledge base with a new document set. Each document is validated before the update is applied. The genie's voice platform configuration is updated with the new document list, `agent_document` relations are synced (old documents removed, new documents upserted), and connected clients are notified via a realtime broadcast.

<ParamField type="string">
  Must be `"knowledge-base"`
</ParamField>

<ParamField type="string">
  Must be `"replace"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The genie ID whose knowledge base will be replaced.
    </ParamField>

    <ParamField type="array">
      The new complete set of documents. Pass an empty array to clear the knowledge base.

      <Expandable title="item properties">
        <ParamField type="string">Document external ID (voice platform ID).</ParamField>
        <ParamField type="string">Document name.</ParamField>
        <ParamField type="string">Document type (for example `"file"`, `"url"`).</ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="message" type="string">
  Summary of the replacement, including document count.
</ResponseField>

<ResponseField name="replacedCount" type="number">
  Number of documents in the new knowledge base.
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke({
    resource: "knowledge-base",
    action: "replace",
    data: {
      agentId: "550e8400-e29b-41d4-a716-446655440000",
      documents: [
        { id: "el-doc-id-1", name: "Product FAQ", type: "file" },
        { id: "el-doc-id-3", name: "Return Policy", type: "file" },
      ],
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "replace",
      "data": {
        "agentId": "550e8400-e29b-41d4-a716-446655440000",
        "documents": [
          { "id": "el-doc-id-1", "name": "Product FAQ", "type": "file" },
          { "id": "el-doc-id-3", "name": "Return Policy", "type": "file" }
        ]
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "message": "Replaced knowledge base with 2 documents",
    "replacedCount": 2
  }
  ```
</CodeGroup>

<Note>
  Document IDs passed in the `documents` array are voice platform external IDs, not HelpGenie document UUIDs. All documents are validated against the platform before the replacement is applied — if no valid documents are found in a non-empty array, the request is rejected with a `VALIDATION_ERROR`.
</Note>

***

## Sync documents with agents

Synchronizes document changes across all dependent agents. Removes old external documents and adds updated ones to each agent's knowledge base. Typically used internally after document content is updated or deleted.

<ParamField type="string">
  Must be `"knowledge-base"`
</ParamField>

<ParamField type="string">
  Must be `"sync-with-agents"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      External document ID to remove from agents.
    </ParamField>

    <ParamField type="string">
      External document ID to add to agents.
    </ParamField>

    <ParamField type="string[]">
      Specific document IDs to sync. If omitted, syncs all dependent documents.
    </ParamField>

    <ParamField type="boolean">
      When `true`, skip deletion of the old document from agents (non-destructive update).
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="synced_agents" type="array">
      Agents that were successfully updated.

      <Expandable title="item properties">
        <ResponseField name="agent_id" type="string">Genie ID.</ResponseField>
        <ResponseField name="updated" type="boolean">Whether the agent was updated.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="failed_agents" type="array">
      Agents that failed to update.
    </ResponseField>

    <ResponseField name="total_agents" type="number">
      Total number of dependent agents processed.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "knowledge-base",
    "sync-with-agents",
    undefined,
    {
      oldDocId: "el-doc-abc123def456",
      newDocId: "el-doc-xyz789uvw012",
      preventDeletion: false,
    }
  );
  ```

  ```json Request body theme={null}
  {
    "resource": "knowledge-base",
    "action": "sync-with-agents",
    "data": {
      "oldDocId": "el-doc-abc123def456",
      "newDocId": "el-doc-xyz789uvw012",
      "preventDeletion": false
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "synced_agents": [
        {
          "agent_id": "880e8400-e29b-41d4-a716-446655440003",
          "updated": true
        }
      ],
      "failed_agents": [],
      "total_agents": 1
    }
  }
  ```
</CodeGroup>

***

## Clone document

Creates a copy of an existing document.

<ParamField type="string">
  `clone`
</ParamField>

<ParamField type="string">
  UUID of the document to clone.
</ParamField>

### Response

Returns the newly created document object.

***

## Consolidate documents

Merges multiple documents into a single new document. Optionally prunes the originals after consolidation. This delegates to the `doc-upload` edge function.

<ParamField type="string">
  `consolidate`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string[]">
      Array of document UUIDs to consolidate.
    </ParamField>

    <ParamField type="string">
      Name for the consolidated document.
    </ParamField>

    <ParamField type="boolean">
      When `true`, deletes the source documents after consolidation.
    </ParamField>
  </Expandable>
</ParamField>

***

## Documents outside workspace

Returns documents that are attached to one of the workspace's genies but are owned by a different user. This surfaces documents that were added to a genie by an admin on behalf of the workspace — they would otherwise be invisible because documents are normally scoped to the owner's account.

Pagination is supported. Results are sorted newest-first. Only the current user's workspace is searched — no additional parameters are required.

<ParamField type="string">
  Must be `"knowledge-base"`
</ParamField>

<ParamField type="string">
  Must be `"outside-workspace"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Results per page. Maximum 500.
    </ParamField>

    <ParamField type="number">
      Number of results to skip.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="documents" type="array">
      Full document objects. Same shape as the `all` action response items, including `folder`, `owner`, and `dependent_agents`.
    </ResponseField>

    <ResponseField name="count" type="number">Total matching documents.</ResponseField>
    <ResponseField name="limit" type="number">Applied limit.</ResponseField>
    <ResponseField name="offset" type="number">Applied offset.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("knowledge-base", "outside-workspace", undefined, {
    limit: 50,
    offset: 0,
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "knowledge-base",
      "action": "outside-workspace",
      "data": {
        "limit": 50,
        "offset": 0
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "documents": [
        {
          "id": "770e8400-e29b-41d4-a716-446655440099",
          "name": "Admin Uploaded Guide",
          "is_active": true,
          "is_public": false,
          "user_id": "admin-user-id",
          "folder": null,
          "owner": {
            "id": "admin-user-id",
            "full_name": "Admin User",
            "email": "admin@example.com"
          },
          "dependent_agents": [
            {
              "id": "550e8400-e29b-41d4-a716-446655440000",
              "name": "Support Genie",
              "is_active": true
            }
          ],
          "created_at": "2024-01-10T08:00:00.000Z",
          "updated_at": "2024-01-10T08:00:00.000Z"
        }
      ],
      "count": 1,
      "limit": 50,
      "offset": 0
    }
  }
  ```
</CodeGroup>

***

## Error codes

| Code               | Status | Description                               |
| ------------------ | ------ | ----------------------------------------- |
| `UNAUTHORIZED`     | 401    | Missing or invalid authentication token   |
| `INVALID_TOKEN`    | 401    | Token validation failed                   |
| `FORBIDDEN`        | 403    | User lacks required permissions           |
| `NOT_FOUND`        | 404    | Document not found                        |
| `VALIDATION_ERROR` | 400    | Invalid request parameters                |
| `INVALID_ACTION`   | 400    | Unknown action for the documents resource |
| `INTERNAL_ERROR`   | 500    | Server-side error                         |


# Lead notes
Source: https://docs.helpgenie.ai/api-reference/lead-notes

Manage notes attached to leads with pinning support and full CRUD operations.

All requests use a single endpoint: `POST https://api.helpgenie.ai/v1` with `resource: "lead-notes"`.

## Access control

<Note>
  All operations require authentication. Access is granted if the user owns the lead (via the lead's agent) or is an internal admin. Non-owners receive a `403 Forbidden` response.
</Note>

***

## List notes

Retrieves all notes for a specific lead. Pinned notes appear first in the results.

<Tip>
  Pinned notes always appear at the top of list results regardless of pagination or creation date. Use the `togglePin` action or set `is_pinned: true` on update to pin important notes so they are never buried.
</Tip>

<ParamField type="string">
  Must be `"lead-notes"`
</ParamField>

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

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      The ID of the lead to retrieve notes for.
    </ParamField>

    <ParamField type="number">
      Number of results to return. Range: 1-500. Default: `50`.
    </ParamField>

    <ParamField type="number">
      Pagination offset. Default: `0`.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="notes" type="Note[]">
      Array of note objects. See [note object](#note-object).
    </ResponseField>

    <ResponseField name="count" type="number">
      Total number of notes for this lead.
    </ResponseField>

    <ResponseField name="limit" type="number" />

    <ResponseField name="offset" type="number" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    notes: LeadNote[];
    count: number;
  }>({
    resource: "lead-notes",
    action: "list",
    data: {
      leadId: 123,
      limit: 20,
      offset: 0,
    },
  });

  const notes = response?.notes || [];
  ```
</CodeGroup>

***

## Get a note

Retrieves a specific note by ID.

<ParamField type="string">
  Must be `"lead-notes"`
</ParamField>

<ParamField type="string">
  Must be `"get"`
</ParamField>

<ParamField type="string">
  The note UUID.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="note" type="Note">
      The note object. See [note object](#note-object).
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ note: LeadNote }>({
    resource: "lead-notes",
    action: "get",
    id: "note-uuid-here",
  });
  ```
</CodeGroup>

***

## Create a note

Creates a new note for a lead.

<ParamField type="string">
  Must be `"lead-notes"`
</ParamField>

<ParamField type="string">
  Must be `"create"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      The ID of the lead to attach this note to.
    </ParamField>

    <ParamField type="string">
      The note text.
    </ParamField>
  </Expandable>
</ParamField>

### Response (status 201)

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="note" type="Note">
      The created note object.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ note: LeadNote }>(
    {
      resource: "lead-notes",
      action: "create",
      data: {
        leadId: 123,
        content: "Follow up next week",
      },
    },
    201
  );

  const note = response?.note;
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/lead-notes \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "lead-notes",
      "action": "create",
      "data": {
        "leadId": 123,
        "content": "Spoke with Jane — interested in the enterprise plan. Schedule a demo for next Tuesday."
      }
    }'
  ```
</CodeGroup>

***

## Update a note

Updates an existing note. Only `content` and `is_pinned` fields can be modified.

<ParamField type="string">
  Must be `"lead-notes"`
</ParamField>

<ParamField type="string">
  Must be `"update"`
</ParamField>

<ParamField type="string">
  The note UUID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Updated note text.
    </ParamField>

    <ParamField type="boolean">
      Whether the note should be pinned.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="note" type="Note">
      The updated note object.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ note: LeadNote }>({
    resource: "lead-notes",
    action: "update",
    id: "note-uuid-here",
    data: {
      content: "Updated note content",
      is_pinned: true,
    },
  });
  ```
</CodeGroup>

***

## Delete a note

Permanently deletes a note.

<ParamField type="string">
  Must be `"lead-notes"`
</ParamField>

<ParamField type="string">
  Must be `"delete"`
</ParamField>

<ParamField type="string">
  The note UUID.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="message" type="string" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    success: boolean;
    message: string;
  }>({
    resource: "lead-notes",
    action: "delete",
    id: "note-uuid-here",
  });
  ```
</CodeGroup>

***

## Toggle pin status

Toggles the pinned status of a note. If the note is pinned it becomes unpinned, and vice versa.

<ParamField type="string">
  Must be `"lead-notes"`
</ParamField>

<ParamField type="string">
  Must be `"togglePin"`
</ParamField>

<ParamField type="string">
  The note UUID.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="note" type="Note">
      The note object with the updated `is_pinned` value.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ note: LeadNote }>({
    resource: "lead-notes",
    action: "togglePin",
    id: "note-uuid-here",
  });

  const updatedNote = response?.note;
  ```
</CodeGroup>

***

## Get pinned notes

Retrieves all pinned notes for a specific lead.

<ParamField type="string">
  Must be `"lead-notes"`
</ParamField>

<ParamField type="string">
  Must be `"pinned"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      The ID of the lead.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="notes" type="Note[]">
      Array of pinned note objects.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ notes: LeadNote[] }>({
    resource: "lead-notes",
    action: "pinned",
    data: {
      leadId: 123,
    },
  });

  const pinnedNotes = response?.notes || [];
  ```
</CodeGroup>

***

## Note object

<ResponseField name="id" type="string">
  UUID of the note.
</ResponseField>

<ResponseField name="lead_id" type="number">
  ID of the lead this note belongs to.
</ResponseField>

<ResponseField name="user_id" type="string | null">
  ID of the user who created the note.
</ResponseField>

<ResponseField name="content" type="string">
  The note text.
</ResponseField>

<ResponseField name="is_pinned" type="boolean | null">
  Whether the note is pinned. Pinned notes sort first in list results.
</ResponseField>

<ResponseField name="created_at" type="string | null">
  ISO 8601 timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  ISO 8601 timestamp.
</ResponseField>

***

## Error responses

| Status | Code               | Description                                 |
| ------ | ------------------ | ------------------------------------------- |
| 400    | `VALIDATION_ERROR` | Missing required parameters (e.g. `leadId`) |
| 401    | `UNAUTHORIZED`     | Invalid or missing authentication token     |
| 403    | `FORBIDDEN`        | User does not own the lead                  |
| 404    | `NOT_FOUND`        | Note not found                              |
| 500    | `INTERNAL_ERROR`   | Server error                                |


# Leads
Source: https://docs.helpgenie.ai/api-reference/leads

Manage and query lead records associated with your agents, including filtering, statistics, and admin operations.

All requests use a single endpoint: `POST https://api.helpgenie.ai/v1` with `resource: "leads"`.

## Access control

<Note>
  Regular users can only access leads from agents they own. Internal admins can access all leads using `adminMode: true` and optionally scope to a specific user with `userId`.
</Note>

***

## Get lead statistics

Retrieves aggregated statistics about leads, including total count and breakdown by status. Aggregation happens at the database level for optimal performance.

<ParamField type="string">
  Must be `"leads"`
</ParamField>

<ParamField type="string">
  Must be `"stats"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="object">
      <Expandable title="properties">
        <ParamField type="string">
          Filter by a specific agent ID.
        </ParamField>

        <ParamField type="string[]">
          Filter by multiple agent IDs.
        </ParamField>

        <ParamField type="string">
          Filter by priority (exact match).
        </ParamField>

        <ParamField type="string">
          Search in name, email, and phone fields (partial match).
        </ParamField>

        <ParamField type="string">
          Filter by creation date. One of `"7d"`, `"30d"`, `"90d"`, or `"all"`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="boolean">
      Internal admins only. Bypass user scoping to see all leads.
    </ParamField>

    <ParamField type="string">
      Internal admins only. View statistics for a specific user.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="stats" type="object">
      <Expandable title="properties">
        <ResponseField name="total" type="number">
          Total number of leads matching the filters.
        </ResponseField>

        <ResponseField name="by_status" type="object">
          <Expandable title="properties">
            <ResponseField name="new" type="number" />

            <ResponseField name="contacted" type="number" />

            <ResponseField name="qualified" type="number" />

            <ResponseField name="converted" type="number" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Leads with a `null` status or a status outside the four standard values are not counted in any `by_status` category but are included in `total`.
</Note>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    stats: {
      total: number;
      by_status: { new: number; contacted: number; qualified: number; converted: number };
    };
  }>({
    resource: "leads",
    action: "stats",
    data: {
      filters: {
        agentIds: ["agent-1", "agent-2"],
        dateRange: "30d",
      },
    },
  });
  ```

  ```json Example response theme={null}
  {
    "success": true,
    "data": {
      "stats": {
        "total": 47,
        "by_status": {
          "new": 12,
          "contacted": 18,
          "qualified": 15,
          "converted": 2
        }
      }
    }
  }
  ```
</CodeGroup>

***

## List all leads

Retrieves all leads with full field details and relations.

<ParamField type="string">
  Must be `"leads"`
</ParamField>

<ParamField type="string">
  Must be `"all"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="object">
      <Expandable title="properties">
        <ParamField type="string">
          Filter by a specific agent ID.
        </ParamField>

        <ParamField type="string[]">
          Filter by multiple agent IDs.
        </ParamField>

        <ParamField type="string">
          Filter by status (exact match).
        </ParamField>

        <ParamField type="string">
          Filter by priority (exact match).
        </ParamField>

        <ParamField type="string">
          Search in name, email, and phone fields (partial match).
        </ParamField>

        <ParamField type="string">
          Filter by creation date. One of `"7d"`, `"30d"`, `"90d"`, or `"all"`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="number">
      Number of results to return. Default: `50`, max: `500`.
    </ParamField>

    <ParamField type="number">
      Pagination offset. Default: `0`.
    </ParamField>

    <ParamField type="boolean">
      Internal admins only. Bypass user scoping.
    </ParamField>

    <ParamField type="string">
      Internal admins only. View leads for a specific user.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="leads" type="Lead[]">
      Array of lead objects with all fields. See [lead object](#lead-object) below.
    </ResponseField>

    <ResponseField name="count" type="number">
      Total number of leads matching the filters.
    </ResponseField>

    <ResponseField name="limit" type="number" />

    <ResponseField name="offset" type="number" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    leads: Lead[];
    count: number;
    limit: number;
    offset: number;
  }>({
    resource: "leads",
    action: "all",
    data: {
      filters: {
        agentId: "agent-123",
        status: "qualified",
        dateRange: "90d",
      },
      limit: 25,
      offset: 0,
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/leads \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "all",
      "data": {
        "filters": {
          "agentId": "agent-123",
          "status": "qualified",
          "priority": "high",
          "dateRange": "90d"
        },
        "limit": 25,
        "offset": 0
      }
    }'
  ```
</CodeGroup>

***

## List leads (summary)

Retrieves leads with basic fields only, optimized for table views. Accepts the same parameters as `all`.

<ParamField type="string">
  Must be `"leads"`
</ParamField>

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

<ParamField type="object">
  Same parameters as `all` (filters, pagination, admin options).
</ParamField>

### Response

Same response structure as `all`, but each lead contains only summary fields:

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="leads" type="object[]">
      <Expandable title="Lead summary fields">
        <ResponseField name="id" type="number" />

        <ResponseField name="agent_id" type="string" />

        <ResponseField name="user_id" type="string" />

        <ResponseField name="name" type="string | null" />

        <ResponseField name="email" type="string | null" />

        <ResponseField name="phone" type="string | null" />

        <ResponseField name="status" type="string | null" />

        <ResponseField name="priority" type="string | null" />

        <ResponseField name="budget" type="string | null" />

        <ResponseField name="timeline" type="string | null" />

        <ResponseField name="assigned_to" type="string | null" />

        <ResponseField name="created_at" type="string" />

        <ResponseField name="updated_at" type="string | null" />

        <ResponseField name="agent" type="object">
          <Expandable title="properties">
            <ResponseField name="id" type="string" />

            <ResponseField name="name" type="string" />

            <ResponseField name="user_id" type="string" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number" />

    <ResponseField name="limit" type="number" />

    <ResponseField name="offset" type="number" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    leads: Lead[];
    count: number;
  }>({
    resource: "leads",
    action: "list",
    data: {
      filters: {
        searchTerm: "john",
        priority: "high",
      },
      limit: 25,
    },
  });
  ```
</CodeGroup>

***

## Get a lead

Retrieves a specific lead by ID with all fields and relations.

<ParamField type="string">
  Must be `"leads"`
</ParamField>

<ParamField type="string">
  Must be `"get"`
</ParamField>

<ParamField type="string | number">
  The lead ID.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="lead" type="Lead">
      Full lead object. See [lead object](#lead-object).
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ lead: Lead }>({
    resource: "leads",
    action: "get",
    id: 42,
  });
  ```
</CodeGroup>

***

## Create a lead

Creates a new lead associated with an agent.

<ParamField type="string">
  Must be `"leads"`
</ParamField>

<ParamField type="string">
  Must be `"create"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The agent this lead belongs to. Validated against agent ownership.
    </ParamField>

    <ParamField type="string">
      Lead name.
    </ParamField>

    <ParamField type="string">
      Lead email address.
    </ParamField>

    <ParamField type="string">
      Lead phone number.
    </ParamField>

    <ParamField type="string">
      Lead status (e.g. `"new"`, `"contacted"`, `"qualified"`, `"converted"`).
    </ParamField>

    <ParamField type="string">
      Lead priority level.
    </ParamField>

    <ParamField type="string">
      Budget information.
    </ParamField>

    <ParamField type="string">
      Timeline information.
    </ParamField>

    <ParamField type="object">
      Address data as a JSON object.
    </ParamField>

    <ParamField type="string">
      Free-text notes.
    </ParamField>

    <ParamField type="string">
      User ID of the assigned team member.
    </ParamField>

    <ParamField type="number">
      Link to a conversation record.
    </ParamField>

    <ParamField type="number">
      Link to a primary lead (for grouping related leads).
    </ParamField>

    <ParamField type="boolean">
      Whether this lead is a decision maker.
    </ParamField>

    <ParamField type="boolean">
      Whether the lead has given email consent.
    </ParamField>

    <ParamField type="boolean">
      Whether the lead has given SMS consent.
    </ParamField>

    <ParamField type="string">
      Preferred method of contact.
    </ParamField>

    <ParamField type="string">
      Preferred time for contact.
    </ParamField>

    <ParamField type="object">
      Arbitrary metadata as a JSON object.
    </ParamField>

    <ParamField type="string">
      Override user attribution for this lead.
    </ParamField>

    <ParamField type="string">
      Admin only. Create the lead as if this user created it.
    </ParamField>
  </Expandable>
</ParamField>

### Response (status 201)

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="lead" type="Lead">
      The created lead object.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  The `user_id` on the created lead is resolved in this order: (1) provided `user_id` parameter, (2) agent's owning user, (3) current authenticated user.
</Note>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ lead: Lead }>(
    {
      resource: "leads",
      action: "create",
      data: {
        agent_id: "agent-123",
        name: "Jane Doe",
        email: "jane@example.com",
        status: "new",
        priority: "high",
      },
    },
    201
  );
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/leads \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "create",
      "data": {
        "agent_id": "agent-123",
        "name": "Jane Doe",
        "email": "jane@example.com",
        "phone": "+1234567890",
        "status": "new",
        "priority": "high",
        "preferred_contact_method": "email",
        "budget": "50000",
        "timeline": "Q2 2026",
        "notes": "Interested in enterprise plan"
      }
    }'
  ```
</CodeGroup>

***

## Update a lead

Updates an existing lead. This is a partial update -- only include the fields you want to change.

<ParamField type="string">
  Must be `"leads"`
</ParamField>

<ParamField type="string">
  Must be `"update"`
</ParamField>

<ParamField type="string | number">
  The lead ID.
</ParamField>

<ParamField type="object">
  Any combination of lead fields. All fields except `id` and `created_at` can be updated. See the `create` action for the full list of fields.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="lead" type="Lead">
      The updated lead object.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ lead: Lead }>({
    resource: "leads",
    action: "update",
    id: 42,
    data: {
      status: "qualified",
      priority: "high",
      notes: "Spoke with decision maker, very interested",
    },
  });
  ```
</CodeGroup>

***

## Delete a lead

Permanently deletes a lead. This is a hard delete with no recovery.

<ParamField type="string">
  Must be `"leads"`
</ParamField>

<ParamField type="string">
  Must be `"delete"`
</ParamField>

<ParamField type="string | number">
  The lead ID.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="message" type="string" />
  </Expandable>
</ResponseField>

<Warning>
  This permanently deletes the lead. The user must have access to the lead's agent.
</Warning>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    success: boolean;
    message: string;
  }>({
    resource: "leads",
    action: "delete",
    id: 42,
  });
  ```
</CodeGroup>

***

## Log lead activity

Records an activity entry against a lead. Used to track interactions like calls, emails, and status changes.

<ParamField type="string">
  Must be `"leads"`
</ParamField>

<ParamField type="string">
  Must be `"log"`
</ParamField>

<ParamField type="string | number">
  The lead ID.
</ParamField>

<ParamField type="object">
  Activity fields to record. Common fields include `type`, `description`, `metadata`. The data is inserted into the `lead_activities` table.
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data.activity" type="object">
  The created activity record.
</ResponseField>

<CodeGroup>
  ```json Request body theme={null}
  {
    "resource": "leads",
    "action": "log",
    "id": 42,
    "data": {
      "type": "email_sent",
      "description": "Sent follow-up proposal"
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "activity": {
        "id": 123,
        "lead_id": 42,
        "user_id": "user-uuid",
        "type": "email_sent",
        "description": "Sent follow-up proposal",
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

***

## Get lead activity logs

Retrieves the activity history for a specific lead, ordered by most recent first.

<ParamField type="string">
  Must be `"leads"`
</ParamField>

<ParamField type="string">
  Must be `"getLogs"`
</ParamField>

<ParamField type="string | number">
  The lead ID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Results per page.
    </ParamField>

    <ParamField type="number">
      Number of results to skip.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data.activities" type="array">
  Array of activity records for this lead.
</ResponseField>

<CodeGroup>
  ```json Request body theme={null}
  {
    "resource": "leads",
    "action": "getLogs",
    "id": 42,
    "data": {
      "limit": 25
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "activities": [
        {
          "id": 123,
          "lead_id": 42,
          "user_id": "user-uuid",
          "type": "email_sent",
          "description": "Sent follow-up proposal",
          "created_at": "2024-01-15T10:30:00.000Z"
        }
      ]
    }
  }
  ```
</CodeGroup>

***

## Lead object

The full lead object returned by `all`, `get`, `create`, and `update` actions.

<ResponseField name="id" type="number" />

<ResponseField name="agent_id" type="string" />

<ResponseField name="user_id" type="string" />

<ResponseField name="name" type="string | null" />

<ResponseField name="email" type="string | null" />

<ResponseField name="phone" type="string | null" />

<ResponseField name="status" type="string | null" />

<ResponseField name="priority" type="string | null" />

<ResponseField name="budget" type="string | null" />

<ResponseField name="timeline" type="string | null" />

<ResponseField name="address" type="object | null" />

<ResponseField name="notes" type="string | null" />

<ResponseField name="assigned_to" type="string | null" />

<ResponseField name="conversation_id" type="number | null" />

<ResponseField name="primary_lead_id" type="number | null" />

<ResponseField name="is_decision_maker" type="boolean | null" />

<ResponseField name="email_consent" type="boolean | null" />

<ResponseField name="sms_consent" type="boolean | null" />

<ResponseField name="preferred_contact_method" type="string | null" />

<ResponseField name="preferred_contact_time" type="string | null" />

<ResponseField name="metadata" type="object | null" />

<ResponseField name="created_at" type="string" />

<ResponseField name="updated_at" type="string | null" />

<ResponseField name="agent" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string" />

    <ResponseField name="name" type="string" />

    <ResponseField name="user_id" type="string" />
  </Expandable>
</ResponseField>

***

## Enum values reference

### `status`

| Value         | Description                                  |
| ------------- | -------------------------------------------- |
| `"new"`       | Lead has been captured but not yet contacted |
| `"contacted"` | Initial outreach has been made               |
| `"qualified"` | Lead has been vetted and meets criteria      |
| `"converted"` | Lead has been successfully converted         |

### `priority`

| Value      | Description                  |
| ---------- | ---------------------------- |
| `"low"`    | Low urgency                  |
| `"medium"` | Standard urgency             |
| `"high"`   | Requires immediate attention |

### `preferred_contact_method`

| Value     | Description              |
| --------- | ------------------------ |
| `"email"` | Contact via email        |
| `"phone"` | Contact via phone call   |
| `"sms"`   | Contact via text message |

***

## Filtering reference

All list-style actions (`stats`, `all`, `list`) accept a `filters` object with the following fields:

| Filter       | Type       | Description                                           |
| ------------ | ---------- | ----------------------------------------------------- |
| `agentId`    | `string`   | Filter by a single agent                              |
| `agentIds`   | `string[]` | Filter by multiple agents                             |
| `status`     | `string`   | Exact match on lead status (not available on `stats`) |
| `priority`   | `string`   | Exact match on lead priority                          |
| `searchTerm` | `string`   | Partial match across name, email, and phone           |
| `dateRange`  | `string`   | One of `"7d"`, `"30d"`, `"90d"`, `"all"`              |

***

## Admin operations

<Note>
  Admin operations require the `internal_admin` role. Regular users receive a `403 Forbidden` response.
</Note>

### View all leads across all users

```typescript theme={null}
const response = await ApiService.invoke<{ leads: Lead[]; count: number }>({
  resource: "leads",
  action: "all",
  data: {
    adminMode: true,
  },
});
```

### View a specific user's leads

```typescript theme={null}
const response = await ApiService.invoke<{ leads: Lead[]; count: number }>({
  resource: "leads",
  action: "list",
  data: {
    adminMode: true,
    userId: "user-456",
  },
});
```

### Create a lead as another user

```typescript theme={null}
const response = await ApiService.invoke<{ lead: Lead }>(
  {
    resource: "leads",
    action: "create",
    data: {
      agent_id: "agent-123",
      name: "Jane Doe",
      email: "jane@example.com",
      userId: "user-456",
    },
  },
  201
);
```

***

## Error responses

| Status | Code               | Description                             |
| ------ | ------------------ | --------------------------------------- |
| 400    | `VALIDATION_ERROR` | Missing or invalid required parameters  |
| 401    | `UNAUTHORIZED`     | Invalid or missing authentication token |
| 403    | `FORBIDDEN`        | User does not have access to the agent  |
| 404    | `NOT_FOUND`        | Lead not found                          |
| 500    | `INTERNAL_ERROR`   | Server error                            |


# Learn
Source: https://docs.helpgenie.ai/api-reference/learn

Access Learn Hub articles and track per-user reading progress for in-product education.

The Learn Hub provides curated articles to help users get the most out of HelpGenie. Progress is tracked per user — viewing an article automatically updates `last_viewed_at`, and users can explicitly mark articles complete or incomplete.

Only published articles are returned.

***

## Actions

### `all` / `list`

Returns a paginated list of published articles with the current user's progress joined.

**Parameters**

| Field                | Type    | Required | Description                           |
| -------------------- | ------- | -------- | ------------------------------------- |
| `limit`              | number  | No       | Max results, default `100`, max `500` |
| `offset`             | number  | No       | Pagination offset, default `0`        |
| `filters.startHere`  | boolean | No       | Only return "Start Here" articles     |
| `filters.category`   | string  | No       | Filter by category slug               |
| `filters.searchTerm` | string  | No       | Case-insensitive title search         |
| `startHere`          | boolean | No       | Shorthand for `filters.startHere`     |

**Response**

```json theme={null}
{
  "articles": [
    {
      "id": "article-uuid",
      "title": "Getting started with your first Genie",
      "slug": "getting-started-first-genie",
      "category": "setup",
      "is_start_here": true,
      "order_index": 1,
      "completed_at": null,
      "last_viewed_at": "2024-01-05T10:00:00Z"
    }
  ],
  "count": 24,
  "limit": 100,
  "offset": 0
}
```

***

### `get`

Returns a single published article by `slug` (preferred) or `id`. Automatically records `last_viewed_at` for the current user as a side effect.

**Parameters**

| Field  | Type   | Required    | Description                                   |
| ------ | ------ | ----------- | --------------------------------------------- |
| `slug` | string | Conditional | Article slug — preferred lookup key           |
| `id`   | string | Conditional | Article UUID — used if `slug` is not provided |

At least one of `slug` or `id` is required.

**Response**

```json theme={null}
{
  "article": {
    "id": "article-uuid",
    "title": "Getting started with your first Genie",
    "slug": "getting-started-first-genie",
    "category": "setup",
    "is_start_here": true,
    "order_index": 1,
    "body_markdown": "## Introduction\n\nWelcome to HelpGenie...",
    "completed_at": null,
    "last_viewed_at": "2024-01-07T10:00:00Z"
  }
}
```

***

### `progress`

Returns all progress records for the current user — one entry per article they have viewed or completed.

**Parameters** — none

**Response**

```json theme={null}
{
  "progress": [
    {
      "article_id": "article-uuid",
      "completed_at": "2024-01-06T09:00:00Z",
      "last_viewed_at": "2024-01-06T09:00:00Z"
    }
  ]
}
```

***

### `mark-complete`

Marks an article as completed for the current user. Sets both `completed_at` and `last_viewed_at` to now.

**Parameters**

| Field       | Type   | Required    | Description                                           |
| ----------- | ------ | ----------- | ----------------------------------------------------- |
| `id`        | string | Conditional | Article UUID (request ID)                             |
| `articleId` | string | Conditional | Article UUID (data field) — used if `id` not provided |

**Response**

```json theme={null}
{
  "success": true,
  "article_id": "article-uuid",
  "completed_at": "2024-01-07T10:00:00Z"
}
```

***

### `mark-incomplete`

Clears the `completed_at` timestamp for an article, marking it as not completed.

**Parameters**

| Field       | Type   | Required    | Description               |
| ----------- | ------ | ----------- | ------------------------- |
| `id`        | string | Conditional | Article UUID (request ID) |
| `articleId` | string | Conditional | Article UUID (data field) |

**Response**

```json theme={null}
{
  "success": true,
  "article_id": "article-uuid"
}
```

***

## Error codes

| Code               | Meaning                            |
| ------------------ | ---------------------------------- |
| `VALIDATION_ERROR` | Missing article ID or slug         |
| `NOT_FOUND`        | Article not found or not published |
| `INTERNAL_ERROR`   | Unexpected server error            |


# Mail tenant credentials
Source: https://docs.helpgenie.ai/api-reference/mail-tenant-credentials

Admin-only callback endpoint for the mail system to register or rotate tenant credentials for a Voice team

`mail-tenant-credentials` is an admin-only resource that lets the mail system push the credentials it issued (or reissued) for a Voice team back into HelpGenie Voice. It is the inbound counterpart to the outbound tenant-provisioning call made when a genie mailbox is first created.

If the `owner_email` address has no Voice account yet, one is created automatically. If that account has no team, a team is created as well — so the mail system always receives a stable `team_id` to store on its side.

<Warning>
  All actions on this resource require an internal admin API key. Requests from non-admin callers are rejected with `403 Forbidden`.
</Warning>

***

## Upsert tenant credentials

Registers or updates the mail tenant credentials for the team that owns `owner_email`. Creates a Voice account and team for `owner_email` if neither exists yet.

<ParamField type="string">
  Must be `"mail-tenant-credentials"`
</ParamField>

<ParamField type="string">
  Must be `"upsert"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Email address of the Voice team owner. Must be a valid email address. Used to look up (or create) the Voice account that owns the tenant.
    </ParamField>

    <ParamField type="string">
      The tenant identifier issued by the mail system for this team.
    </ParamField>

    <ParamField type="string">
      The API key issued by the mail system for this tenant.
    </ParamField>

    <ParamField type="string | null">
      Display name for the tenant. Pass `null` to clear an existing value.
    </ParamField>

    <ParamField type="string | null">
      The mail system's own user identifier for this owner. Pass `null` if not available.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  Whether the credentials were stored successfully.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="team_id" type="number">
      The Voice team ID the credentials were stored under. The mail system should persist this to associate future updates with the same team.
    </ResponseField>

    <ResponseField name="owner_user_id" type="string">
      The Voice user ID for `owner_email`. Matches the ID of the newly created account if one was provisioned during this call.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke<{
    team_id: number;
    owner_user_id: string;
  }>({
    resource: "mail-tenant-credentials",
    action: "upsert",
    data: {
      owner_email: "owner@example.com",
      tenant_id: "tenant-abc123",
      api_key: "mk_live_xxxxxxxxxxxxxxxx",
      tenant_name: "Example Team",
      owner_user_id: "mail-usr-456",
    },
  });

  const { team_id, owner_user_id } = response;
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_ADMIN_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "mail-tenant-credentials",
      "action": "upsert",
      "data": {
        "owner_email": "owner@example.com",
        "tenant_id": "tenant-abc123",
        "api_key": "mk_live_xxxxxxxxxxxxxxxx",
        "tenant_name": "Example Team",
        "owner_user_id": "mail-usr-456"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "team_id": 42,
      "owner_user_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
  ```
</CodeGroup>

***

## Side effects

* If `owner_email` does not match any existing Voice account, a new account is created with a temporary password. The owner will need to complete account setup before logging in directly.
* If the resolved account has no team, a team is created automatically using the local part of `owner_email` as the team name.
* Calling `upsert` again for the same `owner_email` with new credentials will overwrite the previously stored values — no duplicate entries are created.

***

## Error codes

| Code               | Status | Description                                                                          |
| ------------------ | ------ | ------------------------------------------------------------------------------------ |
| `FORBIDDEN`        | 403    | Caller is not an internal admin                                                      |
| `VALIDATION_ERROR` | 400    | `owner_email` is missing or invalid, `tenant_id` is missing, or `api_key` is missing |
| `INVALID_ACTION`   | 400    | Unknown action                                                                       |
| `INTERNAL_ERROR`   | 500    | Account or team creation failed, or credential storage failed                        |


# Marketplace
Source: https://docs.helpgenie.ai/api-reference/marketplace

Browse, search, and manage marketplace genie listings with categories and statistics.

All requests use a single endpoint: `POST https://api.helpgenie.ai/v1` with `resource: "marketplace"`.

## Access control

<Note>
  The `list`, `all`, `get`, `categories`, `stats`, and `trending` actions are publicly accessible. The `create`, `update`, and `delete` actions require internal admin authentication. The `clone`, `reviews`, `favorites`, `collections`, and `submissions` actions require user authentication.
</Note>

<Warning>
  The `create`, `update`, and `delete` actions are admin-only operations. Only users with the `internal_admin` role can perform these actions. Non-admin users will receive a `403 Forbidden` response.
</Warning>

### `sortBy` values

| Value       | Description                                              |
| ----------- | -------------------------------------------------------- |
| `"popular"` | Sort by view count (most viewed first)                   |
| `"newest"`  | Sort by creation date (most recent first) -- **default** |
| `"rating"`  | Sort by rating (highest rated first)                     |
| `"clones"`  | Sort by clone count (most cloned first)                  |

***

## List genies (slim)

Retrieves a simplified list of marketplace genies optimized for dropdowns and compact listings. Returns only essential fields without nested relations.

<ParamField type="string">
  Must be `"marketplace"`
</ParamField>

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

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Items per page. Range: 1-500. Default: `20`.
    </ParamField>

    <ParamField type="number">
      Pagination offset. Default: `0`.
    </ParamField>

    <ParamField type="object">
      <Expandable title="properties">
        <ParamField type="string">
          Filter by category slug.
        </ParamField>

        <ParamField type="string">
          Filter by brand slug.
        </ParamField>

        <ParamField type="string">
          Search in name, tagline, and description.
        </ParamField>

        <ParamField type="string">
          Set to `"true"` to show only featured genies.
        </ParamField>

        <ParamField type="string">
          Minimum rating filter.
        </ParamField>

        <ParamField type="string">
          Filter by difficulty metadata.
        </ParamField>

        <ParamField type="string">
          Filter by industry metadata.
        </ParamField>

        <ParamField type="string">
          Sort order. One of `"popular"`, `"newest"`, `"rating"`, `"clones"`. Default: `"newest"`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="genies" type="object[]">
      <Expandable title="Slim genie fields">
        <ResponseField name="id" type="string" />

        <ResponseField name="slug" type="string" />

        <ResponseField name="display_name" type="string" />

        <ResponseField name="tagline" type="string" />

        <ResponseField name="thumbnail_url" type="string" />

        <ResponseField name="rating" type="number" />

        <ResponseField name="category_id" type="string" />

        <ResponseField name="is_featured" type="boolean" />

        <ResponseField name="clone_count" type="number" />
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number" />

    <ResponseField name="limit" type="number" />

    <ResponseField name="offset" type="number" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    genies: MarketplaceGenie[];
    count: number;
  }>({
    resource: "marketplace",
    action: "list",
    data: {
      limit: 20,
      query: {
        category: "customer-service",
        sortBy: "popular",
      },
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/marketplace \
    -H "Content-Type: application/json" \
    -d '{
      "action": "list",
      "data": {
        "limit": 20,
        "offset": 0,
        "query": {
          "category": "customer-service",
          "search": "sales",
          "sortBy": "popular",
          "featured": "true",
          "minRating": "4"
        }
      }
    }'
  ```
</CodeGroup>

***

## List genies (complete)

Retrieves the full marketplace genie listing with all fields and nested relations (category, brand, and creator in admin mode).

<ParamField type="string">
  Must be `"marketplace"`
</ParamField>

<ParamField type="string">
  Must be `"all"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Items per page. Range: 1-500. Default: `20`.
    </ParamField>

    <ParamField type="number">
      Pagination offset. Default: `0`.
    </ParamField>

    <ParamField type="boolean">
      Admin only. Include non-public genies in results.
    </ParamField>

    <ParamField type="object">
      Same query parameters as the `list` action. Default sort: featured first, then by clones.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="genies" type="object[]">
      Array of full genie objects. See [genie object](#genie-object).
    </ResponseField>

    <ResponseField name="count" type="number" />

    <ResponseField name="limit" type="number" />

    <ResponseField name="offset" type="number" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    genies: MarketplaceGenie[];
    count: number;
  }>({
    resource: "marketplace",
    action: "all",
    data: {
      limit: 50,
      query: {
        search: "sales",
        minRating: "4",
      },
    },
  });
  ```
</CodeGroup>

***

## Get a genie

Retrieves a specific marketplace genie by slug or ID. Automatically increments the view count and includes related genies from the same category.

<ParamField type="string">
  Must be `"marketplace"`
</ParamField>

<ParamField type="string">
  Must be `"get"`
</ParamField>

<ParamField type="string">
  The genie slug (preferred) or UUID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      Admin only. Allow fetching non-public genies.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  All fields from the [genie object](#genie-object), plus:

  <Expandable title="additional fields">
    <ResponseField name="related_genies" type="object[]">
      Genies from the same category.

      <Expandable title="properties">
        <ResponseField name="id" type="string" />

        <ResponseField name="slug" type="string" />

        <ResponseField name="display_name" type="string" />

        <ResponseField name="tagline" type="string" />

        <ResponseField name="thumbnail_url" type="string" />

        <ResponseField name="rating" type="number" />

        <ResponseField name="category_id" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<MarketplaceGenie>({
    resource: "marketplace",
    action: "get",
    id: "sales-assistant",
  });
  ```
</CodeGroup>

***

## Create a listing

Creates a new marketplace listing. Automatically marks the agent as a marketplace template and links the listing back to the agent.

<Note>
  Only internal admins can create marketplace listings.
</Note>

<ParamField type="string">
  Must be `"marketplace"`
</ParamField>

<ParamField type="string">
  Must be `"create"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      ID of the agent to list on the marketplace.
    </ParamField>

    <ParamField type="string">
      URL-friendly unique identifier.
    </ParamField>

    <ParamField type="string">
      Public display name.
    </ParamField>

    <ParamField type="string">
      Category ID for the listing.
    </ParamField>

    <ParamField type="string">
      Short one-liner description.
    </ParamField>

    <ParamField type="string">
      Full description.
    </ParamField>

    <ParamField type="string">
      Associated brand ID.
    </ParamField>

    <ParamField type="boolean">
      Feature on homepage. Default: `false`.
    </ParamField>

    <ParamField type="boolean">
      Publish to marketplace. Default: `true`.
    </ParamField>

    <ParamField type="string">
      Preview image URL.
    </ParamField>

    <ParamField type="string">
      Demo video URL.
    </ParamField>

    <ParamField type="object">
      Additional metadata (e.g. `difficulty`, `industry`).
    </ParamField>
  </Expandable>
</ParamField>

### Response (status 201)

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  The created marketplace genie with all fields. See [genie object](#genie-object).
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<MarketplaceGenie>(
    {
      resource: "marketplace",
      action: "create",
      data: {
        agent_id: "agent-123",
        slug: "sales-assistant",
        display_name: "Sales Assistant",
        category_id: "category-456",
        tagline: "Close more deals with voice AI",
        is_featured: true,
        metadata: { difficulty: "beginner", industry: "sales" },
      },
    },
    201
  );
  ```
</CodeGroup>

***

## Update a listing

Updates an existing marketplace listing.

<Note>
  Only internal admins can update marketplace listings.
</Note>

<ParamField type="string">
  Must be `"marketplace"`
</ParamField>

<ParamField type="string">
  Must be `"update"`
</ParamField>

<ParamField type="string">
  The listing ID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="boolean" />

    <ParamField type="boolean" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="object" />
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  The updated marketplace genie with all fields.
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<MarketplaceGenie>({
    resource: "marketplace",
    action: "update",
    id: "genie-uuid",
    data: {
      display_name: "Updated Sales Assistant",
      is_featured: false,
    },
  });
  ```
</CodeGroup>

***

## Delete a listing

Permanently deletes a marketplace listing and unlinks the agent from the marketplace.

<Note>
  Only internal admins can delete marketplace listings.
</Note>

<ParamField type="string">
  Must be `"marketplace"`
</ParamField>

<ParamField type="string">
  Must be `"delete"`
</ParamField>

<ParamField type="string">
  The listing ID.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="id" type="string">
      The deleted listing ID.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    success: boolean;
    id: string;
  }>({
    resource: "marketplace",
    action: "delete",
    id: "genie-uuid",
  });
  ```
</CodeGroup>

***

## List categories

Retrieves all marketplace categories ordered by display order. No authentication required.

<ParamField type="string">
  Must be `"marketplace"`
</ParamField>

<ParamField type="string">
  Must be `"categories"`
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="categories" type="object[]">
      <Expandable title="properties">
        <ResponseField name="id" type="string" />

        <ResponseField name="name" type="string" />

        <ResponseField name="slug" type="string" />

        <ResponseField name="description" type="string" />

        <ResponseField name="icon" type="string" />

        <ResponseField name="order" type="number" />

        <ResponseField name="parent_id" type="string | null" />

        <ResponseField name="created_at" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    categories: MarketplaceCategory[];
    count: number;
  }>({
    resource: "marketplace",
    action: "categories",
  });
  ```
</CodeGroup>

***

## Get statistics

Retrieves aggregate statistics about the marketplace. No authentication required.

<ParamField type="string">
  Must be `"marketplace"`
</ParamField>

<ParamField type="string">
  Must be `"stats"`
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="total_genies" type="number">
      Total number of marketplace genies.
    </ResponseField>

    <ResponseField name="total_views" type="number">
      Combined view count across all genies.
    </ResponseField>

    <ResponseField name="total_clones" type="number">
      Combined clone count across all genies.
    </ResponseField>

    <ResponseField name="featured_count" type="number">
      Number of featured genies.
    </ResponseField>

    <ResponseField name="categories_count" type="number">
      Number of categories.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    total_genies: number;
    total_views: number;
    total_clones: number;
    featured_count: number;
    categories_count: number;
  }>({
    resource: "marketplace",
    action: "stats",
  });
  ```

  ```json Example response theme={null}
  {
    "success": true,
    "data": {
      "total_genies": 42,
      "total_views": 5420,
      "total_clones": 128,
      "featured_count": 8,
      "categories_count": 12
    }
  }
  ```
</CodeGroup>

***

## Clone a marketplace genie

Clones a marketplace genie into the authenticated user's account. Delegates to `handle-agent` for the actual agent clone, tracks the clone in `user_marketplace_clones`, and increments the listing's `clone_count`.

<ParamField type="string">
  Must be `"marketplace"`
</ParamField>

<ParamField type="string">
  Must be `"clone"`
</ParamField>

<ParamField type="string">
  The marketplace genie listing ID. Can also be passed as `marketplace_genie_id` in the data object.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Custom name for the cloned genie.
    </ParamField>

    <ParamField type="object">
      Custom overrides applied to the clone.
    </ParamField>

    <ParamField type="number">
      Current clone count (incremented by 1). Default: `0`.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="marketplace_genie_id" type="string">
      The listing that was cloned.
    </ResponseField>

    <ResponseField name="cloneResult" type="object">
      The result from the agent clone operation, including the new agent.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke({
    resource: "marketplace",
    action: "clone",
    id: "marketplace-genie-uuid",
    data: {
      cloneName: "My Custom Sales Bot",
      customizations: { industry: "retail" },
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/marketplace \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "clone",
      "id": "marketplace-genie-uuid",
      "data": {
        "cloneName": "My Custom Sales Bot"
      }
    }'
  ```
</CodeGroup>

***

## Reviews

Manages reviews for marketplace genies. Uses a `mode` parameter inside `data` to select the operation. When `mode` is omitted, lists reviews.

<ParamField type="string">
  Must be `"marketplace"`
</ParamField>

<ParamField type="string">
  Must be `"reviews"`
</ParamField>

<ParamField type="string">
  The marketplace genie ID. Can also be passed as `marketplace_genie_id` in data.
</ParamField>

### Create a review

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Must be `"create"`.
    </ParamField>

    <ParamField type="string">
      The genie being reviewed.
    </ParamField>

    <ParamField type="number">
      Rating value.
    </ParamField>

    <ParamField type="string">
      Review body text.
    </ParamField>

    <ParamField type="boolean">
      Whether the reviewer has cloned this genie. Default: `false`.
    </ParamField>
  </Expandable>
</ParamField>

Returns `{ review: {...} }` with status `201`.

### Update a review

Set `mode: "update"`. Requires `review_id`, plus optional `rating` and `review_text`. Only the review owner can update.

### Delete a review

Set `mode: "delete"`. Requires `review_id`. Only the review owner can delete.

### List reviews (default)

When `mode` is omitted, lists reviews for the given genie with pagination.

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Filter reviews for this genie.
    </ParamField>

    <ParamField type="number">
      Filter by exact rating value.
    </ParamField>

    <ParamField type="boolean">
      Show only verified-clone reviews.
    </ParamField>

    <ParamField type="number">
      Results per page. Max: `200`. Default: `50`.
    </ParamField>

    <ParamField type="number">
      Pagination offset. Default: `0`.
    </ParamField>
  </Expandable>
</ParamField>

Returns `{ items: [...], count, limit, offset }`.

***

## Favorites

Manages a user's marketplace favorites. Uses a `mode` parameter inside `data`.

<ParamField type="string">
  Must be `"marketplace"`
</ParamField>

<ParamField type="string">
  Must be `"favorites"`
</ParamField>

### Add a favorite

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Must be `"add"`.
    </ParamField>

    <ParamField type="string">
      The genie to favorite.
    </ParamField>
  </Expandable>
</ParamField>

Returns `{ favorite: {...} }` with status `201`.

### Remove a favorite

Set `mode: "remove"` with `marketplace_genie_id`.

### List favorites (default)

When `mode` is omitted, lists all favorites for the authenticated user with pagination.

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Results per page. Max: `200`. Default: `50`.
    </ParamField>

    <ParamField type="number">
      Pagination offset. Default: `0`.
    </ParamField>
  </Expandable>
</ParamField>

Returns `{ items: [...], count, limit, offset }`. Each item includes the full `marketplace_genie` object.

***

## Trending

Returns trending marketplace genies from the `trending_marketplace_genies` view, ordered by trending score. No authentication required.

<ParamField type="string">
  Must be `"marketplace"`
</ParamField>

<ParamField type="string">
  Must be `"trending"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Maximum results. Max: `100`. Default: `10`.
    </ParamField>

    <ParamField type="string">
      Filter by category.
    </ParamField>

    <ParamField type="boolean">
      Only show rising genies (fewer than 50 clones, 5+ daily interactions).
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="items" type="object[]">
      Array of trending genie objects with `trending_score`.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke({
    resource: "marketplace",
    action: "trending",
    data: { limit: 10, risingOnly: true },
  });
  ```
</CodeGroup>

***

## Collections

Manages user-curated collections of marketplace genies. Uses a `mode` parameter inside `data`.

<ParamField type="string">
  Must be `"marketplace"`
</ParamField>

<ParamField type="string">
  Must be `"collections"`
</ParamField>

### Create a collection

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Must be `"create"`.
    </ParamField>

    <ParamField type="string">
      Collection name.
    </ParamField>

    <ParamField type="string">
      Collection description.
    </ParamField>

    <ParamField type="boolean">
      Whether the collection is publicly visible. Default: `false`.
    </ParamField>
  </Expandable>
</ParamField>

Returns `{ collection: {...} }` with status `201`.

### Update a collection

Set `mode: "update"` with `collection_id` and any of `name`, `description`, `is_public`.

### Delete a collection

Set `mode: "delete"` with `collection_id`.

### Add genie to collection

Set `mode: "add-genie"` with `collection_id` and `marketplace_genie_id`.

### Remove genie from collection

Set `mode: "remove-genie"` with `collection_id` and `marketplace_genie_id`.

### Get a single collection

Pass `collection_id` (or `id`) without a `mode`. Returns the collection and its genies.

### List collections (default)

When no `mode` and no `collection_id` are provided, lists all collections for the authenticated user.

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Results per page. Max: `200`. Default: `50`.
    </ParamField>

    <ParamField type="number">
      Pagination offset. Default: `0`.
    </ParamField>
  </Expandable>
</ParamField>

Returns `{ items: [...], count, limit, offset }`.

***

## Submissions

Manages marketplace submission requests. Users submit their genies for marketplace listing; admins moderate them. Uses a `mode` parameter inside `data`.

<ParamField type="string">
  Must be `"marketplace"`
</ParamField>

<ParamField type="string">
  Must be `"submissions"`
</ParamField>

### Create a submission

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Must be `"create"`.
    </ParamField>

    <ParamField type="string">
      The agent to submit for marketplace listing.
    </ParamField>

    <ParamField type="object">
      Additional submission details (tagline, description, category preference, etc.).
    </ParamField>
  </Expandable>
</ParamField>

Returns `{ submission: {...} }` with status `201`. Initial status is `"pending"`.

### Moderate a submission (admin only)

Set `mode` to `"approve"`, `"reject"`, or `"under-review"`. Requires `submission_id`. Optional `admin_notes`.

### Delete a submission

Set `mode: "delete"` with `submission_id`. Admins can delete any submission; regular users can only delete their own.

### List submissions (default)

When `mode` is omitted, lists submissions with pagination. Admins see all submissions; regular users see only their own.

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Filter by status: `"pending"`, `"approved"`, `"rejected"`, `"under_review"`.
    </ParamField>

    <ParamField type="number">
      Results per page. Max: `200`. Default: `50`.
    </ParamField>

    <ParamField type="number">
      Pagination offset. Default: `0`.
    </ParamField>
  </Expandable>
</ParamField>

Returns `{ items: [...], count, limit, offset }`.

***

## Genie object

The full genie object returned by `all`, `get`, `create`, and `update` actions.

<ResponseField name="id" type="string" />

<ResponseField name="agent_id" type="string" />

<ResponseField name="slug" type="string" />

<ResponseField name="display_name" type="string" />

<ResponseField name="tagline" type="string" />

<ResponseField name="description" type="string" />

<ResponseField name="category_id" type="string" />

<ResponseField name="category" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string" />

    <ResponseField name="name" type="string" />

    <ResponseField name="slug" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="brand_id" type="string" />

<ResponseField name="brand" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string" />

    <ResponseField name="name" type="string" />

    <ResponseField name="slug" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="is_featured" type="boolean" />

<ResponseField name="is_public" type="boolean" />

<ResponseField name="thumbnail_url" type="string" />

<ResponseField name="demo_video_url" type="string" />

<ResponseField name="rating" type="number" />

<ResponseField name="view_count" type="number" />

<ResponseField name="clone_count" type="number" />

<ResponseField name="metadata" type="object" />

<ResponseField name="created_at" type="string" />

<ResponseField name="updated_at" type="string" />

<ResponseField name="creator" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string" />

    <ResponseField name="full_name" type="string" />

    <ResponseField name="email" type="string" />
  </Expandable>
</ResponseField>

***

## Error responses

| Status | Code               | Description                             |
| ------ | ------------------ | --------------------------------------- |
| 400    | `VALIDATION_ERROR` | Missing required parameters             |
| 401    | `UNAUTHORIZED`     | Missing or invalid authentication token |
| 403    | `FORBIDDEN`        | Non-admin attempting a write operation  |
| 404    | `NOT_FOUND`        | Marketplace genie not found             |
| 500    | `INTERNAL_ERROR`   | Server error                            |


# Phone numbers
Source: https://docs.helpgenie.ai/api-reference/phone-numbers

Provision, release, and manage phone numbers for voice agents

Manage phone numbers provisioned for voice agents. Phone numbers can be assigned to genies for inbound and outbound calling.

<Note>
  Standard users can only view phone numbers assigned to their own agents. Admin users can view all phone numbers across the platform.
</Note>

***

## List phone numbers

Returns a paginated list of phone numbers with user profile enrichment.

<ParamField type="string">
  Must be `"phone-numbers"`.
</ParamField>

<ParamField type="string">
  Must be `"all"` or `"list"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Results per page. Maximum 1000.
    </ParamField>

    <ParamField type="number">
      Number of results to skip.
    </ParamField>

    <ParamField type="boolean">
      Admin only. View all phone numbers across the platform.
    </ParamField>

    <ParamField type="string">
      Admin only. Scope results to a specific user's phone numbers.
    </ParamField>

    <ParamField type="object">
      <Expandable title="properties">
        <ParamField type="string">
          Filter by phone number digits (non-digit characters are stripped before matching).
        </ParamField>

        <ParamField type="string">
          Filter by country code (for example `"US"`, `"AU"`).
        </ParamField>

        <ParamField type="string">
          Filter by status (for example `"active"`, `"inactive"`).
        </ParamField>

        <ParamField type="boolean">
          When `true`, return only transfer numbers. When `false`, return only main numbers.
        </ParamField>

        <ParamField type="string">
          Filter to numbers assigned to a specific genie (UUID).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="items" type="array">
      Array of phone number objects.

      <Expandable title="item properties">
        <ResponseField name="id" type="number">Unique phone number record ID (integer).</ResponseField>
        <ResponseField name="phone_number" type="string">Phone number in E.164 format (for example `"+12025551234"`).</ResponseField>
        <ResponseField name="friendly_name" type="string | null">Human-readable label for the number.</ResponseField>
        <ResponseField name="status" type="string">Current status (for example `"active"`, `"inactive"`).</ResponseField>
        <ResponseField name="date_created" type="string">ISO 8601 timestamp when the number was provisioned.</ResponseField>
        <ResponseField name="country_code" type="string | null">Two-letter country code (for example `"US"`).</ResponseField>
        <ResponseField name="is_transfer" type="boolean | null">Whether this is a transfer number rather than a main inbound number.</ResponseField>
        <ResponseField name="agent_id" type="string">UUID of the genie this number is assigned to.</ResponseField>
        <ResponseField name="agent_name" type="string">Display name of the assigned genie.</ResponseField>
        <ResponseField name="user_id" type="string | null">User ID of the genie's owner.</ResponseField>
        <ResponseField name="user_email" type="string | null">Email of the genie's owner.</ResponseField>
        <ResponseField name="user_name" type="string | null">Full name of the genie's owner.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number">
      Total number of matching records.
    </ResponseField>

    <ResponseField name="limit" type="number">
      The limit that was applied.
    </ResponseField>

    <ResponseField name="offset" type="number">
      The offset that was applied.
    </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": "phone-numbers",
      "action": "all",
      "data": {
        "limit": 50,
        "filters": { "country_code": "US" }
      }
    }'
  ```

  ```json Request body theme={null}
  {
    "resource": "phone-numbers",
    "action": "all",
    "data": {
      "limit": 50,
      "filters": { "country_code": "US" }
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "items": [
        {
          "id": 1234,
          "phone_number": "+12025551234",
          "friendly_name": "Support Line",
          "country_code": "US",
          "status": "active",
          "date_created": "2024-01-15T10:30:00.000Z",
          "is_transfer": false,
          "agent_id": "550e8400-e29b-41d4-a716-446655440000",
          "agent_name": "Customer Support Bot",
          "user_id": "660e8400-e29b-41d4-a716-446655440001",
          "user_email": "owner@example.com",
          "user_name": "Jane Smith"
        }
      ],
      "count": 1,
      "limit": 50,
      "offset": 0
    }
  }
  ```
</CodeGroup>

***

## Get phone number

Retrieves a single phone number by ID with profile enrichment.

<ParamField type="string">
  Must be `"phone-numbers"`.
</ParamField>

<ParamField type="string">
  Must be `"get"`.
</ParamField>

<ParamField type="string">
  The phone number record ID.
</ParamField>

***

## Stats

Returns aggregated statistics across phone numbers.

<ParamField type="string">
  Must be `"phone-numbers"`.
</ParamField>

<ParamField type="string">
  Must be `"stats"`.
</ParamField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="total" type="number">Total phone number count.</ResponseField>
    <ResponseField name="active" type="number">Active phone numbers.</ResponseField>
    <ResponseField name="inactive" type="number">Inactive phone numbers.</ResponseField>
  </Expandable>
</ResponseField>

***

## Export

Exports phone numbers as a CSV string. Supports the same filters as the list action.

<ParamField type="string">
  Must be `"phone-numbers"`.
</ParamField>

<ParamField type="string">
  Must be `"export"`.
</ParamField>

CSV columns: Phone Number, Friendly Name, Genie Name, User Email, User Name, Country, Status, Type, Date Provisioned. Maximum 10,000 records.

***

## Provision

Provisions a new phone number and assigns it to a genie.

<ParamField type="string">
  Must be `"phone-numbers"`.
</ParamField>

<ParamField type="string">
  Must be `"provision"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Genie UUID to assign the number to.
    </ParamField>

    <ParamField type="string">
      Country for number provisioning.
    </ParamField>
  </Expandable>
</ParamField>

***

## Release

Releases a provisioned phone number.

<ParamField type="string">
  Must be `"phone-numbers"`.
</ParamField>

<ParamField type="string">
  Must be `"release"`.
</ParamField>

<ParamField type="string">
  The phone number record ID to release.
</ParamField>

<Warning>
  This will release the phone number from the carrier. The number may become unavailable for re-provisioning.
</Warning>

***

## Update

Updates phone number configuration.

<ParamField type="string">
  Must be `"phone-numbers"`.
</ParamField>

<ParamField type="string">
  Must be `"update"`.
</ParamField>

<ParamField type="string">
  The phone number record ID to update.
</ParamField>


# Playbooks
Source: https://docs.helpgenie.ai/api-reference/playbooks

Playbook listing and apply workflow

Use `playbooks` to list/get templates and apply them to provisioning flows.

Supported actions: `all`, `list`, `get`, `categories`, `apply`.


# Portals
Source: https://docs.helpgenie.ai/api-reference/portals

Portal CRUD, genie assignment, and distribution actions

Manage public/private portals with the `portals` resource.

Supported actions: `all`, `list`, `get`, `create`, `update`, `delete`, `reorder`, `add-genie`, `remove-genie`, `reorder-genies`, `share-url`, `embed-code`.


# Profiles
Source: https://docs.helpgenie.ai/api-reference/profiles

Manage user profiles including account information, subscription details, and team associations.

All requests use a single endpoint: `POST https://api.helpgenie.ai/v1` with `resource: "profiles"`.

## Access control

| Action                       | Regular user      | Admin                 |
| ---------------------------- | ----------------- | --------------------- |
| `all`                        | No                | Yes                   |
| `list`                       | No                | Yes                   |
| `get`                        | Own profile only  | Any profile           |
| `create`                     | No                | Yes                   |
| `update`                     | Own profile only  | Any profile           |
| `delete`                     | Own profile only  | Any profile           |
| `check-timezone`             | Yes (own profile) | Yes                   |
| `generate-sso-token`         | Yes (own session) | Yes (+ impersonation) |
| `generate-sync-consent-link` | Yes (own email)   | Yes (any email)       |
| `usage-summary`              | Yes (own profile) | Yes                   |

<Note>
  Admin endpoints require a role starting with `internal_` (e.g. `internal_admin`). Non-admin users attempting admin-only actions receive a `403 Forbidden` response.
</Note>

### `role` values

| Value              | Description                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| `"standard_user"`  | Business owner -- can create and manage agents, view leads, and access all standard features    |
| `"consumer"`       | End user -- can talk to agents and interact with consumer-facing features                       |
| `"internal_admin"` | Full platform access -- can manage all users, agents, marketplace listings, and system settings |

<Info>
  Profile mutations (`create`, `update`, `delete`) are automatically logged to the `activities` table as `user_action` events. Update actions include the list of changed fields in the activity metadata.
</Info>

***

## List all profiles (admin)

Retrieves all profiles with complete joined data including subscriptions, call purchases, and phone subscriptions.

<ParamField type="string">
  Must be `"profiles"`
</ParamField>

<ParamField type="string">
  Must be `"all"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Results per page. Range: 1-500. Default: `50`.
    </ParamField>

    <ParamField type="number">
      Pagination offset. Default: `0`.
    </ParamField>

    <ParamField type="object">
      <Expandable title="properties">
        <ParamField type="string">
          Search in `full_name` or `email`.
        </ParamField>

        <ParamField type="string">
          Filter by role (exact match).
        </ParamField>

        <ParamField type="number">
          Filter by team ID.
        </ParamField>

        <ParamField type="boolean">
          Filter profiles with active subscriptions.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Column to sort by. One of: `"created_at"` (default), `"email"`, `"full_name"`.
    </ParamField>

    <ParamField type="string">
      Sort direction. `"asc"` or `"desc"`. Default: `"desc"`.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="profiles" type="object[]">
      Array of full profile objects with joined relations. See [profile object](#profile-object).
    </ResponseField>

    <ResponseField name="count" type="number" />

    <ResponseField name="limit" type="number" />

    <ResponseField name="offset" type="number" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    profiles: Profile[];
    count: number;
    limit: number;
    offset: number;
  }>({
    resource: "profiles",
    action: "all",
    data: {
      limit: 100,
      offset: 0,
      filters: {
        role: "internal_admin",
      },
    },
  });
  ```
</CodeGroup>

***

## List basic profiles (admin)

Retrieves a paginated list of profiles with basic fields only, optimized for lists and dropdowns.

<ParamField type="string">
  Must be `"profiles"`
</ParamField>

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

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Results per page. Range: 1-500. Default: `50`.
    </ParamField>

    <ParamField type="number">
      Pagination offset. Default: `0`.
    </ParamField>

    <ParamField type="object">
      <Expandable title="properties">
        <ParamField type="string">
          Search in `full_name` or `email`.
        </ParamField>

        <ParamField type="string">
          Filter by role.
        </ParamField>

        <ParamField type="number">
          Filter by team ID.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="profiles" type="object[]">
      <Expandable title="Basic profile fields">
        <ResponseField name="id" type="string" />

        <ResponseField name="full_name" type="string | null" />

        <ResponseField name="email" type="string | null" />

        <ResponseField name="role" type="string | null" />

        <ResponseField name="avatar_url" type="string | null" />

        <ResponseField name="team_id" type="number | null" />

        <ResponseField name="created_at" type="string" />

        <ResponseField name="updated_at" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number" />

    <ResponseField name="limit" type="number" />

    <ResponseField name="offset" type="number" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    profiles: Profile[];
    count: number;
  }>({
    resource: "profiles",
    action: "list",
    data: {
      limit: 50,
      filters: {
        searchTerm: "john@example.com",
      },
    },
  });
  ```
</CodeGroup>

***

## Get a profile

Retrieves a single profile with complete details including subscriptions and team data. Users can only access their own profile; admins can access any profile.

<ParamField type="string">
  Must be `"profiles"`
</ParamField>

<ParamField type="string">
  Must be `"get"`
</ParamField>

<ParamField type="string">
  The profile ID (user UUID).
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="profile" type="object">
      Full profile object with all joined relations. See [profile object](#profile-object).
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const { user } = await supabase.auth.getUser();
  const response = await ApiService.invoke<{ profile: Profile }>({
    resource: "profiles",
    action: "get",
    id: user.id,
  });

  const subscriptions = response?.profile?.call_purchases;
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/profiles \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "get",
      "id": "d4f8e2a1-5b3c-4e9f-a1b2-c3d4e5f67890"
    }'
  ```
</CodeGroup>

***

## Create a profile (admin)

Creates a new user profile. The `id` must match an existing auth user UUID.

<ParamField type="string">
  Must be `"profiles"`
</ParamField>

<ParamField type="string">
  Must be `"create"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Auth user UUID. Must match an existing user in the auth system.
    </ParamField>

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="number" />

    <ParamField type="string" />

    <ParamField type="boolean" />
  </Expandable>
</ParamField>

### Response (status 201)

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="profile" type="object">
      The created profile with joined data.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ profile: Profile }>(
    {
      resource: "profiles",
      action: "create",
      data: {
        id: "auth-user-uuid-here",
        full_name: "Jane Smith",
        email: "jane@example.com",
        role: "standard_user",
      },
    },
    201
  );
  ```
</CodeGroup>

***

## Update a profile

Updates an existing profile. Users can only update their own profile; admins can update any profile. This is a partial update -- only include the fields you want to change.

<ParamField type="string">
  Must be `"profiles"`
</ParamField>

<ParamField type="string">
  Must be `"update"`
</ParamField>

<ParamField type="string">
  The profile ID (user UUID).
</ParamField>

<ParamField type="object">
  Any combination of profile fields. See the `create` action for the full list of fields (all fields except `id` are accepted).
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="profile" type="object">
      The updated profile with joined data.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ profile: Profile }>({
    resource: "profiles",
    action: "update",
    id: userId,
    data: {
      full_name: "John Doe",
      timezone: "America/New_York",
      company_name: "Acme Corp",
    },
  });
  ```
</CodeGroup>

***

## Delete a profile

Permanently deletes a profile. Users can only delete their own profile; admins can delete any profile.

<ParamField type="string">
  Must be `"profiles"`
</ParamField>

<ParamField type="string">
  Must be `"delete"`
</ParamField>

<ParamField type="string">
  The profile ID (user UUID).
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="message" type="string" />
  </Expandable>
</ResponseField>

<Warning>
  This permanently deletes the profile record.
</Warning>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    success: boolean;
    message: string;
  }>({
    resource: "profiles",
    action: "delete",
    id: "user-uuid",
  });
  ```
</CodeGroup>

***

## Check timezone

Checks the authenticated user's profile for a timezone value. If the timezone is not set, auto-detects it from the server and saves it to the profile. No-op if timezone is already set.

<ParamField type="string">
  Must be `"profiles"`
</ParamField>

<ParamField type="string">
  Must be `"check-timezone"`
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  await ApiService.invoke({
    resource: "profiles",
    action: "check-timezone",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/profiles \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "action": "check-timezone" }'
  ```
</CodeGroup>

***

## Profile object

The full profile object returned by `all`, `get`, `create`, and `update` actions.

### Core fields

<ResponseField name="id" type="string">
  User UUID.
</ResponseField>

<ResponseField name="full_name" type="string | null" />

<ResponseField name="email" type="string | null" />

<ResponseField name="role" type="string | null" />

<ResponseField name="avatar_url" type="string | null" />

### Contact information

<ResponseField name="phone_number" type="string | null" />

<ResponseField name="phone_country_code" type="string | null" />

### Address

<ResponseField name="address_line1" type="string | null" />

<ResponseField name="address_line2" type="string | null" />

<ResponseField name="city" type="string | null" />

<ResponseField name="state_province" type="string | null" />

<ResponseField name="country" type="string | null" />

<ResponseField name="country_name" type="string | null" />

<ResponseField name="postal_code" type="string | null" />

### Company

<ResponseField name="company_name" type="string | null" />

<ResponseField name="job_title" type="string | null" />

### Preferences

<ResponseField name="date_of_birth" type="string | null" />

<ResponseField name="timezone" type="string | null" />

<ResponseField name="preferred_language" type="string | null" />

<ResponseField name="billing_currency" type="string | null" />

### External IDs

<ResponseField name="stripe_id" type="string | null" />

<ResponseField name="hubspot_id" type="string | null" />

### Marketplace

<ResponseField name="marketplace_creator_bio" type="string | null" />

<ResponseField name="marketplace_creator_verified" type="boolean | null" />

### Team

<ResponseField name="team_id" type="number | null" />

<ResponseField name="team" type="object | null">
  <Expandable title="properties">
    <ResponseField name="id" type="number" />

    <ResponseField name="name" type="string" />

    <ResponseField name="brand" type="string" />

    <ResponseField name="owner_id" type="string" />

    <ResponseField name="created_at" type="string" />
  </Expandable>
</ResponseField>

### Subscription

<ResponseField name="subscription" type="object | null">
  <Expandable title="properties">
    <ResponseField name="id" type="number" />

    <ResponseField name="status" type="string | null" />

    <ResponseField name="price_id" type="string | null" />

    <ResponseField name="stripe_id" type="string | null" />

    <ResponseField name="quantity" type="number | null" />

    <ResponseField name="extra_quantity" type="number | null" />

    <ResponseField name="trial_ends_at" type="string | null" />

    <ResponseField name="ends_at" type="string | null" />

    <ResponseField name="created_at" type="string" />
  </Expandable>
</ResponseField>

### Call purchases

<ResponseField name="call_purchases" type="object[]">
  <Expandable title="properties">
    <ResponseField name="id" type="number" />

    <ResponseField name="quantity" type="number | null" />

    <ResponseField name="status" type="string | null" />

    <ResponseField name="stripe_subscription_id" type="string | null" />

    <ResponseField name="created_at" type="string" />
  </Expandable>
</ResponseField>

### Phone subscriptions

<ResponseField name="phone_subscriptions" type="object[]">
  <Expandable title="properties">
    <ResponseField name="id" type="string" />

    <ResponseField name="phone_number" type="string" />

    <ResponseField name="phone_type" type="string" />

    <ResponseField name="status" type="string" />

    <ResponseField name="stripe_price_id" type="string" />

    <ResponseField name="created_at" type="string" />
  </Expandable>
</ResponseField>

### Timestamps

<ResponseField name="created_at" type="string" />

<ResponseField name="updated_at" type="string" />

***

## Generate SSO token

Generates a signed, time-limited SSO token for the authenticated user. The token is used to authenticate the user into connected suite applications without a separate login.

When impersonation parameters are provided, the token encodes the target user's identity alongside the admin's, allowing the receiving application to establish an impersonated session.

<ParamField type="string">
  Must be `"profiles"`
</ParamField>

<ParamField type="string">
  Must be `"generate-sso-token"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The user ID of the account to impersonate. Must be supplied together with `adminUserId`. Both fields must be present for impersonation fields to be embedded; supplying only one has no effect.
    </ParamField>

    <ParamField type="string">
      The admin user's own ID. Must be supplied together with `impersonatedUserId`.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="token" type="string">
      A signed token string in the format `email={email}&ts={unix_timestamp}[&imp_uid={id}&admin_uid={id}]&sig={hmac_hex}`. Pass this value to the target suite application to authenticate the session.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Own session theme={null}
  const response = await ApiService.invoke<{ token: string }>({
    resource: "profiles",
    action: "generate-sso-token",
  });

  const ssoToken = response?.token;
  // Redirect: https://app.example.com/sso?token=<ssoToken>
  ```

  ```typescript With impersonation (admin) theme={null}
  const response = await ApiService.invoke<{ token: string }>({
    resource: "profiles",
    action: "generate-sso-token",
    data: {
      impersonatedUserId: "target-user-uuid",
      adminUserId: "admin-user-uuid",
    },
  });

  const ssoToken = response?.token;
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/profiles \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "generate-sso-token"
    }'
  ```
</CodeGroup>

***

## Generate sync consent link

Generates a signed, time-limited URL that redirects the user through an OAuth consent flow to authorise a third-party integration. The link is valid for a short window and is tied to the user's email address.

Regular users can only generate a link for their own email. Admins can generate a link for any user's email.

<ParamField type="string">
  Must be `"profiles"`
</ParamField>

<ParamField type="string">
  Must be `"generate-sync-consent-link"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The email address of the user to generate the link for. Must match the authenticated user's email unless the caller is an admin.
    </ParamField>

    <ParamField type="string">
      The integration to connect. Must be one of: `"airtable"`, `"anthropic"`, `"asana"`, `"github-app"`, `"google-calendar"`, `"google-sheet"`, `"hubspot"`, `"simpro"`, `"slack"`, `"supabase"`, `"xero"`.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="url" type="string">
      A signed consent URL. Redirect the user to this URL to complete the integration authorisation flow. The URL includes HMAC-verified query parameters (`email`, `ts`, `sig`, `connection`) and is time-limited.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Own account theme={null}
  const response = await ApiService.invoke<{ url: string }>({
    resource: "profiles",
    action: "generate-sync-consent-link",
    data: {
      email: "user@example.com",
      connection: "slack",
    },
  });

  // Redirect the user to response?.url to complete authorisation
  const consentUrl = response?.url;
  ```

  ```typescript Another user (admin only) theme={null}
  const response = await ApiService.invoke<{ url: string }>({
    resource: "profiles",
    action: "generate-sync-consent-link",
    data: {
      email: "customer@example.com",
      connection: "hubspot",
    },
  });

  const consentUrl = response?.url;
  ```

  ```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": "profiles",
      "action": "generate-sync-consent-link",
      "data": {
        "email": "user@example.com",
        "connection": "google-calendar"
      }
    }'
  ```
</CodeGroup>

***

## Usage summary

Returns a usage summary for the profile (calls, leads, conversations, etc.).

<ParamField type="string">
  `usage-summary`
</ParamField>

<ParamField type="string">
  Profile UUID. Defaults to the authenticated user. Admins may pass any profile ID.
</ParamField>

***

## Activity logging

Profile mutations are logged to the `activities` table:

| Action | Activity type | Action logged                                             |
| ------ | ------------- | --------------------------------------------------------- |
| Create | `user_action` | `profile_created`                                         |
| Update | `user_action` | `profile_updated` (includes `updated_fields` in metadata) |
| Delete | `user_action` | `profile_deleted`                                         |

***

## Error responses

| Status | Code               | Description                                                                     |
| ------ | ------------------ | ------------------------------------------------------------------------------- |
| 400    | `VALIDATION_ERROR` | Profile ID not provided                                                         |
| 401    | `UNAUTHORIZED`     | Invalid or missing authentication token                                         |
| 403    | `FORBIDDEN`        | Non-admin accessing admin-only action, or user accessing another user's profile |
| 404    | `NOT_FOUND`        | Profile does not exist                                                          |
| 500    | `INTERNAL_ERROR`   | Database operation failed                                                       |


# Pronunciation Vaults
Source: https://docs.helpgenie.ai/api-reference/pronunciation-vaults

Shared pronunciation dictionaries that define how your Genies pronounce specific words and names.

Pronunciation Vaults are shared libraries of word-to-phonetic mappings. Regular users can read public vaults; creating, updating, and deleting vaults is restricted to admins.

***

## Actions

### `all`

Returns all pronunciation vaults. Regular users only see public vaults. Admins see all vaults and can filter by accent.

**Parameters**

| Field    | Type   | Required | Description                        |
| -------- | ------ | -------- | ---------------------------------- |
| `accent` | string | No       | Admin only — filter by accent code |

**Response**

```json theme={null}
{
  "vaults": [
    {
      "id": "vault-uuid",
      "name": "General American English",
      "description": "Standard US English pronunciation guide",
      "accent": "en-US",
      "pairs": [
        { "word": "HelpGenie", "pronunciation": "help JEE-nee" }
      ],
      "is_public": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "count": 3
}
```

***

### `get`

Returns a single pronunciation vault by ID. Returns `NOT_FOUND` for non-public vaults accessed by regular users.

**Parameters**

| Field | Type   | Required | Description                       |
| ----- | ------ | -------- | --------------------------------- |
| `id`  | string | Yes      | Vault UUID (passed as request ID) |

**Response**

```json theme={null}
{
  "vault": {
    "id": "vault-uuid",
    "name": "General American English",
    "description": "Standard US English pronunciation guide",
    "accent": "en-US",
    "pairs": [ /* pronunciation pairs */ ],
    "is_public": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

***

### `create`

Creates a new pronunciation vault. **Admin only.**

**Parameters**

| Field         | Type    | Required | Description                                                      |
| ------------- | ------- | -------- | ---------------------------------------------------------------- |
| `name`        | string  | Yes      | Vault name                                                       |
| `description` | string  | No       | Optional description                                             |
| `accent`      | string  | No       | Accent code (e.g. `"en-US"`, `"en-GB"`)                          |
| `pairs`       | array   | No       | Pronunciation pairs — array of `{ word, pronunciation }` objects |
| `is_public`   | boolean | No       | Whether the vault is visible to all users, defaults to `true`    |

**Response** — `201`

```json theme={null}
{
  "vault": {
    "id": "vault-uuid",
    "name": "General American English",
    "pairs": [],
    "is_public": true,
    "created_at": "2024-01-01T00:00:00Z"
  }
}
```

***

### `update`

Updates a pronunciation vault. **Admin only.** Partial updates supported — only supplied fields are changed.

**Parameters**

| Field         | Type    | Required | Description                           |
| ------------- | ------- | -------- | ------------------------------------- |
| `id`          | string  | Yes      | Vault UUID (passed as request ID)     |
| `name`        | string  | No       | Updated name                          |
| `description` | string  | No       | Updated description                   |
| `accent`      | string  | No       | Updated accent code                   |
| `pairs`       | array   | No       | Replacement pronunciation pairs array |
| `is_public`   | boolean | No       | Updated visibility                    |

**Response**

```json theme={null}
{
  "vault": { /* updated vault */ }
}
```

***

### `delete`

Permanently deletes a pronunciation vault. **Admin only.** Irreversible.

**Parameters**

| Field | Type   | Required | Description                       |
| ----- | ------ | -------- | --------------------------------- |
| `id`  | string | Yes      | Vault UUID (passed as request ID) |

**Response**

```json theme={null}
{ "success": true, "message": "Vault deleted successfully" }
```

***

## Error codes

| Code               | Meaning                       |
| ------------------ | ----------------------------- |
| `VALIDATION_ERROR` | Missing required parameter    |
| `NOT_FOUND`        | Vault not found or not public |
| `FORBIDDEN`        | Admin access required         |
| `INTERNAL_ERROR`   | Unexpected server error       |


# Public Agent Pages
Source: https://docs.helpgenie.ai/api-reference/public-agent-pages

Unauthenticated endpoints for loading and requesting access to Agent Pages.

<Warning>
  Agent Pages are deprecated. Use [Public Genies](/api-reference/public-genies) for new integrations.
</Warning>

These routes use `resource: "agent-pages"` and require **no API key**. They serve the legacy Agent Page embed and access-request flow.

***

## Actions

### `url`

Loads an Agent Page by its URL slug. Returns the full page record with the joined Genie data. Validates access for private Genies via an access token header.

**Parameters**

| Field      | Type   | Required | Description                |
| ---------- | ------ | -------- | -------------------------- |
| `url_name` | string | Yes      | URL slug of the Agent Page |

**Headers**

| Header                 | Description                                                                 |
| ---------------------- | --------------------------------------------------------------------------- |
| `X-Agent-Access-Token` | Access grant token for private Genies. Required if the Genie is not public. |

**Response**

```json theme={null}
{
  "agentPage": {
    "id": "page-uuid",
    "url_name": "support-bot",
    "welcome_message": "How can I help you today?",
    "info_links": [ ],
    "agents": {
      "id": "agent-uuid",
      "name": "Support Genie",
      "elevenlabs_id": "el-agent-id",
      "settings": { },
      "branding": { },
      "is_active": true,
      "is_public": true
    }
  }
}
```

**Private Genie error** (when Genie is not public and no valid token):

```json theme={null}
{
  "success": false,
  "error": {
    "code": "GENIE_PRIVATE",
    "message": "This Genie is private",
    "status": 403,
    "genieName": "Support Genie"
  }
}
```

Access tokens are validated against `agent_access_grants`. Each valid use increments the grant's `use_count`.

***

### `request-access`

Submits an access request for a private Agent Page. Notifies the Genie owner by email. If the requester does not have a HelpGenie account, one is created automatically with a welcome email and set-password link.

**Parameters**

| Field      | Type   | Required | Description                |
| ---------- | ------ | -------- | -------------------------- |
| `url_name` | string | Yes      | URL slug of the Agent Page |
| `email`    | string | Yes      | Requester's email address  |

**Response**

```json theme={null}
{ "success": true }
```

Only valid for private Genies (`is_public: false`). Returns `VALIDATION_ERROR` if the Genie is already public.

***

## Error codes

| Code               | Meaning                                                 |
| ------------------ | ------------------------------------------------------- |
| `VALIDATION_ERROR` | Missing required parameter or Genie is already public   |
| `NOT_FOUND`        | Agent Page not found                                    |
| `GENIE_PRIVATE`    | Genie is private and no valid access token was provided |
| `FORBIDDEN`        | Access denied                                           |
| `INTERNAL_ERROR`   | Unexpected server error                                 |


# Public Genies
Source: https://docs.helpgenie.ai/api-reference/public-genies

Unauthenticated endpoints for loading, browsing, and interacting with public Genies.

These routes use `resource: "genies"` and require **no API key**. They are intended for consumer-facing surfaces — embedded widgets, public genie pages, QR code landing pages, and marketplace listings.

Only Genies with `is_public: true` (or `is_marketplace_genie: true`) are returned. Private Genies can be accessed via the `url` action by passing a valid `X-Agent-Access-Token` header.

***

## Actions

### `get`

Returns a single public Genie by UUID, including its page and QR code data.

**Parameters**

| Field | Type   | Required | Description             |
| ----- | ------ | -------- | ----------------------- |
| `id`  | string | Yes      | Genie UUID (request ID) |

**Response**

```json theme={null}
{
  "agent": {
    "id": "agent-uuid",
    "name": "Support Genie",
    "description": "AI-powered support assistant",
    "elevenlabs_id": "el-agent-id",
    "is_active": true,
    "is_public": true,
    "category": "Support",
    "voice_bridge_enabled": false,
    "voice_bridge_show_button": true,
    "branding": { },
    "agent_pages": { },
    "saved_qr_codes": [ ]
  }
}
```

Returns `AGENT_NOT_FOUND` if the Genie does not exist or is not public.

***

### `all`

Paginated list of public Genies with full data (including page and QR codes). Supports search and filtering.

**Parameters**

| Field                  | Type    | Required | Description                       |
| ---------------------- | ------- | -------- | --------------------------------- |
| `search` / `name`      | string  | No       | Case-insensitive name search      |
| `category`             | string  | No       | Filter by category                |
| `is_marketplace_genie` | boolean | No       | Filter to marketplace Genies only |
| `is_demo_genie`        | boolean | No       | Filter to demo Genies only        |
| `limit`                | number  | No       | Results per page (default `30`)   |
| `offset`               | number  | No       | Pagination offset (default `0`)   |

**Response**

```json theme={null}
{
  "agents": [ /* full Genie objects */ ],
  "count": 42,
  "limit": 30,
  "offset": 0
}
```

***

### `list`

Paginated list of public Genies with a lightweight field set — suitable for dropdowns and catalogue views.

**Parameters**

| Field                  | Type    | Required | Description                   |
| ---------------------- | ------- | -------- | ----------------------------- |
| `searchTerm`           | string  | No       | Searches name and description |
| `category`             | string  | No       | Filter by category            |
| `is_marketplace_genie` | boolean | No       | Filter to marketplace Genies  |
| `is_demo_genie`        | boolean | No       | Filter to demo Genies         |
| `limit`                | number  | No       | Default `30`                  |
| `offset`               | number  | No       | Default `0`                   |

**Response**

```json theme={null}
{
  "agents": [
    {
      "id": "agent-uuid",
      "name": "Support Genie",
      "description": "...",
      "elevenlabs_id": "el-agent-id",
      "is_active": true,
      "category": "Support",
      "voice_bridge_enabled": false,
      "voice_bridge_show_button": true,
      "branding": { },
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "count": 42,
  "limit": 30,
  "offset": 0
}
```

***

### `url`

Loads a Genie by its URL slug (`url_name`). Used by the embedded widget and genie page to bootstrap a conversation. Validates access for private Genies via an access token.

**Parameters**

| Field      | Type   | Required | Description           |
| ---------- | ------ | -------- | --------------------- |
| `url_name` | string | Yes      | URL slug of the Genie |

**Headers**

| Header                 | Description                                                                 |
| ---------------------- | --------------------------------------------------------------------------- |
| `X-Agent-Access-Token` | Access grant token for private Genies. Required if the Genie is not public. |

**Response**

```json theme={null}
{
  "agent": { /* full Genie object with page, QR codes, and access grants */ }
}
```

**Private Genie error** (when `is_public: false` and no valid token):

```json theme={null}
{
  "success": false,
  "error": {
    "code": "GENIE_PRIVATE",
    "message": "This Genie is private",
    "status": 403,
    "genieName": "Support Genie"
  }
}
```

Access tokens are validated against `agent_access_grants` — expired or exhausted grants are rejected. Each valid use increments the grant's `use_count`.

***

### `request-access`

Submits an access request for a private Genie identified by URL slug. Notifies the Genie owner by email. If the requester does not have an account, one is created automatically and a welcome email with a set-password link is sent.

**Parameters**

| Field      | Type   | Required | Description               |
| ---------- | ------ | -------- | ------------------------- |
| `url_name` | string | Yes      | URL slug of the Genie     |
| `email`    | string | Yes      | Requester's email address |

**Response**

```json theme={null}
{ "success": true }
```

Only valid for private Genies (`is_public: false`). Returns `VALIDATION_ERROR` if the Genie is already public.

***

### `accept-invite`

Accepts an invitation to access a Genie. Grants the user direct access via `agent_users` and links the Genie to their consumer profile. If the user does not have an account, one is created and a welcome email is sent.

**Parameters**

| Field      | Type   | Required | Description             |
| ---------- | ------ | -------- | ----------------------- |
| `url_name` | string | Yes      | URL slug of the Genie   |
| `email`    | string | Yes      | Invitee's email address |
| `agent_id` | string | Yes      | Genie UUID              |

**Response**

```json theme={null}
{
  "success": true,
  "consumerId": "user-uuid"
}
```

***

### `log-qr-scanned`

Logs a QR code scan event to the activity feed. Optionally associates the scan with a known consumer.

**Parameters**

| Field        | Type   | Required | Description                                  |
| ------------ | ------ | -------- | -------------------------------------------- |
| `genieId`    | string | Yes      | Genie UUID                                   |
| `genieName`  | string | No       | Genie name (for the activity log title)      |
| `urlName`    | string | No       | URL slug                                     |
| `consumerId` | string | No       | UUID of the authenticated consumer, if known |

**Response**

```json theme={null}
{ "success": true }
```

***

## Error codes

| Code               | Meaning                                                 |
| ------------------ | ------------------------------------------------------- |
| `VALIDATION_ERROR` | Missing required parameter or invalid request           |
| `NOT_FOUND`        | Genie not found                                         |
| `AGENT_NOT_FOUND`  | Genie not found or not public                           |
| `GENIE_PRIVATE`    | Genie is private and no valid access token was provided |
| `FORBIDDEN`        | Access denied                                           |
| `INTERNAL_ERROR`   | Unexpected server error                                 |


# Public Help Hub
Source: https://docs.helpgenie.ai/api-reference/public-help-hub

Unauthenticated endpoints for loading a Genie's public Help Hub and reading individual published guides.

These routes use `resource: "help-hub"` and require **no API key**. They are intended for consumer-facing surfaces — the public Help Hub page (`/help/:url_name`) and individual guide pages (`/help/:url_name/:documentId`).

Only Genies with `is_public: true` (or `is_marketplace_genie: true`) are served. A Help Hub can additionally be disabled per-Genie without making the Genie itself private.

Only documents the owner has explicitly marked `is_public` are included in any response from these endpoints.

***

## Get Help Hub

Returns the full public data for a Genie's Help Hub: branding, contact details, published guides grouped by topic, featured questions, downloadable resources, and quick-links.

<ParamField type="string">
  `help-hub`
</ParamField>

<ParamField type="string">
  `public-get`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The Genie's URL slug (e.g. `"acme-support"`). Also accepted as a query parameter.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="hub" type="object">
  <Expandable title="properties">
    <ResponseField name="genieId" type="string">Genie UUID.</ResponseField>
    <ResponseField name="urlName" type="string">Genie URL slug.</ResponseField>
    <ResponseField name="name" type="string">Genie display name.</ResponseField>
    <ResponseField name="description" type="string | null">Genie description.</ResponseField>
    <ResponseField name="welcomeMessage" type="string | null">Welcome message shown at the top of the hub.</ResponseField>

    <ResponseField name="branding" type="object">
      Hub branding derived from the Genie's configuration.

      <Expandable title="properties">
        <ResponseField name="primaryColor" type="string">Primary hex color (e.g. `"#4E9CFF"`). Defaults to `"#4E9CFF"` when unset.</ResponseField>
        <ResponseField name="secondaryColor" type="string | null">Secondary hex color, or `null` when unset.</ResponseField>
        <ResponseField name="logoUrl" type="string | null">HTTPS URL of the logo image, or `null`.</ResponseField>
        <ResponseField name="brandName" type="string | null">Brand name to display alongside the logo.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="phoneNumber" type="string | null">Live phone number for the Genie, or `null` if no active number is provisioned.</ResponseField>
    <ResponseField name="emailAddress" type="string | null">Provisioned support email address, or `null` if a mailbox is not active.</ResponseField>

    <ResponseField name="links" type="array">
      Quick-links curated by the owner. Maximum 12 links.

      <Expandable title="item properties">
        <ResponseField name="id" type="string">Link identifier.</ResponseField>
        <ResponseField name="label" type="string">Link display label.</ResponseField>
        <ResponseField name="url" type="string">Link destination URL (HTTPS or HTTP).</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="topics" type="array">
      Published guides grouped by folder topic, sorted by folder position then name. Empty when the owner has disabled the guide section. Unfoldered guides appear in a final topic named `"Everything else"`.

      <Expandable title="item properties">
        <ResponseField name="id" type="string">Topic (folder) ID, or `"unsorted"` for unfoldered guides.</ResponseField>
        <ResponseField name="name" type="string">Topic display name.</ResponseField>

        <ResponseField name="guides" type="array">
          Guides in this topic, sorted alphabetically by name.

          <Expandable title="item properties">
            <ResponseField name="id" type="string">Document UUID.</ResponseField>
            <ResponseField name="name" type="string">Guide title.</ResponseField>
            <ResponseField name="summary" type="string | null">One-line description from the document metadata.</ResponseField>
            <ResponseField name="updatedAt" type="string | null">ISO 8601 last-updated timestamp.</ResponseField>
            <ResponseField name="answers" type="string[]">Up to 8 questions this guide answers, used for hub search and the guide card preview.</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="guideCount" type="number">Total number of published guides. `0` when the guide section is disabled.</ResponseField>
    <ResponseField name="headline" type="string | null">Optional custom headline for the hub page.</ResponseField>
    <ResponseField name="subheadline" type="string | null">Optional subheadline.</ResponseField>
    <ResponseField name="askPlaceholder" type="string | null">Custom placeholder text for the chat input.</ResponseField>

    <ResponseField name="questions" type="array">
      Featured questions shown on the hub. Curated by the owner when configured; otherwise derived from the questions declared by published guides. Maximum 24. Empty when the owner has disabled the FAQ section.

      <Expandable title="item properties">
        <ResponseField name="id" type="string">Question identifier.</ResponseField>
        <ResponseField name="question" type="string">Question text.</ResponseField>
        <ResponseField name="topic" type="string | null">Topic label the question belongs to.</ResponseField>
        <ResponseField name="documentId" type="string | null">UUID of the guide that answers this question, or `null` if not linked to a specific guide.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="downloads" type="array">
      Downloadable resources (manuals, PDFs). Maximum 24.

      <Expandable title="item properties">
        <ResponseField name="id" type="string">Resource identifier.</ResponseField>
        <ResponseField name="label" type="string">Display label.</ResponseField>
        <ResponseField name="fileUrl" type="string">HTTPS URL of the file.</ResponseField>
        <ResponseField name="fileName" type="string | null">Original filename.</ResponseField>
        <ResponseField name="mimeType" type="string | null">MIME type (e.g. `"application/pdf"`).</ResponseField>
        <ResponseField name="sizeBytes" type="number | null">File size in bytes.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="contact" type="object | null">
      Contact details configured by the owner. `null` when no contact information is set.

      <Expandable title="properties">
        <ResponseField name="hours" type="string | null">Business hours text.</ResponseField>
        <ResponseField name="address" type="string | null">Physical address.</ResponseField>
        <ResponseField name="mapUrl" type="string | null">URL to a map or directions page.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="searchEngineVisible" type="boolean">
      Whether this hub has opted into search-engine indexing. `true` only when the owner enabled indexing **and** the hub has at least 3 published guides.
    </ResponseField>

    <ResponseField name="showApp" type="boolean">
      Whether the "Get the app" band should be shown on the hub page. Defaults to `true`; the owner can disable it without affecting the rest of the hub.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "help-hub",
    action: "public-get",
    data: { url_name: "acme-support" },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "help-hub",
      "action": "public-get",
      "data": { "url_name": "acme-support" }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "hub": {
        "genieId": "550e8400-e29b-41d4-a716-446655440000",
        "urlName": "acme-support",
        "name": "Acme Support",
        "description": "Get answers fast.",
        "branding": {
          "primaryColor": "#4E9CFF",
          "secondaryColor": null,
          "logoUrl": "https://example.com/logo.png",
          "brandName": "Acme Corp"
        },
        "phoneNumber": "+15551234567",
        "emailAddress": "support@acme.helpgenie.ai",
        "topics": [
          {
            "id": "folder-uuid",
            "name": "Getting Started",
            "guides": [
              {
                "id": "doc-uuid",
                "name": "How to create your first account",
                "summary": "A step-by-step guide for new users.",
                "updatedAt": "2024-06-26T10:00:00.000Z",
                "answers": ["How do I sign up?", "What do I need to get started?"]
              }
            ]
          }
        ],
        "guideCount": 1,
        "questions": [
          {
            "id": "doc-uuid:How do I sign up?",
            "question": "How do I sign up?",
            "topic": "Getting Started",
            "documentId": "doc-uuid"
          }
        ],
        "downloads": [],
        "links": [],
        "contact": null,
        "searchEngineVisible": false,
        "showApp": true
      }
    }
  }
  ```
</CodeGroup>

***

## Get guide

Returns the full content of a single published guide attached to a Genie's Help Hub. Both the Genie and the document must be public.

<ParamField type="string">
  `help-hub`
</ParamField>

<ParamField type="string">
  `public-guide`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The Genie's URL slug.
    </ParamField>

    <ParamField type="string">
      UUID of the guide document to retrieve.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="guide" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">Document UUID.</ResponseField>
    <ResponseField name="name" type="string">Guide title.</ResponseField>
    <ResponseField name="summary" type="string | null">One-line description.</ResponseField>

    <ResponseField name="topic" type="object | null">
      The folder this guide belongs to, or `null` if unfoldered.

      <Expandable title="properties">
        <ResponseField name="id" type="string | null">Folder UUID.</ResponseField>
        <ResponseField name="name" type="string">Folder display name.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="content" type="string">
      Full guide text as plain prose. Sections are separated by blank lines. Truncated to 60,000 characters.
    </ResponseField>

    <ResponseField name="truncated" type="boolean">
      `true` when the content exceeded 60,000 characters and was trimmed.
    </ResponseField>

    <ResponseField name="updatedAt" type="string | null">ISO 8601 last-updated timestamp.</ResponseField>
    <ResponseField name="genieName" type="string | null">Display name of the Genie this guide belongs to.</ResponseField>

    <ResponseField name="genieDocument" type="object | null">
      Structured branded document. Present only for guides authored with a branded template (FAQ, how-to, or one-pager). `null` for all other guide types.

      <Expandable title="properties">
        <ResponseField name="title" type="string">Document title.</ResponseField>
        <ResponseField name="subtitle" type="string | null">Optional subtitle.</ResponseField>
        <ResponseField name="template" type="string">Template type: `"faq"`, `"how-to"`, or `"one-pager"`.</ResponseField>

        <ResponseField name="sections" type="array">
          Document sections, in order. Maximum 40 sections.

          <Expandable title="item properties">
            <ResponseField name="heading" type="string">Section heading.</ResponseField>
            <ResponseField name="body" type="string">Section body text. Line breaks are preserved. Maximum 8,000 characters per section.</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "help-hub",
    action: "public-guide",
    data: {
      url_name: "acme-support",
      document_id: "770e8400-e29b-41d4-a716-446655440002",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "help-hub",
      "action": "public-guide",
      "data": {
        "url_name": "acme-support",
        "document_id": "770e8400-e29b-41d4-a716-446655440002"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "guide": {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "name": "How to create your first account",
        "summary": "A step-by-step guide for new users.",
        "topic": { "id": "folder-uuid", "name": "Getting Started" },
        "content": "Visit our website and click Sign up.\n\nEnter your business details and follow the setup wizard.\n\nYou will receive a confirmation email within a few minutes.",
        "truncated": false,
        "updatedAt": "2024-06-26T10:00:00.000Z",
        "genieName": "Acme Support",
        "genieDocument": null
      }
    }
  }
  ```
</CodeGroup>

***

## Error responses

| Status | Code               | Description                                                                                                                                                 |
| ------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `VALIDATION_ERROR` | `url_name` or `document_id` missing from the request                                                                                                        |
| 404    | `NOT_FOUND`        | Genie not found or not public; hub disabled by the owner; document not found, not public, or not attached to this Genie; guide content still being prepared |
| 500    | `INTERNAL_ERROR`   | Server error                                                                                                                                                |


# QR codes
Source: https://docs.helpgenie.ai/api-reference/qr-code

Manage saved QR code images for genie conversation pages

Manage saved QR code images generated for genies. QR codes link directly to genie conversation pages.

<Note>
  Users can only view and manage their own QR codes. There is no admin mode for this resource.
</Note>

***

## List QR codes

Lists all saved QR codes for the authenticated user.

<ParamField type="string">
  Must be `"qr-code"`.
</ParamField>

<ParamField type="string">
  Must be `"all"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Filter to QR codes for a specific genie.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="items" type="array">
      Array of QR code objects. Maximum 100 records, ordered by creation date (newest first).
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.helpgenie.ai/v1/qr-code \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "action": "all" }'
  ```

  ```json Request body theme={null}
  {
    "resource": "qr-code",
    "action": "all",
    "data": {
      "agentId": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
  ```
</CodeGroup>

***

## Create QR code

Creates a new QR code record.

<ParamField type="string">
  Must be `"qr-code"`.
</ParamField>

<ParamField type="string">
  Must be `"create"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Genie this QR code links to.
    </ParamField>

    <ParamField type="string">
      File path in the storage bucket.
    </ParamField>

    <ParamField type="string">
      Public URL of the QR image.
    </ParamField>

    <ParamField type="string">
      Image format (for example `"png"`, `"svg"`).
    </ParamField>

    <ParamField type="number">
      File size in bytes.
    </ParamField>

    <ParamField type="object">
      Custom display configuration.
    </ParamField>

    <ParamField type="string">
      URL the QR code points to.
    </ParamField>

    <ParamField type="string">
      Display filename.
    </ParamField>
  </Expandable>
</ParamField>

***

## Delete QR code

Soft-deletes a QR code record (sets `is_deleted` to `true`).

<ParamField type="string">
  Must be `"qr-code"`.
</ParamField>

<ParamField type="string">
  Must be `"delete"`.
</ParamField>

<ParamField type="string">
  The QR code record ID.
</ParamField>

***

## Increment download

Increments the download counter for a QR code.

<ParamField type="string">
  Must be `"qr-code"`.
</ParamField>

<ParamField type="string">
  Must be `"increment-download"`.
</ParamField>

<ParamField type="string">
  The QR code record ID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      Current download count (will be incremented by 1).
    </ParamField>
  </Expandable>
</ParamField>


# Teams
Source: https://docs.helpgenie.ai/api-reference/teams

Manage teams, team membership, and invitations.

All requests use a single endpoint: `POST https://api.helpgenie.ai/v1` with `resource: "teams"`.

## Access control

<Note>
  Access varies by action. Team owners and internal admins have full access to all actions. Team members have read-only access to `get` and `members`. Any authenticated user can create a team.
</Note>

| Action                | Any user | Team member     | Team owner | Admin |
| --------------------- | -------- | --------------- | ---------- | ----- |
| `get`                 | No       | Yes (read-only) | Yes        | Yes   |
| `create`              | Yes      | --              | --         | Yes   |
| `update`              | No       | No              | Yes        | Yes   |
| `delete`              | No       | No              | Yes        | Yes   |
| `members`             | No       | Yes             | Yes        | Yes   |
| `invite`              | No       | No              | Yes        | Yes   |
| `invitations`         | No       | No              | Yes        | Yes   |
| `cancel-invite`       | No       | No              | Yes        | Yes   |
| `resend-invite`       | No       | No              | Yes        | Yes   |
| `remove-member`       | No       | No              | Yes        | Yes   |
| `get-branding`        | No       | Yes             | Yes        | Yes   |
| `update-branding`     | No       | No              | Yes        | Yes   |
| `clear-branding`      | No       | No              | Yes        | Yes   |
| `share-genie`         | No       | No              | Yes        | Yes   |
| `grant-genie-access`  | No       | No              | Yes        | Yes   |
| `remove-genie-access` | No       | No              | Yes        | Yes   |

<Warning>
  Only team owners and internal admins can manage invitations and remove members. Regular team members have read-only access to `get` and `members` actions only.
</Warning>

### Team management workflow

<Steps>
  <Step title="Create a team">
    Use the `create` action to set up a new team. The authenticated user automatically becomes the team owner.
  </Step>

  <Step title="Invite members">
    Use the `invite` action to send invitations by email. Track pending invitations with the `invitations` action.
  </Step>

  <Step title="Members accept">
    Invited users accept the invitation to join the team. Their profile is updated with the `team_id`.
  </Step>

  <Step title="Manage the team">
    Use `members` to view the roster, `remove-member` to remove users, and `cancel-invite` to revoke pending invitations.
  </Step>
</Steps>

***

## Get a team

Retrieves a specific team by ID with all team members.

<ParamField type="string">
  Must be `"teams"`
</ParamField>

<ParamField type="string">
  Must be `"get"`
</ParamField>

<ParamField type="string">
  The team ID.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="team" type="object">
      <Expandable title="properties">
        <ResponseField name="id" type="number" />

        <ResponseField name="name" type="string" />

        <ResponseField name="brand" type="string" />

        <ResponseField name="branding" type="object" />

        <ResponseField name="owner_id" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="members" type="object[]">
      <Expandable title="properties">
        <ResponseField name="id" type="string" />

        <ResponseField name="full_name" type="string" />

        <ResponseField name="email" type="string" />

        <ResponseField name="avatar_url" type="string" />

        <ResponseField name="role" type="string">
          Either `"Owner"` or `"Member"`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    team: Team;
    members: TeamMember[];
  }>({
    resource: "teams",
    action: "get",
    id: "123",
  });
  ```
</CodeGroup>

***

## Create a team

Creates a new team. The authenticated user automatically becomes the team owner.

<ParamField type="string">
  Must be `"teams"`
</ParamField>

<ParamField type="string">
  Must be `"create"`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Team name.
    </ParamField>

    <ParamField type="string">
      Team brand name.
    </ParamField>

    <ParamField type="object">
      Branding configuration (e.g. colors, logos).
    </ParamField>
  </Expandable>
</ParamField>

### Response (status 201)

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="team" type="object">
      The newly created team object.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ team: Team }>(
    {
      resource: "teams",
      action: "create",
      data: {
        name: "Marketing Team",
        brand: "ACME Corp",
        branding: { color: "#FF0000" },
      },
    },
    201
  );
  ```
</CodeGroup>

***

## Update a team

Updates team settings such as name, brand, and branding.

<ParamField type="string">
  Must be `"teams"`
</ParamField>

<ParamField type="string">
  Must be `"update"`
</ParamField>

<ParamField type="string">
  The team ID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Updated team name.
    </ParamField>

    <ParamField type="string">
      Updated brand name.
    </ParamField>

    <ParamField type="object">
      Updated branding configuration.
    </ParamField>

    <ParamField type="string">
      Admin only. Transfers team ownership to this user ID. The new owner must already be a member of the team and cannot be the current owner.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="team" type="object">
      The updated team object.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ team: Team }>({
    resource: "teams",
    action: "update",
    id: "123",
    data: {
      name: "Updated Team Name",
    },
  });
  ```
</CodeGroup>

***

## Delete a team

Permanently deletes a team and removes all members.

<ParamField type="string">
  Must be `"teams"`
</ParamField>

<ParamField type="string">
  Must be `"delete"`
</ParamField>

<ParamField type="string">
  The team ID.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="message" type="string">
      Deletion result description.
    </ResponseField>

    <ResponseField name="errors" type="string[]">
      Array of any cleanup errors, if applicable.
    </ResponseField>
  </Expandable>
</ResponseField>

<Warning>
  This permanently deletes the team and removes all member associations.
</Warning>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    success: boolean;
    message: string;
  }>({
    resource: "teams",
    action: "delete",
    id: "123",
  });
  ```
</CodeGroup>

***

## List team members

Retrieves all members of a team.

<ParamField type="string">
  Must be `"teams"`
</ParamField>

<ParamField type="string">
  Must be `"members"`
</ParamField>

<ParamField type="string">
  The team ID.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="members" type="object[]">
      <Expandable title="properties">
        <ResponseField name="id" type="string" />

        <ResponseField name="full_name" type="string" />

        <ResponseField name="email" type="string" />

        <ResponseField name="avatar_url" type="string" />

        <ResponseField name="role" type="string">
          Either `"Owner"` or `"Member"`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number">
      Total number of members.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    members: TeamMember[];
    count: number;
  }>({
    resource: "teams",
    action: "members",
    id: "123",
  });
  ```
</CodeGroup>

***

## Invite a member

Sends a team invitation to an email address. If a previous invitation exists for the same email, it is replaced. The invitee receives an email and must accept before joining.

<ParamField type="string">
  Must be `"teams"`
</ParamField>

<ParamField type="string">
  Must be `"invite"`
</ParamField>

<ParamField type="string">
  The team ID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Email address of the person to invite.
    </ParamField>

    <ParamField type="string">
      Admin only. Sends the invitation on behalf of this user ID.
    </ParamField>
  </Expandable>
</ParamField>

### Response (status 201)

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="invitation" type="object">
      <Expandable title="properties">
        <ResponseField name="id" type="string">
          Invitation UUID.
        </ResponseField>

        <ResponseField name="email" type="string">
          Email address the invitation was sent to.
        </ResponseField>

        <ResponseField name="status" type="string">
          Always `"pending"` for a newly created invitation.
        </ResponseField>

        <ResponseField name="invited_at" type="string">
          ISO 8601 timestamp of when the invitation was sent.
        </ResponseField>

        <ResponseField name="accepted_at" type="string | null">
          ISO 8601 timestamp of acceptance, or `null` if not yet accepted.
        </ResponseField>

        <ResponseField name="expires_at" type="string | null">
          ISO 8601 expiry timestamp, or `null` if no expiry is set.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ invitation: TeamInvitation }>({
    resource: "teams",
    action: "invite",
    id: "123",
    data: {
      email: "user@example.com",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/teams \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "teams",
      "action": "invite",
      "id": "123",
      "data": {
        "email": "newmember@example.com"
      }
    }'
  ```
</CodeGroup>

***

## List pending invitations

Retrieves all pending invitations for a team.

<ParamField type="string">
  Must be `"teams"`
</ParamField>

<ParamField type="string">
  Must be `"invitations"`
</ParamField>

<ParamField type="string">
  The team ID.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="invitations" type="object[]">
      <Expandable title="properties">
        <ResponseField name="id" type="string">
          Invitation UUID.
        </ResponseField>

        <ResponseField name="email" type="string">
          Invited email address.
        </ResponseField>

        <ResponseField name="status" type="string">
          Current invitation status (e.g. `"pending"`).
        </ResponseField>

        <ResponseField name="invited_at" type="string">
          ISO 8601 timestamp of when the invitation was sent.
        </ResponseField>

        <ResponseField name="accepted_at" type="string | null">
          ISO 8601 timestamp of acceptance, or `null` if not yet accepted.
        </ResponseField>

        <ResponseField name="expires_at" type="string | null">
          ISO 8601 expiry timestamp, or `null` if no expiry is set.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number">
      Number of pending invitations.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    invitations: TeamInvitation[];
    count: number;
  }>({
    resource: "teams",
    action: "invitations",
    id: "123",
  });
  ```
</CodeGroup>

***

## Cancel an invitation

Cancels a pending team invitation.

<ParamField type="string">
  Must be `"teams"`
</ParamField>

<ParamField type="string">
  Must be `"cancel-invite"`
</ParamField>

<ParamField type="string">
  The invitation UUID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      The team ID the invitation belongs to.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ success: boolean }>({
    resource: "teams",
    action: "cancel-invite",
    id: "invitation-uuid",
    data: {
      teamId: 123,
    },
  });
  ```
</CodeGroup>

***

## Resend an invitation

Refreshes the timestamp on a pending invitation, triggering a new invitation email to the invitee.

<ParamField type="string">
  Must be `"teams"`
</ParamField>

<ParamField type="string">
  Must be `"resend-invite"`
</ParamField>

<ParamField type="string">
  The invitation UUID to resend.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="number">
      The team ID the invitation belongs to.
    </ParamField>

    <ParamField type="string">
      Admin only. Perform this action on behalf of this user ID.
    </ParamField>
  </Expandable>
</ParamField>

<Note>
  Only invitations with `status: "pending"` can be resent. Returns 404 if the invitation is not found or is no longer pending.
</Note>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="invitation" type="object">
      <Expandable title="properties">
        <ResponseField name="id" type="string">
          Invitation UUID.
        </ResponseField>

        <ResponseField name="email" type="string">
          Email address the invitation was sent to.
        </ResponseField>

        <ResponseField name="status" type="string">
          Always `"pending"` for a resent invitation.
        </ResponseField>

        <ResponseField name="invited_at" type="string">
          ISO 8601 timestamp updated to the time the invitation was resent.
        </ResponseField>

        <ResponseField name="accepted_at" type="string | null">
          ISO 8601 timestamp of acceptance, or `null` if not yet accepted.
        </ResponseField>

        <ResponseField name="expires_at" type="string | null">
          ISO 8601 expiry timestamp, or `null` if no expiry is set.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ invitation: TeamInvitation }>({
    resource: "teams",
    action: "resend-invite",
    id: "invitation-uuid",
    data: {
      teamId: 123,
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Content-Type: application/json" \
    -H "x-api-key: hg_live_YOUR_KEY" \
    -d '{
      "resource": "teams",
      "action": "resend-invite",
      "id": "invitation-uuid",
      "data": {
        "teamId": 123
      }
    }'
  ```
</CodeGroup>

***

## Remove a member

Removes a member from a team.

<ParamField type="string">
  Must be `"teams"`
</ParamField>

<ParamField type="string">
  Must be `"remove-member"`
</ParamField>

<ParamField type="string">
  The team ID.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The user UUID of the member to remove.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ success: boolean }>({
    resource: "teams",
    action: "remove-member",
    id: "123",
    data: {
      memberId: "user-uuid",
    },
  });
  ```
</CodeGroup>

***

## Branding actions

### `get-branding`

Returns the team's branding configuration.

**Parameters** — none (uses the authenticated user's team).

***

### `update-branding`

Updates the team's branding (colors, logo, gradient settings). Team owner or admin only.

**Parameters**

| Field             | Type    | Description                 |
| ----------------- | ------- | --------------------------- |
| `primaryColor`    | string  | Primary brand color (hex)   |
| `secondaryColor`  | string  | Secondary brand color (hex) |
| `logoUrl`         | string  | URL of the brand logo       |
| `gradientEnabled` | boolean | Whether gradient is enabled |

***

### `clear-branding`

Resets all branding fields to null. Team owner or admin only.

**Parameters** — none.

***

## Genie sharing actions

### `share-genie`

Shares a Genie with team members.

**Parameters**

| Field     | Type   | Required | Description         |
| --------- | ------ | -------- | ------------------- |
| `agentId` | string | Yes      | Genie UUID to share |

***

### `grant-genie-access`

Grants a team member access to a specific Genie.

**Parameters**

| Field     | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| `agentId` | string | Yes      | Genie UUID                       |
| `userId`  | string | Yes      | Team member UUID to grant access |

***

### `remove-genie-access`

Revokes a team member's access to a specific Genie.

**Parameters**

| Field     | Type   | Required | Description                |
| --------- | ------ | -------- | -------------------------- |
| `agentId` | string | Yes      | Genie UUID                 |
| `userId`  | string | Yes      | Team member UUID to revoke |

***

## Error responses

| Status | Code               | Description                             |
| ------ | ------------------ | --------------------------------------- |
| 400    | `VALIDATION_ERROR` | Missing or invalid required parameters  |
| 401    | `UNAUTHORIZED`     | No valid authentication token           |
| 403    | `FORBIDDEN`        | User lacks permission for the operation |
| 404    | `NOT_FOUND`        | Team or resource not found              |
| 500    | `INTERNAL_ERROR`   | Server error during processing          |


# Voice collections
Source: https://docs.helpgenie.ai/api-reference/voice-collections

DEPRECATED — the voice-collections resource has been removed

<Warning>
  The `voice-collections` resource has been removed and is no longer available. Requests to this resource will return a `NOT_FOUND` error.
</Warning>


# Voices
Source: https://docs.helpgenie.ai/api-reference/voices

Browse and search voices, manage favorites, and track voice usage

## List voices

Retrieves all available voices from the voice library.

<ParamField type="string">
  `voices`
</ParamField>

<ParamField type="string">
  `list`
</ParamField>

<ParamField type="object">
  Any filter or pagination parameters supported by the voice library are forwarded as-is.
</ParamField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "voices",
    action: "list",
  });
  ```

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

### Response

Returns voice library data forwarded directly from the upstream voice service.

***

## List shared voices

Retrieves voices from the shared voice library.

<ParamField type="string">
  `voices`
</ParamField>

<ParamField type="string">
  `list-shared`
</ParamField>

<ParamField type="object">
  Any filter or pagination parameters supported by the voice library are forwarded as-is.
</ParamField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "voices",
    action: "list-shared",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/voices \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "voices",
      "action": "list-shared"
    }'
  ```
</CodeGroup>

### Response

Returns shared voice library data forwarded directly from the upstream voice service.

***

## Search voices

Searches the voice library by one or more search terms.

<ParamField type="string">
  `voices`
</ParamField>

<ParamField type="string">
  `search`
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string[]">
      Array of search terms. At least one term is required.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "voices",
    action: "search",
    data: {
      terms: ["Rachel", "American", "calm"],
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/voices \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "voices",
      "action": "search",
      "data": {
        "terms": ["Rachel", "American", "calm"]
      }
    }'
  ```
</CodeGroup>

### Response

Returns matching voice data forwarded directly from the upstream voice service.

***

## List favorite voices

Retrieves all voices that the authenticated user has added to their favorites.

<ParamField type="string">
  `voices`
</ParamField>

<ParamField type="string">
  `favorites`
</ParamField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "voices",
    action: "favorites",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/voices \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "voices",
      "action": "favorites"
    }'
  ```
</CodeGroup>

### Response

<ResponseField name="favorites" type="VoiceFavorite[]">
  Array of favorited voice records.

  <Expandable title="VoiceFavorite object">
    <ResponseField name="id" type="string">
      Unique favorite record identifier.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      ID of the user who favorited the voice.
    </ResponseField>

    <ResponseField name="voice_id" type="string">
      The external voice identifier.
    </ResponseField>

    <ResponseField name="voice_data" type="object">
      Voice metadata stored at the time of favoriting.
    </ResponseField>

    <ResponseField name="favorited_at" type="string | null">
      ISO 8601 timestamp of when the voice was favorited.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="number">
  Total number of favorited voices.
</ResponseField>

***

## Add favorite voice

Adds a voice to the authenticated user's favorites. If the voice is already favorited, returns the existing record without creating a duplicate.

<ParamField type="string">
  `voices`
</ParamField>

<ParamField type="string">
  `add-favorite`
</ParamField>

<ParamField type="string">
  The voice ID to add to favorites.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="object">
      Voice metadata to store with the favorite record (name, language, accent, etc.).
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "voices",
    action: "add-favorite",
    id: "voice-id",
    data: {
      voice_data: {
        name: "Rachel",
        language: "en",
        accent: "American",
      },
    },
  });
  ```
</CodeGroup>

### Response (status 201)

<ResponseField name="favorite" type="VoiceFavorite">
  The newly created favorite record. See the [VoiceFavorite object](#list-favorite-voices) for field details.
</ResponseField>

If the voice is already favorited, the response returns:

<ResponseField name="already_favorited" type="boolean">
  `true` when the voice was already in favorites.
</ResponseField>

<ResponseField name="voice_id" type="string">
  The voice ID that was already favorited.
</ResponseField>

***

## Remove favorite voice

Removes a voice from the authenticated user's favorites.

<ParamField type="string">
  `voices`
</ParamField>

<ParamField type="string">
  `remove-favorite`
</ParamField>

<ParamField type="string">
  The voice ID to remove from favorites.
</ParamField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "voices",
    action: "remove-favorite",
    id: "voice-id",
  });
  ```
</CodeGroup>

### Response

<ResponseField name="success" type="boolean">
  `true` if the voice was successfully removed from favorites.
</ResponseField>

<ResponseField name="voice_id" type="string">
  The voice ID that was removed.
</ResponseField>

***

## Track voice usage

Records that a voice was used. This is a fire-and-forget operation; errors are logged server-side but do not cause the request to fail.

<ParamField type="string">
  `voices`
</ParamField>

<ParamField type="string">
  `track-usage`
</ParamField>

<ParamField type="string">
  The voice ID to track usage for.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      The context in which the voice was used. Valid values:

      | Value            | Description                                   |
      | ---------------- | --------------------------------------------- |
      | `preview`        | User previewed / listened to the voice sample |
      | `select`         | User selected the voice for an existing genie |
      | `agent_creation` | Voice was chosen during new genie creation    |
    </ParamField>

    <ParamField type="string">
      The genie ID, if the usage is related to genie creation or configuration.
    </ParamField>
  </Expandable>
</ParamField>

<Note>
  Authentication is optional. Anonymous usage is tracked when no token is provided.
</Note>

<Tip>
  Track-usage is a fire-and-forget operation. The endpoint always returns `{ success: true }` even if the underlying database write fails. Errors are logged server-side but are never surfaced to the caller, so it is safe to call without awaiting or error-handling.
</Tip>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "voices",
    action: "track-usage",
    id: "voice-id",
    data: {
      context: "agent_creation",
      agentId: "agent-uuid",
    },
  });
  ```
</CodeGroup>

### Response

<ResponseField name="success" type="boolean">
  Always returns `true`, regardless of whether the tracking write succeeded internally.
</ResponseField>


# Worker genies
Source: https://docs.helpgenie.ai/api-reference/worker-genies

Create and manage autonomous background AI agents that execute tasks on schedule, by event, or manually

Worker genies are autonomous background AI agents powered by Anthropic Claude. They can execute tasks on schedule, by event trigger, or on-demand. Each worker genie has access to tools including `web_fetch`, `memory_read`, `memory_write`, `query_data`, and `notify_owner`.

<Note>
  Worker genies run server-side and have access to stored credentials for calling external APIs securely.
</Note>

***

## List worker genies

Retrieves all worker genies for the authenticated user.

<ParamField type="string">
  Must be `"worker-genies"`.
</ParamField>

<ParamField type="string">
  Must be `"all"` or `"list"`.
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="items" type="array">
      <Expandable title="item properties">
        <ResponseField name="id" type="string">Worker genie UUID.</ResponseField>
        <ResponseField name="name" type="string">Display name.</ResponseField>
        <ResponseField name="soul_prompt" type="string">Instructions for the genie.</ResponseField>
        <ResponseField name="model" type="string">AI model identifier.</ResponseField>
        <ResponseField name="trigger_type" type="string">`manual`, `schedule`, or `event`.</ResponseField>
        <ResponseField name="schedule" type="string">Cron expression (if scheduled).</ResponseField>
        <ResponseField name="credential_refs" type="string[]">Names of stored credentials.</ResponseField>
        <ResponseField name="enabled" type="boolean">Whether the genie is active.</ResponseField>
        <ResponseField name="last_run_at" type="string">ISO 8601 timestamp of last run.</ResponseField>
        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
        <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s https://api.helpgenie.ai/v1/worker-genies \
    -H "Authorization: Bearer hg_live_YOUR_KEY"
  ```

  ```json Request body theme={null}
  {
    "resource": "worker-genies",
    "action": "all"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "items": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "HubSpot Contact Digest",
          "soul_prompt": "You are a sales intelligence worker...",
          "model": "claude-sonnet-4-6",
          "trigger_type": "manual",
          "schedule": null,
          "credential_refs": ["hubspot_api"],
          "enabled": true,
          "last_run_at": "2024-03-01T10:00:00.000Z",
          "created_at": "2024-01-15T10:30:00.000Z",
          "updated_at": "2024-01-15T10:30:00.000Z"
        }
      ]
    }
  }
  ```
</CodeGroup>

***

## Get worker genie

Retrieves a single worker genie by ID, including recent run history.

<ParamField type="string">
  Must be `"worker-genies"`.
</ParamField>

<ParamField type="string">
  Must be `"get"`.
</ParamField>

<ParamField type="string">
  The UUID of the worker genie.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s https://api.helpgenie.ai/v1/worker-genies/GENIE_UUID \
    -H "Authorization: Bearer hg_live_YOUR_KEY"
  ```

  ```json Request body theme={null}
  {
    "resource": "worker-genies",
    "action": "get",
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</CodeGroup>

***

## Create worker genie

Creates a new worker genie with the specified configuration.

<ParamField type="string">
  Must be `"worker-genies"`.
</ParamField>

<ParamField type="string">
  Must be `"create"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Display name for the worker genie.
    </ParamField>

    <ParamField type="string">
      Detailed instructions for what the genie should do during each run.
    </ParamField>

    <ParamField type="string">
      AI model identifier.
    </ParamField>

    <ParamField type="string">
      `manual`, `schedule`, or `event`.
    </ParamField>

    <ParamField type="string">
      Cron expression. Required when `trigger_type` is `schedule`.
    </ParamField>

    <ParamField type="string[]">
      Names of stored credentials this genie can access during runs.
    </ParamField>

    <ParamField type="boolean">
      Whether the genie is active.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.helpgenie.ai/v1/worker-genies \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "HubSpot Contact Digest",
      "soul_prompt": "You are a sales intelligence worker. Use web_fetch with the hubspot_api credential to call the HubSpot API...",
      "trigger_type": "manual",
      "credential_refs": ["hubspot_api"]
    }'
  ```

  ```json Request body theme={null}
  {
    "resource": "worker-genies",
    "action": "create",
    "data": {
      "name": "HubSpot Contact Digest",
      "soul_prompt": "You are a sales intelligence worker. Use web_fetch with the hubspot_api credential to call the HubSpot API...",
      "trigger_type": "manual",
      "credential_refs": ["hubspot_api"]
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "HubSpot Contact Digest",
      "soul_prompt": "You are a sales intelligence worker...",
      "model": "claude-sonnet-4-6",
      "trigger_type": "manual",
      "enabled": true,
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  }
  ```
</CodeGroup>

***

## Update worker genie

Updates an existing worker genie. Supports partial updates.

<ParamField type="string">
  Must be `"worker-genies"`.
</ParamField>

<ParamField type="string">
  Must be `"update"`.
</ParamField>

<ParamField type="string">
  The UUID of the worker genie to update.
</ParamField>

***

## Delete worker genie

Permanently deletes a worker genie and all of its run history.

<ParamField type="string">
  Must be `"worker-genies"`.
</ParamField>

<ParamField type="string">
  Must be `"delete"`.
</ParamField>

<ParamField type="string">
  The UUID of the worker genie to delete.
</ParamField>

<Warning>
  This action is irreversible. The worker genie and all associated run history will be permanently deleted.
</Warning>

***

## Run worker genie

Triggers a manual run of a worker genie. The run executes asynchronously and results can be retrieved via run history.

<ParamField type="string">
  Must be `"worker-genies"`.
</ParamField>

<ParamField type="string">
  Must be `"run"`.
</ParamField>

<ParamField type="string">
  The UUID of the worker genie to run.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Additional context passed to the genie for this run.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.helpgenie.ai/v1/worker-genies \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "action": "run", "id": "GENIE_UUID" }'
  ```

  ```json Request body theme={null}
  {
    "resource": "worker-genies",
    "action": "run",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "data": {
      "context": "Focus on new contacts from the last 24 hours"
    }
  }
  ```
</CodeGroup>

***

## Get run history

Retrieves the execution history for a worker genie or all worker genies.

<ParamField type="string">
  Must be `"worker-genies"`.
</ParamField>

<ParamField type="string">
  Must be `"runs"`.
</ParamField>

<ParamField type="string">
  Optional worker genie UUID. If omitted, returns runs for all genies.
</ParamField>

<ResponseField name="data.items" type="array">
  <Expandable title="item properties">
    <ResponseField name="id" type="string">Run UUID.</ResponseField>
    <ResponseField name="genie_id" type="string">Worker genie UUID.</ResponseField>
    <ResponseField name="trigger" type="string">What triggered the run (`manual`, `schedule`, `event`).</ResponseField>
    <ResponseField name="status" type="string">Run status.</ResponseField>
    <ResponseField name="started_at" type="string">ISO 8601 start timestamp.</ResponseField>
    <ResponseField name="finished_at" type="string">ISO 8601 end timestamp.</ResponseField>
    <ResponseField name="summary" type="string">AI-generated summary of the run.</ResponseField>
    <ResponseField name="tool_calls_count" type="number">Number of tool calls made.</ResponseField>
    <ResponseField name="error" type="string">Error message if the run failed.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.helpgenie.ai/v1/worker-genies \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "action": "runs", "id": "GENIE_UUID" }'
  ```

  ```json Request body theme={null}
  {
    "resource": "worker-genies",
    "action": "runs",
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</CodeGroup>

***

## Test credential

Tests a credential before or after storing. Can test an already-stored credential by name, or test a new credential value before committing it. Optionally makes a test HTTP request to verify the credential works.

<ParamField type="string">
  Must be `"worker-genies"`.
</ParamField>

<ParamField type="string">
  Must be `"test-credential"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Name of an already-stored credential to test. If provided without `value`, tests the stored credential.
    </ParamField>

    <ParamField type="string">
      A credential value to test before storing. Used with `credential_type`.
    </ParamField>

    <ParamField type="string">
      Type of the credential being tested. Default: `"bearer_token"`.
    </ParamField>

    <ParamField type="string">
      URL to make a test request against. If omitted, only checks that the credential exists.
    </ParamField>

    <ParamField type="string">
      Custom header name for `api_key_header` type. Default: `"X-Api-Key"`.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="valid" type="boolean">
      Whether the credential test passed.
    </ResponseField>

    <ResponseField name="status" type="number">
      HTTP status code from the test request (if a URL was provided).
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable result message.
    </ResponseField>

    <ResponseField name="error" type="string">
      Error message if the test failed.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.helpgenie.ai/v1/worker-genies \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "test-credential",
      "data": {
        "name": "hubspot_api",
        "url": "https://api.hubapi.com/crm/v3/objects/contacts?limit=1"
      }
    }'
  ```
</CodeGroup>

***

## Store credential

Stores an encrypted API credential that worker genies can use during runs. Credentials are encrypted at rest using AES-GCM.

<ParamField type="string">
  Must be `"worker-genies"`.
</ParamField>

<ParamField type="string">
  Must be `"store-credential"`.
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string">
      Unique name used as a reference in `credential_refs`.
    </ParamField>

    <ParamField type="string">
      `bearer_token`, `api_key_header`, `basic_auth`, or `oauth2`.
    </ParamField>

    <ParamField type="string">
      The secret value to store.
    </ParamField>

    <ParamField type="object">
      Extra configuration, for example `{ "header_name": "X-Api-Key" }`.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.helpgenie.ai/v1/worker-genies \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "store-credential",
      "name": "hubspot_api",
      "credential_type": "bearer_token",
      "value": "pat-na1-xxxxx"
    }'
  ```
</CodeGroup>

***

## List credentials

Lists all stored credentials for the authenticated user. Secret values are never returned.

<ParamField type="string">
  Must be `"worker-genies"`.
</ParamField>

<ParamField type="string">
  Must be `"list-credentials"`.
</ParamField>

<ResponseField name="data.items" type="array">
  <Expandable title="item properties">
    <ResponseField name="id" type="string">Credential UUID.</ResponseField>
    <ResponseField name="name" type="string">Credential name.</ResponseField>
    <ResponseField name="credential_type" type="string">Type of credential.</ResponseField>
    <ResponseField name="metadata" type="object">Extra configuration.</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.helpgenie.ai/v1/worker-genies \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "action": "list-credentials" }'
  ```
</CodeGroup>

***

## Delete credential

Deletes a stored credential by ID.

<ParamField type="string">
  Must be `"worker-genies"`.
</ParamField>

<ParamField type="string">
  Must be `"delete-credential"`.
</ParamField>

<ParamField type="string">
  The UUID of the credential to delete.
</ParamField>

***

## Available tools

Worker genies have access to the following tools during execution:

| Tool           | Description                                                                                                |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| `web_fetch`    | HTTP request to any URL. Supports GET, POST, PUT, PATCH, DELETE. Auto-injects stored credentials.          |
| `memory_read`  | Read from durable memory store (account or genie-scoped).                                                  |
| `memory_write` | Write to durable memory store. Persists across runs.                                                       |
| `query_data`   | Query internal tables: conversations, leads, call\_logs, agents, lead\_activities, documents, email\_logs. |
| `notify_owner` | Send email or dashboard notification to the account owner.                                                 |


# Authentication
Source: https://docs.helpgenie.ai/getting-started/authentication

Authenticate with the HelpGenie API using API keys or session tokens

All API requests require authentication. The recommended method for external integrations is an **API key**.

## Method 1: API Key (recommended)

Create an API key in [Help Genie](https://helpgenie.ai) → **Settings** → **API Keys** → **Create Key**.

The full key is shown **once** — copy it immediately and store it securely. Keys use the `hg_live_` prefix.

Pass your key using either method:

<CodeGroup>
  ```bash Authorization header theme={null}
  curl https://api.helpgenie.ai/v1/genies \
    -H "Authorization: Bearer hg_live_YOUR_KEY"
  ```

  ```bash X-API-Key header theme={null}
  curl https://api.helpgenie.ai/v1/genies \
    -H "X-API-Key: hg_live_YOUR_KEY"
  ```

  ```typescript fetch theme={null}
  const response = await fetch("https://api.helpgenie.ai/v1/genies", {
    headers: {
      Authorization: "Bearer hg_live_YOUR_KEY",
    },
  });

  const result = await response.json();
  ```
</CodeGroup>

**Key details:**

* Don't expire — work until revoked
* Rate limited: **60 requests/minute** per key
* Max **5 active keys** per user
* Keys carry the same permissions as the user who created them

## Method 2: Session Token (for browser/app contexts)

For browser-based applications, authenticate with Supabase Auth:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { createClient } from "@supabase/supabase-js";

  const supabase = createClient(
    "https://<project-ref>.supabase.co",
    "<anon-key>"
  );

  const { data, error } = await supabase.auth.signInWithPassword({
    email: "user@example.com",
    password: "your-password",
  });

  const accessToken = data.session?.access_token;
  ```

  ```bash cURL theme={null}
  curl -X POST "https://<project-ref>.supabase.co/auth/v1/token?grant_type=password" \
    -H "apikey: <anon-key>" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "user@example.com",
      "password": "your-password"
    }'
  ```
</CodeGroup>

Then include the token in the `Authorization` header:

```
Authorization: Bearer <session_access_token>
```

Session tokens expire after \~1 hour. The Supabase client handles refresh automatically.

## Making authenticated requests

<CodeGroup>
  ```bash cURL (API key) theme={null}
  curl https://api.helpgenie.ai/v1/genies \
    -H "Authorization: Bearer hg_live_YOUR_KEY"
  ```

  ```typescript TypeScript (ApiService) theme={null}
  import { ApiService } from "@/services/api/ApiService";

  // ApiService handles token retrieval automatically
  const genies = await ApiService.invoke({
    resource: "genies",
    action: "all",
  });
  ```

  ```typescript fetch (session token) theme={null}
  const response = await fetch("https://api.helpgenie.ai/v1/genies", {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });

  const result = await response.json();
  ```
</CodeGroup>

## Authentication errors

| Error code           | HTTP status | Description                                           |
| -------------------- | ----------- | ----------------------------------------------------- |
| `UNAUTHORIZED`       | 401         | No authentication header provided.                    |
| `INVALID_KEY_PREFIX` | 401         | API key doesn't start with `hg_live_` or `hg_admin_`. |
| `KEY_NOT_FOUND`      | 401         | API key not found or has been revoked.                |
| `INVALID_TOKEN`      | 401         | Session token is malformed, expired, or revoked.      |

Example error response:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "No authentication provided. Include an Authorization header with 'Bearer hg_live_YOUR_KEY' or set the X-API-Key header.",
    "status": 401
  }
}
```

See [Error handling](/getting-started/errors) for the complete error reference.


# Error handling
Source: https://docs.helpgenie.ai/getting-started/errors

Understand error response formats and handle API errors in your application

When a request fails, the API returns a JSON response with `success: false` and an `error` object containing a machine-readable code, a human-readable message, and the HTTP status code.

## Error response format

```json theme={null}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404
  }
}
```

<ResponseField name="success" type="boolean">
  Always `false` for error responses.
</ResponseField>

<ResponseField name="error" type="object">
  <ResponseField name="code" type="string">
    A machine-readable error code. Use this for programmatic error handling.
  </ResponseField>

  <ResponseField name="message" type="string">
    A human-readable description of the error. Suitable for logging but not guaranteed to be stable across versions.
  </ResponseField>

  <ResponseField name="status" type="number">
    The HTTP status code associated with the error.
  </ResponseField>
</ResponseField>

## Error codes

| Code                  | HTTP status | Description                                                                                                           |
| --------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `UNAUTHORIZED`        | 401         | No authentication header provided. Include `Authorization: Bearer hg_live_YOUR_KEY` or `X-API-Key: hg_live_YOUR_KEY`. |
| `INVALID_KEY_PREFIX`  | 401         | API key format is invalid. Keys must start with `hg_live_` or `hg_admin_`.                                            |
| `KEY_NOT_FOUND`       | 401         | API key not found or has been revoked. Generate a new key at Settings → API Keys.                                     |
| `INVALID_TOKEN`       | 401         | Session token is malformed, expired, or has been revoked. Refresh the session and retry.                              |
| `FORBIDDEN`           | 403         | The authenticated user does not have permission to access this resource or perform this action.                       |
| `NOT_FOUND`           | 404         | The requested resource does not exist or the user does not have access to it.                                         |
| `VALIDATION_ERROR`    | 400         | The request body is missing required fields, contains invalid data, or has malformed JSON.                            |
| `AGENT_NOT_FOUND`     | 404         | The specified genie (agent) does not exist or the user does not have access to it.                                    |
| `INVALID_ACTION`      | 400         | The `action` value is not supported for the specified resource.                                                       |
| `RATE_LIMIT_EXCEEDED` | 429         | Too many requests. API keys are limited to 60 requests/minute. Wait before retrying.                                  |
| `INTERNAL_ERROR`      | 500         | An unexpected server error occurred. If this persists, contact support.                                               |

## Handling errors in code

### With ApiService

`ApiService.invoke()` throws on error. Wrap calls in try/catch:

```typescript theme={null}
import { ApiService } from "@/services/api/ApiService";

try {
  const genie = await ApiService.invoke({
    resource: "genies",
    action: "get",
    id: "abc-123",
  });
} catch (error) {
  console.error("API request failed:", error.message);
}
```

### With fetch

When using `fetch` directly, check the `success` field in the response body:

```typescript theme={null}
const response = await fetch(
  "https://api.helpgenie.ai/v1",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer hg_live_YOUR_KEY`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      resource: "genies",
      action: "get",
      id: "abc-123",
    }),
  }
);

const result = await response.json();

if (!result.success) {
  const { code, message, status } = result.error;

  switch (code) {
    case "UNAUTHORIZED":
    case "INVALID_TOKEN":
      // Refresh the auth session and retry
      break;
    case "NOT_FOUND":
    case "AGENT_NOT_FOUND":
      // Resource does not exist or is not accessible
      break;
    case "VALIDATION_ERROR":
      // Fix the request body and retry
      break;
    case "RATE_LIMIT_EXCEEDED":
      // Wait and retry with exponential backoff
      break;
    default:
      console.error(`API error [${code}]: ${message}`);
  }
}
```

### With TanStack Query

When using TanStack Query (React Query), errors propagate through the query's `error` state:

```typescript theme={null}
import { useQuery } from "@tanstack/react-query";
import { ApiService } from "@/services/api/ApiService";

const { data, error, isError } = useQuery({
  queryKey: ["genies"],
  queryFn: () =>
    ApiService.invoke({
      resource: "genies",
      action: "all",
    }),
});

if (isError) {
  console.error("Failed to load genies:", error.message);
}
```

## Retry strategy

<Tip>
  **Use exponential backoff for `429` and `500` errors.** These are the only error codes worth retrying automatically. Authentication errors (`401`) require a token refresh, and validation errors (`400`, `403`, `404`) indicate a problem with the request itself.

  A recommended approach:

  1. Start with a **1-second** delay after the first failure.
  2. **Double** the delay after each subsequent failure (1s, 2s, 4s, 8s...).
  3. Add **random jitter** (0-500ms) to avoid thundering herd problems.
  4. Give up after **3-4 retries** and surface the error to the user.
</Tip>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const delay = (ms: number) =>
    new Promise((resolve) => setTimeout(resolve, ms));

  async function fetchWithRetry<T>(
    fn: () => Promise<T>,
    maxRetries = 3
  ): Promise<T> {
    for (let attempt = 0; attempt <= maxRetries; attempt++) {
      try {
        return await fn();
      } catch (error: any) {
        const code = error?.code ?? error?.error?.code;
        const isRetryable =
          code === "RATE_LIMIT_EXCEEDED" || code === "INTERNAL_ERROR";

        if (!isRetryable || attempt === maxRetries) {
          throw error;
        }

        const backoff = 1000 * Math.pow(2, attempt);
        const jitter = Math.random() * 500;
        await delay(backoff + jitter);
      }
    }
    throw new Error("Max retries exceeded");
  }

  // Usage
  const genies = await fetchWithRetry(() =>
    ApiService.invoke({ resource: "genies", action: "all" })
  );
  ```

  ```bash cURL (with retry loop) theme={null}
  #!/bin/bash
  # Retry with exponential backoff for 429 and 500 errors

  URL="https://api.helpgenie.ai/v1"
  TOKEN="hg_live_YOUR_KEY"
  MAX_RETRIES=3

  for attempt in $(seq 0 $MAX_RETRIES); do
    RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$URL" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"resource": "genies", "action": "all"}')

    HTTP_CODE=$(echo "$RESPONSE" | tail -1)
    BODY=$(echo "$RESPONSE" | sed '$d')

    if [ "$HTTP_CODE" -ne 429 ] && [ "$HTTP_CODE" -ne 500 ]; then
      echo "$BODY"
      exit 0
    fi

    if [ "$attempt" -eq "$MAX_RETRIES" ]; then
      echo "Max retries exceeded. Last response: $BODY" >&2
      exit 1
    fi

    DELAY=$(( (1 << attempt) ))
    echo "Retrying in ${DELAY}s (attempt $((attempt + 1))/$MAX_RETRIES)..." >&2
    sleep "$DELAY"
  done
  ```
</CodeGroup>

## Common error scenarios

<AccordionGroup>
  <Accordion title="401 — Missing or expired token">
    The most common cause is an expired access token. Supabase tokens typically expire after 1 hour. Use `supabase.auth.refreshSession()` to get a new token.

    ```typescript theme={null}
    const { data, error } = await supabase.auth.refreshSession();
    const newToken = data.session?.access_token;
    ```
  </Accordion>

  <Accordion title="400 — Invalid action for resource">
    Each resource supports a specific set of actions. Sending an unsupported action (e.g., `action: "archive"` to a resource that does not support it) returns `INVALID_ACTION`. Check the resource's documentation in the [API reference](/api-reference/introduction) for supported actions.
  </Accordion>

  <Accordion title="403 — Insufficient permissions">
    The user's role does not allow the requested operation. For example, a `consumer` user cannot create genies. See [Introduction](/getting-started/introduction) for the role permission matrix.
  </Accordion>

  <Accordion title="404 — Resource not found">
    The record either does not exist or belongs to another user. Non-admin users can only access their own resources. Verify the `id` value and confirm the user has access.
  </Accordion>

  <Accordion title="429 — Rate limit exceeded">
    Back off and retry with exponential delay. A simple implementation:

    ```typescript theme={null}
    const delay = (ms: number) =>
      new Promise((resolve) => setTimeout(resolve, ms));

    async function retryWithBackoff<T>(
      fn: () => Promise<T>,
      maxRetries = 3
    ): Promise<T> {
      for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
          return await fn();
        } catch (error: any) {
          if (
            error?.code === "RATE_LIMIT_EXCEEDED" &&
            attempt < maxRetries - 1
          ) {
            await delay(1000 * Math.pow(2, attempt));
            continue;
          }
          throw error;
        }
      }
      throw new Error("Max retries exceeded");
    }
    ```
  </Accordion>
</AccordionGroup>


# Introduction
Source: https://docs.helpgenie.ai/getting-started/introduction

Learn about the HelpGenie API architecture and available resources

## Two kinds of documentation

This site covers two audiences:

* **API reference** — for developers integrating with HelpGenie programmatically. Continue reading below for the API architecture, then see [Authentication](/getting-started/authentication) and [Making requests](/getting-started/making-requests).
* **Product guides** — for users configuring and operating HelpGenie Voice, Mail, Outbound, and Sync from the dashboard. Start with the [Help Genie Voice guide](/voice-guide/my-genies-list).

## Single endpoint architecture

The HelpGenie API is served from a single endpoint. Every request is a `POST` to the same URL:

```
POST https://api.helpgenie.ai/v1
```

Instead of traditional REST routing with different URL paths per resource, HelpGenie uses a **resource/action pattern** in the request body. The `resource` field selects which entity to operate on, and the `action` field determines what to do.

```json theme={null}
{
  "resource": "genies",
  "action": "get",
  "id": "abc-123"
}
```

The API also supports standard REST-style HTTP method routing as an alternative. See [Making requests](/getting-started/making-requests) for details on both approaches.

## Request and response format

Every request body follows this structure:

<ParamField type="string">
  The resource to operate on (e.g. `genies`, `knowledge-base`, `leads`).
</ParamField>

<ParamField type="string">
  The operation to perform (e.g. `get`, `all`, `list`, `create`, `update`, `delete`).
</ParamField>

<ParamField type="string">
  The identifier of a specific record. Required for `get`, `update`, and `delete` actions.
</ParamField>

<ParamField type="object">
  The payload for `create` and `update` actions. Contents vary by resource.
</ParamField>

Every response uses a consistent envelope:

```json theme={null}
{
  "success": true,
  "data": { ... }
}
```

On failure, the response includes an `error` object instead:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404
  }
}
```

See [Error handling](/getting-started/errors) for the full list of error codes.

## Available resources

The API exposes 13 resources organized into six groups.

### Agents

| Resource        | Description                                                                           |
| --------------- | ------------------------------------------------------------------------------------- |
| `genies`        | Voice AI agents. Create, configure, update, and delete genies.                        |
| `genie-groups`  | Groups for organizing genies. Supports ordering and agent counts.                     |
| `conversations` | Conversation records. Sync from the voice agent system, analyze, and manage metadata. |

### Knowledge

| Resource           | Description                                                                          |
| ------------------ | ------------------------------------------------------------------------------------ |
| `knowledge-base`   | Documents that provide context to agents. Supports PDFs, websites, videos, and text. |
| `document-folders` | Folders for organizing knowledge base documents.                                     |

### Voice

| Resource            | Description                                                                            |
| ------------------- | -------------------------------------------------------------------------------------- |
| `voices`            | Voice discovery and favorites. Browse popular voices, track usage, and save favorites. |
| `voice-collections` | Custom collections for organizing saved voices.                                        |

### CRM

| Resource     | Description                                                                       |
| ------------ | --------------------------------------------------------------------------------- |
| `leads`      | Leads captured during agent conversations. Includes lifecycle tracking and stats. |
| `lead-notes` | Notes attached to leads. Supports pinning and ordering.                           |

### Marketplace

| Resource      | Description                                                                        |
| ------------- | ---------------------------------------------------------------------------------- |
| `marketplace` | Agent templates available in the marketplace. Browse, create, and manage listings. |

### Platform

| Resource     | Description                                            |
| ------------ | ------------------------------------------------------ |
| `profiles`   | User profiles and account data.                        |
| `teams`      | Teams with member management and invitation workflows. |
| `activities` | Activity event log for auditing and tracking.          |

## Authorization and roles

Access is controlled by three user roles:

| Role             | Access level                                                                            |
| ---------------- | --------------------------------------------------------------------------------------- |
| `internal_admin` | Full access to all resources across all users. Can impersonate other users.             |
| `standard_user`  | Access to their own resources only. Can create and manage agents, documents, and leads. |
| `consumer`       | Limited read-only access to assigned agents.                                            |

## Next steps

<Columns>
  <Card title="Authentication" icon="lock" href="/getting-started/authentication">
    Get a Bearer token and authenticate your first request.
  </Card>

  <Card title="Making requests" icon="code" href="/getting-started/making-requests">
    Learn about request patterns, list vs all, and admin mode.
  </Card>

  <Card title="Help Genie Voice guide" icon="microphone" href="/voice-guide/my-genies-list">
    Not building an integration? Learn to use the Help Genie Voice product.
  </Card>
</Columns>


# Making requests
Source: https://docs.helpgenie.ai/getting-started/making-requests

Learn how to structure API requests, understand response formats, and use common patterns

## Request methods

The HelpGenie API supports two ways to make requests: the `ApiService.invoke()` pattern (recommended for TypeScript projects) and direct HTTP requests.

### ApiService.invoke() (recommended)

The `ApiService` class handles authentication, request formatting, and response unwrapping automatically:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { ApiService } from "@/services/api/ApiService";

  const genies = await ApiService.invoke({
    resource: "genies",
    action: "all",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "genies",
      "action": "all"
    }'
  ```
</CodeGroup>

The `invoke` method accepts an options object with these fields:

<ParamField type="string">
  The API resource to target. Must be one of the 13 supported resources.
</ParamField>

<ParamField type="string">
  The action to perform. Common actions: `all`, `list`, `get`, `create`, `update`, `delete`.
</ParamField>

<ParamField type="string | number">
  The record identifier. Required for `get`, `update`, and `delete` actions.
</ParamField>

<ParamField type="object">
  The request payload. Used with `create` and `update` actions. Structure varies by resource.
</ParamField>

### Direct HTTP requests

You can also call the Edge Function directly. The API accepts both a body-based resource/action pattern and standard REST-style HTTP methods.

<Tabs>
  <Tab title="Body-based (POST)">
    Send the resource, action, and data in the request body:

    ```bash theme={null}
    curl -X POST https://api.helpgenie.ai/v1 \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{
        "resource": "genies",
        "action": "get",
        "id": "abc-123"
      }'
    ```
  </Tab>

  <Tab title="REST-style">
    Use HTTP methods and URL paths:

    ```bash theme={null}
    # GET all genies
    GET /v1/genies

    # GET a single genie
    GET /v1/genies/abc-123

    # GET list (compact format)
    GET /v1/genies/list

    # CREATE a genie
    POST /v1/genies

    # UPDATE a genie
    PATCH /v1/genies/abc-123

    # DELETE a genie
    DELETE /v1/genies/abc-123
    ```
  </Tab>
</Tabs>

## Common actions

Most resources support a standard set of actions. Some resources add custom actions specific to their domain.

| Action   | Description                                                   | Requires `id` | Requires `data` |
| -------- | ------------------------------------------------------------- | ------------- | --------------- |
| `all`    | Fetch all records with full details and relations             | No            | No              |
| `list`   | Fetch a compact list of records (for dropdowns and selectors) | No            | No              |
| `get`    | Fetch a single record by ID                                   | Yes           | No              |
| `create` | Create a new record                                           | No            | Yes             |
| `update` | Update an existing record                                     | Yes           | Yes             |
| `delete` | Delete a record                                               | Yes           | No              |

### `list` vs `all`

The API distinguishes between two fetching actions:

* **`all`** returns full records with related data (joins, counts, nested objects). Use this when you need complete information.
* **`list`** returns minimal records with only key fields (typically `id` and `name`). Use this for populating dropdowns, selectors, or anywhere you need a lightweight list.

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Full records with all relations — use for detail views
  const allGenies = await ApiService.invoke({
    resource: "genies",
    action: "all",
  });

  // Compact records — use for dropdowns and selectors
  const genieList = await ApiService.invoke({
    resource: "genies",
    action: "list",
  });
  ```

  ```bash cURL theme={null}
  # Full records with all relations
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{"resource": "genies", "action": "all"}'

  # Compact records for dropdowns
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{"resource": "genies", "action": "list"}'
  ```
</CodeGroup>

<Note>
  **Pagination differs between `all` and `list`.**

  * The `all` action on **genies** uses **cursor-based** pagination. The response includes `nextCursor` and `hasMore` fields. Pass `cursor` in the request data to fetch the next page.
  * Most other resources use **offset-based** pagination. The response includes `count`, and you control paging with `limit` and `offset` in the request data.
</Note>

## Request examples

### Create a resource

<CodeGroup>
  ```typescript TypeScript theme={null}
  const newGenie = await ApiService.invoke({
    resource: "genies",
    action: "create",
    data: {
      genieName: "Support Agent",
      voiceId: "voice-abc-123",
      firstMessage: "Hi, how can I help you today?",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "genies",
      "action": "create",
      "data": {
        "genieName": "Support Agent",
        "voiceId": "voice-abc-123",
        "firstMessage": "Hi, how can I help you today?"
      }
    }'
  ```
</CodeGroup>

### Get a single resource

<CodeGroup>
  ```typescript TypeScript theme={null}
  const genie = await ApiService.invoke({
    resource: "genies",
    action: "get",
    id: "abc-123",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "genies",
      "action": "get",
      "id": "abc-123"
    }'
  ```
</CodeGroup>

### Update a resource

<CodeGroup>
  ```typescript TypeScript theme={null}
  const updated = await ApiService.invoke({
    resource: "genies",
    action: "update",
    id: "abc-123",
    data: {
      genieName: "Updated Agent Name",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "genies",
      "action": "update",
      "id": "abc-123",
      "data": {
        "genieName": "Updated Agent Name"
      }
    }'
  ```
</CodeGroup>

### Delete a resource

<CodeGroup>
  ```typescript TypeScript theme={null}
  await ApiService.invoke({
    resource: "genies",
    action: "delete",
    id: "abc-123",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "genies",
      "action": "delete",
      "id": "abc-123"
    }'
  ```
</CodeGroup>

## Response structure

All responses use a consistent envelope:

### Success response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "abc-123",
    "genieName": "Support Agent",
    "voiceId": "voice-abc-123",
    "created_at": "2025-01-15T10:30:00Z"
  }
}
```

For list and all actions, `data` is an array:

```json theme={null}
{
  "success": true,
  "data": [
    { "id": "abc-123", "genieName": "Support Agent" },
    { "id": "def-456", "genieName": "Sales Agent" }
  ]
}
```

<Note>
  When using `ApiService.invoke()`, the response is automatically unwrapped. You receive the `data` value directly, not the full envelope.
</Note>

### Error response

```json theme={null}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404
  }
}
```

See [Error handling](/getting-started/errors) for all error codes.

## Admin mode and impersonation

Users with the `internal_admin` role can operate on behalf of other users by including an `impersonatedUserId` in the request data. This is used for provisioning trial agents, bulk operations, and testing.

```typescript theme={null}
const trialGenie = await ApiService.invoke({
  resource: "genies",
  action: "create",
  data: {
    genieName: "Trial Genie",
    voiceId: "voice-123",
    impersonatedUserId: "user-456",
  },
});
```

<Warning>
  Impersonation is only available to `internal_admin` users. Non-admin requests that include `impersonatedUserId` will be ignored or rejected.
</Warning>

## Query parameters

When using REST-style HTTP requests, query parameters are automatically extracted and passed to handlers:

```bash theme={null}
GET /v1/genies?limit=30&cursor=abc123
```

When using the body-based approach, include pagination and filter parameters in the `data` object:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const genies = await ApiService.invoke({
    resource: "genies",
    action: "all",
    data: {
      limit: 30,
      cursor: "abc123",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "genies",
      "action": "all",
      "data": {
        "limit": 30,
        "cursor": "abc123"
      }
    }'
  ```
</CodeGroup>


# Developer Standards MCP
Source: https://docs.helpgenie.ai/getting-started/mcp-server

Add the Help Genie MCP server to your AI coding tools to share team coding rules, patterns, and standards automatically.

The Help Genie MCP server exposes your team's coding standards to MCP-compatible AI tools like Claude Code and Codex CLI. Once installed, your AI assistant can pull the right conventions directly during development — without you having to repeat them.

**Endpoint:** `https://mcp.helpgenie.ai/api/mcp`

## Automated setup (recommended)

Run the setup script in your project root:

```bash theme={null}
npx hg-standards-mcp-setup
```

This registers the server with Claude Code and/or Codex CLI, and automatically adds usage instructions to your project's `CLAUDE.md` / `AGENTS.md`.

## Manual setup

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http hg-standards https://mcp.helpgenie.ai/api/mcp
    ```
  </Tab>

  <Tab title="Codex CLI">
    Add to your Codex configuration:

    ```toml theme={null}
    [mcp_servers.hg-standards]
    url = "https://mcp.helpgenie.ai/api/mcp"
    ```
  </Tab>
</Tabs>

For other MCP-compatible clients, see the [Model Context Protocol docs](https://modelcontextprotocol.io).

<Note>
  Installing the server alone does not guarantee your AI agent will call it. After setup, add an instruction to your project's `CLAUDE.md` (or `~/.claude/CLAUDE.md`) telling the agent to use the MCP server during development. The automated setup above handles this for you.
</Note>


# HelpGenie API
Source: https://docs.helpgenie.ai/index

Build with the HelpGenie voice AI platform API

The HelpGenie API gives you programmatic access to voice agents, knowledge bases, conversations, leads, and more. All 13 resources are available through a single endpoint using a consistent request and response format.

## Get started

<Columns>
  <Card title="Introduction" icon="book" href="/getting-started/introduction">
    Learn about the API architecture, the resource/action pattern, and available resources.
  </Card>

  <Card title="Authentication" icon="lock" href="/getting-started/authentication">
    Obtain a Bearer token from Supabase Auth and authenticate your requests.
  </Card>

  <Card title="Making requests" icon="code" href="/getting-started/making-requests">
    Understand request structure, response envelopes, and common patterns.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/getting-started/errors">
    Handle errors with standardized error codes and response formats.
  </Card>
</Columns>

## API reference

<Columns>
  <Card title="Agents" icon="robot" href="/api-reference/genies">
    Create and manage voice agents (genies), groups, and conversations.
  </Card>

  <Card title="Knowledge" icon="book-open" href="/api-reference/knowledge-base">
    Manage documents and organize them into folders for your agents.
  </Card>

  <Card title="Voice" icon="microphone" href="/api-reference/voices">
    Browse voices, manage favorites, and organize voice collections.
  </Card>

  <Card title="CRM" icon="address-book" href="/api-reference/leads">
    Track leads captured by your agents and attach notes.
  </Card>

  <Card title="Marketplace" icon="store" href="/api-reference/marketplace">
    Browse and manage marketplace agent templates.
  </Card>

  <Card title="Platform" icon="gear" href="/api-reference/profiles">
    Manage user profiles, teams, and activity logs.
  </Card>
</Columns>

## Quick reference

Every resource and its available actions at a glance:

| Resource          | Actions                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------- |
| Genies            | `list` `all` `get` `create` `update` `delete` `reorder`                                           |
| Knowledge Base    | `list` `get` `create` `update` `delete` `sync-with-agents` `attach` `detach` `replace`            |
| Document Folders  | `all` `list` `get` `create` `update` `delete` `reorder` `counts`                                  |
| Genie Groups      | `list` `get` `create` `update` `delete` `reorder` `counts` `sync`                                 |
| Conversations     | `list` `get` `sync` `analyze` `update` `delete`                                                   |
| Voices            | `favorites` `popular` `recent` `add-favorite` `remove-favorite` `track-usage`                     |
| Voice Collections | `all` `get` `create` `update` `delete`                                                            |
| Leads             | `stats` `all` `list` `get` `create` `update` `delete`                                             |
| Lead Notes        | `list` `get` `create` `update` `delete` `togglePin` `pinned`                                      |
| Marketplace       | `list` `all` `get` `create` `update` `delete` `categories` `stats`                                |
| Profiles          | `all` `list` `get` `create` `update` `delete`                                                     |
| Teams             | `get` `create` `update` `delete` `members` `invite` `invitations` `cancel-invite` `remove-member` |
| Activities        | `all` `get` `create`                                                                              |

<Info>
  All requests are `POST` to a single endpoint with the `resource` and `action` specified in the request body. See [Making requests](/getting-started/making-requests) for full details.
</Info>


# Calendar
Source: https://docs.helpgenie.ai/mail-guide/calendar

See your meetings alongside your mail

Your calendar syncs automatically once your email account is connected, so meetings show up right alongside your mail.

## Viewing your calendar

Open the **Calendar** tab to see upcoming events. Click any event for details — time, attendees, and location or meeting link.

<Frame>
  <img alt="Calendar view" />
</Frame>

## Responding to meeting invites

Meeting invites and reschedule requests can appear in the Genie feed — approve or decline them there, and your calendar updates automatically to match your response.


# Compose, Reply & Attachments
Source: https://docs.helpgenie.ai/mail-guide/compose-and-send

Write new email, reply, and attach files

Write new email, reply or forward existing threads, and attach files.

## Writing mail

Click **Compose** to start a new email, or use **Reply**, **Reply All**, or **Forward** from an open thread.

<Frame>
  <img alt="Compose window" />
</Frame>

Add recipients and your message, attach any files you need, then click **Send**.

## Editing a suggested reply

When editing an AI-suggested reply from the Genie feed, your changes replace the suggested text — only what you send goes out.

## Your sending style

Set your preferred tone and reply style once in **Settings → Composing** so both manual drafts and suggested replies sound like you.

<Frame>
  <img alt="Composing settings page" />
</Frame>


# Connecting Your Email Account
Source: https://docs.helpgenie.ai/mail-guide/connecting-accounts

Link Gmail or Outlook to get started

Connecting your email account is the first step — mail and calendar can't sync until an account is linked.

## Steps

1. Go to **Settings → Accounts**.
2. Click **Connect Account** and choose Gmail or Outlook.

<Frame>
  <img alt="Accounts settings page with Connect Account button" />
</Frame>

3. You'll be taken to your provider's official sign-in page. Sign in and approve the requested permissions there — your password is never seen or stored by us.
4. Once approved, you're returned to the app and syncing begins automatically.

## Managing connected accounts

You can connect multiple accounts, and disconnect any of them at any time from **Settings → Accounts**. Disconnecting stops sync and removes access, but never deletes mail from your provider.


# The Genie Feed
Source: https://docs.helpgenie.ai/mail-guide/genie-feed

Let AI triage your inbox and approve what it gets right

The Genie feed is your home screen. Instead of scrolling a plain inbox, incoming email is sorted into a feed of suggested actions — replies to approve, meetings to confirm, and messages worth your attention.

## How it works

Each card in the feed shows one suggested action along with a short explanation of why it was suggested.

<Frame>
  <img alt="Genie feed showing a few decision cards" />
</Frame>

* **Approve** to send the suggested reply or action as-is
* **Edit** to tweak the wording before sending
* **Dismiss** if the suggestion isn't right

## Customize how it behaves

Open **Settings → Brain** to describe, in plain language, how you want your mail handled: tone, what should be sent automatically, and what should always wait for your review.

<Frame>
  <img alt="Brain settings page with instructions text area" />
</Frame>

You can turn on automatic sending for suggestions the system is highly confident about, while everything else still waits for your approval.


# Inbox, Threads & Search
Source: https://docs.helpgenie.ai/mail-guide/inbox-and-search

Browse, organize, and search your mail directly

Alongside the Genie feed, you have a traditional inbox for browsing and managing mail directly.

## Reading mail

Open the **Inbox** tab to see your conversations, newest first. Click any conversation to read the full thread.

<Frame>
  <img alt="Inbox list view" />
</Frame>

## Organizing mail

* **Archive** a thread to clear it from your inbox while keeping it searchable
* **Snooze** a thread to have it reappear at a time you choose
* **Trash** a thread to delete it (recoverable from Trash)

## Searching

Use **Search** to find messages by sender, subject, or content across your entire mailbox.

<Frame>
  <img alt="Search results" />
</Frame>


# Help Genie Mail
Source: https://docs.helpgenie.ai/mail-guide/introduction

Bring Gmail and Outlook together in one place, with AI handling triage, replies, and follow-ups in the background.

Help Genie Mail brings Gmail and Outlook together into one place, then handles triage, replies, and follow-ups in the background. The idea is a quiet inbox — the only messages you see are the ones that actually need you.

* New here? Start with [Getting Started](/mail-guide/onboarding) and [Connecting Your Email Account](/mail-guide/connecting-accounts).
* Want AI to triage your inbox? See [The Genie Feed](/mail-guide/genie-feed).
* Prefer to browse mail directly? See [Inbox, Threads & Search](/mail-guide/inbox-and-search) and [Compose, Reply & Attachments](/mail-guide/compose-and-send).
* Meetings show up alongside your mail — see [Calendar](/mail-guide/calendar).
* Configure accounts, AI behavior, and notifications in [Settings](/mail-guide/settings).


# Getting Started
Source: https://docs.helpgenie.ai/mail-guide/onboarding

Your first-run walkthrough

The first time you sign in, you'll see a short walkthrough that introduces the Genie feed and helps you connect your email account.

<Frame>
  <img alt="Welcome / onboarding screen" />
</Frame>

Follow the steps to connect your account and set a few initial preferences. Once you finish or skip it, you can revisit anything it covered later from **Settings**.


# Settings
Source: https://docs.helpgenie.ai/mail-guide/settings

Configure accounts, notifications, and behavior

Settings is where you configure how the app looks, behaves, and notifies you.

<Frame>
  <img alt="Settings hub page" />
</Frame>

* **Accounts** — connect, view, or disconnect email accounts
* **Brain** — edit your AI triage instructions
* **Genies** — manage multiple triage profiles, if you use more than one
* **Composing** — set your default tone and reply style
* **Notifications** — choose when and how you're notified
* **Timezone** — set the timezone used for scheduling across the app


# Campaigns
Source: https://docs.helpgenie.ai/outbound-guide/campaigns

Create, launch, and monitor outbound calling campaigns

A campaign is a batch of outbound calls with a shared purpose — for example, "confirm
next week's appointments" or "follow up on last month's support tickets." Each campaign
has its own audience, script, and schedule.

## Creating a campaign

From your Genie's **Campaigns** tab, choose **New Campaign**:

1. **Audience** — upload a contact list or pick an existing one. Every contact must
   already have a relationship with your business.
2. **Script overlay** — set the greeting, the questions to capture during the call, and
   where to transfer the contact if they ask for a person.
3. **Schedule** — call now, or schedule a window. Outbound respects contact time-zone
   and quiet-hours rules automatically.

<Frame>
  <img alt="Campaign creation wizard, script overlay step" />
</Frame>

## Compliance checklist

Before a campaign can move from **Draft** to **Scheduled**, you must confirm a short
checklist confirming the audience has an existing relationship with your business and
has been checked against opt-outs.

<Frame>
  <img alt="Compliance checklist modal before scheduling" />
</Frame>

## Monitoring a live campaign

Once launched, the **Calls** tab shows each call's status in real time — ringing,
connected, completed, or blocked. A blocked call means the contact was already on a
do-not-call or opt-out list.

## After a campaign finishes

Each completed call has a disposition (e.g. "reached — resolved," "no answer," "opted
out") and a summary, viewable from the campaign's **Calls** tab or rolled up in
**Reports**.


# Getting Started with Outbound
Source: https://docs.helpgenie.ai/outbound-guide/getting-started

Set up your first outbound calling campaign

Outbound lets your Genie call your existing customers on your behalf — to follow up on
a support ticket, confirm an appointment, or check in after a purchase. It is not a
cold-calling or sales-prospecting tool: every call assumes you already have a
relationship with the person being called.

## Before you start

You'll need:

* A Genie already set up with a voice and knowledge base.
* A list of contacts to call, or an integration that triggers calls automatically.
* A phone number assigned to your workspace for outbound calls.

## Your first campaign

1. Open your Genie and go to **Campaigns**.
2. Choose **New Campaign** and pick the audience — upload a contact list or connect an
   existing segment.

<Frame>
  <img alt="New Campaign screen with the audience upload/selection step" />
</Frame>

3. Write (or accept the suggested) opening greeting and the information you want
   collected during the call.
4. Review the compliance checklist — every campaign must pass this before it can be
   scheduled.
5. Schedule or launch, and watch calls happen live from the **Calls** tab.

<Frame>
  <img alt="Live Calls tab showing in-progress call statuses" />
</Frame>

## What a contact experiences

When a call connects, the contact first hears a short recorded message confirming the
call may be recorded, in line with the rules of their region. After that, your Genie
starts the conversation normally. If the contact asks to be transferred to a person, or
asks not to be called again, Outbound handles both automatically.


# Help Genie Outbound
Source: https://docs.helpgenie.ai/outbound-guide/introduction

Let your Genie place real phone calls and run calling campaigns end to end.

Help Genie Outbound lets your Genie place real phone calls and run calling campaigns end to end. Your Genie dials, talks, listens, and then reports back with a transcript, a recommended next step, and the contact updated in your CRM.

Outbound is not a cold-calling or sales-prospecting tool — every call assumes you already have a relationship with the person being called, such as a follow-up on a support ticket, an appointment confirmation, or a check-in after a purchase.

* New to Outbound? Start with [Getting Started](/outbound-guide/getting-started).
* Ready to launch calls? See [Campaigns](/outbound-guide/campaigns).


# Activity & Replay
Source: https://docs.helpgenie.ai/sync-guide/activity-and-replay

See everything your genie has done, and retry anything that failed.

The Activity log is your record of everything that's happened across knowledge syncs, live lookups, and post-call actions — one place to confirm things are working, and to catch anything that isn't.

## What you'll see

Every run shows what kind of activity it was, when it happened, whether it succeeded, and how long it took. Failed runs show why they failed in plain language, so you usually don't need to dig further to know what to fix.

<Frame>
  <img alt="Execution Log page with a mix of successful and failed runs" />
</Frame>

## Replaying a failed run

If something fails — a knowledge sync couldn't reach its source, a post-call action's connection had expired — you can fix the underlying issue and hit **Replay** to run it again immediately, without waiting for its next scheduled run.

<Frame>
  <img alt="Failed run's detail view with the Replay button" />
</Frame>

## Per-genie activity

Each genie also has its own **Activity** tab, showing a timeline of that specific genie's calls and syncs, so you can see the full story of one genie's day without filtering through everyone else's.

## Call detail

Click into any call to see it broken down by Before, During, and After — what knowledge it drew from, what it looked up mid-call, and what happened once it ended. This is the fastest way to understand exactly what a genie did on a specific call.

<Frame>
  <img alt="Call Detail page showing the before/during/after timeline for one call" />
</Frame>


# Capabilities
Source: https://docs.helpgenie.ai/sync-guide/capabilities

Give your genie the ability to look things up and take action, live, during a call.

Capabilities are what your genie can *do* mid-call — not just what it already knows, but what it can go check or act on while a customer is on the line. Think "what's the status of my order," or "do you have this in a size 10," answered with the real, current answer instead of a guess.

## How a capability works

Each capability is built around one of your [connections](/sync-guide/connections) — a capability to check order status might use your order management system; a capability to look up account details might use your CRM. You describe what the capability should do, and your genie learns to reach for it exactly when a caller's question calls for it.

<Frame>
  <img alt="Capabilities editor showing a capability's configuration form" />
</Frame>

## Building one

1. Choose the connection the capability should use.
2. Describe what it does in plain language — this is what helps your genie recognize when to use it.
3. Test it before turning it on, so you can see exactly what your genie will receive back.
4. Assign it to one or more genies.

## Speed matters

Capabilities run live, while someone is on the phone, so they're built to respond quickly. If a capability is consistently slow, you'll see that reflected in its activity — worth checking the system it depends on.

## Turning capabilities on and off

Every genie's **During** tab lists its assigned capabilities with a simple on/off switch — no need to rebuild anything to temporarily disable one.


# Connections
Source: https://docs.helpgenie.ai/sync-guide/connections

Link Sync to the tools and systems your business already uses.

A connection is a link between your genie and one of your business's systems — the thing that lets your genie read from or act on your real data, instead of working in isolation.

There are two ways to connect something.

## One-click connect

For popular tools — HubSpot, Slack, Salesforce, Google Calendar, Pipedrive, and hundreds more — connecting takes one click. You'll be asked to sign in to that tool and approve access, the same way you'd connect any app to your Google account. No credentials to copy, nothing to configure by hand.

<Frame>
  <img alt="Connections page showing the &#x22;Browse 700+ apps&#x22; catalog grid" />
</Frame>

## Connect your own system

If you use something more specific to your business — an internal database, a custom API — you can connect it directly by providing its address and credentials. Sync checks the connection as soon as you save it, so you'll know right away if something's misconfigured.

<Frame>
  <img alt="Custom connection form with endpoint and credential fields" />
</Frame>

## Managing connections

From the Connections page you can see everything you're connected to, check its status at a glance, and reconnect anything that's fallen out of sync (for example, if a login expires). Disconnecting a system removes access immediately — any capabilities or actions that depended on it will need a new connection before they'll work again.

<Frame>
  <img alt="Connection card showing a &#x22;needs reconnecting&#x22; status badge" />
</Frame>

## Your credentials are safe

However you connect — one-click or custom — your credentials are stored securely and never shown in plain text after the initial setup.


# FAQ & Troubleshooting
Source: https://docs.helpgenie.ai/sync-guide/faq-troubleshooting

Answers to common questions and fixes for common issues.

## A connection shows as disconnected — what do I do?

Reconnect it from the Connections page. This usually happens when a login has expired on the other side (for example, a tool revoked access, or a password changed). Reconnecting takes the same one click as the original setup.

## A knowledge sync isn't picking up my latest changes

Check the sync's last-run status first — if it failed, the reason is usually shown right there (a moved spreadsheet, an unreachable API). If it succeeded but the content still looks stale, confirm the sync's schedule matches how often your source actually changes; a sync that runs nightly won't reflect a change you made five minutes ago.

## A capability is timing out during calls

Live lookups run on a tight time budget so callers aren't left waiting. If a capability is timing out, the system it depends on is likely responding too slowly — check that connection's health, and consider whether the capability is trying to do too much in one step.

## Can I turn a capability off without deleting it?

Yes. Every genie's During tab has an on/off switch per capability — turning one off doesn't remove its configuration, so you can turn it back on later exactly as it was.

## Where do I see if a post-call action actually ran?

The [Activity log](/sync-guide/activity-and-replay), either globally or from a specific genie's Activity tab — every action's run is recorded there, with a Replay option if it failed.

## Do I need to know how to code to use Sync?

No. Everything described in this guide — connections, knowledge syncs, capabilities, post-call actions — is configured through the visual interface. Some advanced features (like the raw webhook option for post-call actions) are there for teams that want to go further, but they're entirely optional.


# Getting Started
Source: https://docs.helpgenie.ai/sync-guide/getting-started

Complete the setup wizard to get your first genie running in Sync.

Getting your first genie set up in Sync takes a few minutes.

## 1. Your Voice account is linked automatically

Sync works alongside Help Genie Voice — the two are connected automatically, with no API key or manual setup required. As soon as you sign in to Sync, your Voice genies appear ready to configure.

## 2. Walk through the setup wizard

The first time you sign in, Sync walks you through five short steps:

1. **Welcome** — a quick tour of the before/during/after model.
2. **Connect** — one-click connect to common tools like HubSpot, Slack, and Google Calendar, or browse the full catalog of supported apps.
3. **Pick a genie** — choose which of your Voice genies you're configuring.
4. **Capabilities** — turn on the abilities you want your genie to have (for example, checking order status, or posting a recap to Slack after each call).
5. **Launch** — a quick recap of everything you've turned on, then you're in.

<Frame>
  <img alt="Setup wizard's Capabilities step showing the toggle list" />
</Frame>

## 3. You're set up — now what?

From here, everything lives on your genie's page, organized by Before, During, and After tabs. Start with whichever part matters most to you:

* Want your genie to know more? Start with [Knowledge Sync](/sync-guide/knowledge-sync).
* Want it to look things up live? Start with [Capabilities](/sync-guide/capabilities).
* Want something to happen after every call? Start with [Post-Call Actions](/sync-guide/post-call-actions).

You can always revisit connections, capabilities, and knowledge sources later — nothing in the wizard is a one-time decision.


# What is Help Genie Sync?
Source: https://docs.helpgenie.ai/sync-guide/introduction

The lifecycle model behind every genie — before, during, and after the call.

Help Genie Sync is what keeps your genie sharp. It's the layer that connects your genie to the rest of your business — your knowledge, your tools, your systems — so every call feels like it's being handled by someone who already knows your business inside and out.

Everything in Sync is organized around one simple idea: the life of a call.

## Before the call

Your genie needs to walk into every conversation already knowing your business — your policies, your prices, your product catalog, whatever your customers ask about. Sync keeps that knowledge fresh automatically, so your genie is never caught quoting last month's information.

See [Knowledge Sync](/sync-guide/knowledge-sync) for how this works.

## During the call

Some questions can't be answered from memory alone — "what's the status of my order," "do you have this in stock." For those, your genie can reach out mid-call and check, live, then answer with the real answer instead of a guess.

See [Capabilities](/sync-guide/capabilities) for how this works.

## After the call

Once a call ends, there's often follow-up work: logging a note in your CRM, posting a summary to your team, sending a recap email. Sync can trigger all of that automatically the moment the call wraps up, so nothing falls through the cracks.

See [Post-Call Actions](/sync-guide/post-call-actions) for how this works.

## Who this is for

Anyone responsible for keeping their genie useful and accurate day to day — no engineering background required. Everything in Sync is configured through a visual interface. If you can use a spreadsheet, you can configure a genie.

<Frame>
  <img alt="Genies home page showing the roster of genie cards with Before/During/After equipment counts" />
</Frame>


# Knowledge Sync
Source: https://docs.helpgenie.ai/sync-guide/knowledge-sync

Keep your genie's knowledge current, automatically.

Knowledge Sync is how your genie stays up to date on your business — your policies, prices, products, and anything else customers ask about — without anyone having to manually retrain it.

## What you can sync from

* **A spreadsheet** — point Sync at a Google Sheet and every row becomes something your genie can answer from.
* **An API** — pull structured data straight from your own systems.
* **A web page** — hand Sync a URL and it reads the page into your genie's knowledge.
* **A custom database or app** — anything you've already connected (see [Connections](/sync-guide/connections)) can be used as a knowledge source.

<Frame>
  <img alt="Knowledge Sync editor showing the source type picker" />
</Frame>

## Keeping it fresh

Each knowledge sync runs on a schedule you choose — every hour, every day, or whatever cadence matches how often your information actually changes. When a sync runs, your genie's knowledge updates automatically; there's nothing to re-upload and nothing to retrain.

<Frame>
  <img alt="Schedule picker on a knowledge sync configuration" />
</Frame>

## Checking on a sync

Every sync's page shows you when it last ran, whether it succeeded, and how much information it brought in. If a sync fails — say, a spreadsheet was moved or an API went down — you'll see that clearly, and can fix the source and try again without waiting for the next scheduled run.

## Before tab, per genie

You can manage all your knowledge syncs in one place, or from a specific genie's **Before** tab if you only want to see what's feeding that genie.


# Post-Call Actions
Source: https://docs.helpgenie.ai/sync-guide/post-call-actions

Automatically follow up the moment a call ends.

Post-call actions are things that happen automatically right after a call wraps up — the follow-up work a human agent would otherwise have to do by hand.

## Common actions

* **Log a note in your CRM** — HubSpot, Salesforce, or similar, so every call leaves a trail.
* **Post a summary to your team** — a Slack message with the call recap and outcome.
* **Add a calendar event** — for calls that end in a scheduled follow-up.
* **Send a recap email** — a friendly summary sent straight to the caller.
* **Trigger a webhook** — for anything else your own systems need to react to.

<Frame>
  <img alt="After tab showing the list of configured post-call actions" />
</Frame>

## Setting one up

Post-call actions live on your genie's **After** tab. Each one is tied to a [connection](/sync-guide/connections) and runs automatically once a call ends — nothing to trigger manually.

<Frame>
  <img alt="Post-call action configuration form" />
</Frame>

## For developers on your team

If your team wants to build something more custom on top of a call ending, the After tab also exposes a raw webhook URL and the exact shape of the data it sends — useful if you're wiring call outcomes into a system Sync doesn't support out of the box yet.

## Checking what happened

Every post-call action's run shows up in your [Activity log](/sync-guide/activity-and-replay), so you can always confirm a CRM note actually landed, or a Slack message actually sent.


# Account Branding
Source: https://docs.helpgenie.ai/voice-guide/account-branding

Set the default logo, colors, and styling applied to every new Genie you create.

Account Branding lets you define one set of brand defaults — a logo, colors, gradient, and widget styling — that is automatically applied to **every newly created Genie**. Set it once and your Genies stay on-brand without configuring each one by hand.

You'll find it under **Genie Hub → Account Branding** (`/genie-hub/account-branding`).

<Frame>
  <img alt="Account Branding" />
</Frame>

<Note>
  Account Branding only affects Genies created **after** you save it. Existing Genies keep their current branding and are never changed. You can always adjust an individual Genie's branding on its own settings page.
</Note>

## Before you start

Account Branding is tied to your team. If you haven't created a team yet, the page will prompt you to do so first — head to **Account Settings** to create your team, then return here.

When branding is saved, an **Active** badge appears next to the page title and the status panel confirms that new Genies will use your settings.

## The page at a glance

The page is split into two columns:

* **Branding Settings** (left) — the editor where you configure everything, organized into four tabs: **Images**, **Colors**, **QR Code**, and **Web Embed**.
* **Preview** (right) — a live preview of how a new Genie's avatar will look, an **Active Colors** summary, and a status card showing whether Account Branding is currently active.

Changes you make in the editor update the preview instantly, but nothing is saved until you select **Save Branding**.

## Images

### Brand logo

Upload your company logo or brand image. This single image is reused everywhere:

* As your Genie's avatar throughout the app
* In the center of generated QR codes
* In web embed widgets
* In marketing materials

When you upload a logo, its colors are **automatically extracted and applied** across all your branding — primary and secondary colors, QR code, and web embed header — so everything matches your image out of the box. Background removal and square-padding options are available during upload to help your logo sit cleanly inside the round avatar.

### Generate a logo

Don't have a logo ready? Use the built-in **Smart Logo Generator** to create one:

<Steps>
  <Step title="Enter a name">
    Type the brand or business name for the logo. This is the only required field.
  </Step>

  <Step title="Choose a style">
    Pick from **Modern** (default), **Bold**, **Friendly**, **Tech**, **Luxury**, or **Classic**.
  </Step>

  <Step title="Add optional detail">
    Optionally add a short **Description** (e.g. "A plumbing business in Austin specializing in residential repairs") and select an **Industry** to sharpen the result.
  </Step>

  <Step title="Generate and apply">
    Select **Generate Logo**. When it's ready, choose **Use This Logo** to apply it — or **Regenerate** to try again. Applying a generated logo also extracts and applies its colors.
  </Step>
</Steps>

## Colors

The Colors tab controls the color scheme used for your Genie avatar, buttons, and highlights across the app.

* **Primary Color** — the main brand color. Sets the avatar, buttons, and accents.
* **Secondary Color** — the second color used when a gradient is enabled.
* **Background Color** — used for the web embed widget background.
* **Text Color** — used for text in the web embed widget.

You can set each color with the color picker or by typing a hex value (e.g. `#4E9CFF`).

If you uploaded a logo, an extracted **color palette** appears at the top — click any swatch to assign it as your primary or secondary color. Select **Reset to Extracted** at any time to snap the colors back to those pulled from your logo.

### Gradient

Turn on **Enable Gradient** to blend your primary and secondary colors on the avatar. When enabled, a **Gradient Angle** slider (0°–360°, default 135°) controls the direction of the blend.

A live avatar preview lets you check the result in **Idle**, **Speaking**, and **Listening** states.

## QR Code

Style the QR codes generated for your Genies:

* **Foreground Color** — the color of the QR code pattern.
* **Background Color** — the color behind the pattern.

Your logo (if uploaded) appears in the center of the code, and a live preview shows the finished result.

## Web Embed

Control the look of the chat widget embedded on your website:

* **Border Radius** — how rounded the widget corners are (0–50).
* **Shadow Effect** — toggle a drop shadow on or off.
* **Font Family** — **System Default**, **Arial**, **Georgia**, **Inter**, or **Roboto**.
* **Button Style** — **Rounded**, **Square**, or **Pill**.
* **Header Color** — an optional color for the widget header. Leave it blank to use your primary color.

## Saving

Select **Save Branding** to store your settings. From that point on, every new Genie you create starts with this logo, colors, gradient, and styling already applied.

When creating or editing an individual Genie, you can also select **Apply Account Branding** to pull these defaults into that Genie at any time.


# Account Settings
Source: https://docs.helpgenie.ai/voice-guide/account-settings

Manage your profile, team, security, billing, phone numbers, API keys, and troubleshooting tools from one place.

Account Settings is the hub for everything tied to your account — your personal profile, your team, sign-in security, billing and subscription, purchased calls and phone numbers, developer API keys, and browser troubleshooting tools.

You'll find it under **Genie Hub → Account Settings** (`/genie-hub/account-settings`). The page is organized into five tabs: **Profile**, **Security**, **Billing**, **Developers**, and **Troubleshooting**.

<Frame>
  <img alt="Account Settings" />
</Frame>

## Profile

The Profile tab covers your personal details and your team.

### Your profile

The **Profile** card shows your account basics:

* **Email Address** — the email you signed up with. It's shown for reference and can't be changed here. The date you joined appears beneath it as *Member since*.
* **Profile Avatar** — upload an image to use as your personal avatar.
* **Full Name** — your display name.
* **Preferred Language** — pick your language from the list.
* **Timezone** — choose from the list of common timezones, or select **Custom** to type your own (e.g. `UTC+5:30`). Switch back with **Use List**.

Select **Save Profile** to store your avatar, name, language, and timezone.

#### Extra details

Select **Edit Extra Details** to open a side panel with additional optional information: phone number and country code, address, city, state/province, postal code, country, date of birth, company name, and job title. If a billing currency is set on your account, it's shown here for reference and can't be edited. Select **Save Details** to store these, or **Cancel** to discard them.

### Team Management

The **Team Management** card lets you group people under a single account so they can share Genies.

<Note>
  Team members can view and edit every Genie created under the account. Only the team **owner** can change team settings or manage members.
</Note>

If you don't have a team yet:

* **Business accounts** see a **Create Team** button. Enter a **Team Name** (required) and an optional **Brand Name**, then select **Create Team** — you become the team owner.
* Other account types see a note that team creation is available for business users only.

If you already have a team, its **Team Name** and **Brand Name** are shown. As the owner, select **Edit** to change them and **Save Changes** to apply. Members who aren't the owner see the details read-only.

### Team Members

The **Team Members** card lists everyone on your team along with their role. Pending invitations appear here too, marked **Invited**.

As the team owner you can:

<Steps>
  <Step title="Invite a member">
    Enter an email address under **Invite New Member** and select **Send Invite**. The person receives an email inviting them to join your team.
  </Step>

  <Step title="Remove a member or cancel an invite">
    Select the **✕** next to a person to remove them from the team, or to cancel a pending invitation. The team owner can't be removed.
  </Step>
</Steps>

## Security

The Security tab handles your sign-in password and gives you access to policy documents.

### Change Password

Enter a **New Password** and **Confirm New Password**, then select **Update Password**. Passwords must be at least 6 characters and the two entries must match. This change takes effect immediately.

### Privacy & Policies

This card links to HelpGenie's policy and compliance documents, which open in a new tab:

* Privacy Statement
* Information Security Policy
* Internal Privacy Policy
* Responsible AI Use Policy
* Security & Infrastructure Overview
* Data Processing Addendum
* Identity & Access Management Policy
* Sub-Processor List

## Billing

The Billing tab shows your subscription, extra call purchases, and active phone numbers.

### Subscription

If you're on the **Free Plan**, this card summarizes what an upgrade unlocks and offers a **View Pricing Plans** link.

On a paid subscription, you'll see:

* **Status** — Active, Trialing, Canceled, or Past Due.
* **Available Genies** — your total Genie allowance, broken down as *1 free + plan Genies + extra Genies*. Select the **+** to purchase more: choose a new quantity and select **Upgrade**.
* **Key dates** — trial end date (if trialing), your next billing date (or end date), and the date your subscription started.
* A **status message** confirming your subscription is in good standing, or prompting you to choose a plan if it isn't.

Two actions sit at the top of the card:

* **Manage Billing** — opens the secure billing portal where you can update payment details, invoices, and plan.
* **Sync Billing Data** — refreshes your subscription details if they look incorrect or out of date. There's a short cooldown between syncs; the button tells you how long to wait if it's temporarily unavailable.

### Call Purchases

Extra calls raise a Genie's **daily call limit** beyond what your plan includes.

<Note>
  You need a payment method on file to buy extra calls. Without one, the **Add** button is disabled. Extra calls are billed every month and renew on your billing cycle date.
</Note>

The card lists your existing purchases with the Genie, quantity, status, and date. To buy more:

<Steps>
  <Step title="Open the purchase panel">
    Select **Add**.
  </Step>

  <Step title="Choose a Genie">
    Select the Genie the calls apply to. Its current daily call limit is shown.
  </Step>

  <Step title="Set the quantity">
    Enter how many calls to purchase. The panel shows the per-call price, the total cost, and the new daily limit before you confirm.
  </Step>

  <Step title="Confirm">
    Select **Purchase**. You're charged using your existing payment method.
  </Step>
</Steps>

To reduce a purchase, select the **–** next to it, enter how many calls to remove (leave it empty or `0` to cancel all of them), and select **Reduce Calls**. Reductions apply on your next billing cycle.

### Active Phone Numbers

This card lists the phone numbers assigned to your Genies, showing the Genie name, the number, and its type.

Select **Release** next to a number to give it up. You'll be asked to confirm first.

<Warning>
  Releasing a phone number can't be undone — you won't get the same number back.
</Warning>

If you have any previously released numbers, they appear under a collapsible **Cancelled Phone Numbers** section. New numbers are provisioned from an individual Genie's settings, not here.

## Developers

The Developers tab manages **API keys** used to authenticate requests to the HelpGenie API.

The tab lists your active keys — each showing its name, a masked prefix (`hg_live_…`), when it was created, and when it was last used. Revoked keys appear in a separate **Revoked** list for reference.

### Create an API key

<Steps>
  <Step title="Open the create panel">
    Select **Create API Key**.
  </Step>

  <Step title="Name the key">
    Give it a descriptive name (e.g. "Production", "Development") so you can recognize it later, then select **Create API Key**.
  </Step>

  <Step title="Copy the key">
    Your full key is shown once, along with a usage example. Copy it now and store it somewhere safe.
  </Step>
</Steps>

<Warning>
  A key's full value is shown only at creation. You won't be able to see it again — if you lose it, revoke the key and create a new one.
</Warning>

### Revoke an API key

Select **Revoke** next to an active key and confirm. Any requests using that key stop working immediately.

## Troubleshooting

The Troubleshooting tab provides tools to clear locally stored data when the web app is misbehaving.

* **Clear Browser Cache** — clears cached app files stored by your browser. A good first step for display glitches or stale content.
* **Clear App Data** — removes locally cached analysis, conversation, and transcript data, while leaving your sign-in and other settings in place.
* **Clear All Storage** — wipes everything the app has stored locally. Use this as a last resort; you may need to sign in again afterward.

<Note>
  These tools only affect data stored in your current browser. They don't change your account, Genies, or any data saved to your account.
</Note>


# Activation
Source: https://docs.helpgenie.ai/voice-guide/activation

Turn any Genie into a day-one launch kit — printer files, app-install assets, a tailored presentation, an email-signature widget, QR codes, and launch copy.

Activation is where a finished Genie becomes something a customer can launch. Every Genie has an **activation pack** that combines physical production files, digital sharing assets, mobile-app onboarding, and customer-ready messaging in one place.

You'll find it under **Genie Hub → Activation** (`/genie-hub/activation`). You can also jump straight to a Genie's pack from that Genie's workspace, from a conversation's side panel, or right after finishing setup.

<Frame>
  <img alt="Activation pack" />
</Frame>

## The Activation list

The list shows every Genie you have, each as a card with its avatar, name, and a status line — either **Phone connected** or **Activation pack ready**. Use the search box to filter by name; the count next to **Your Genies** shows how many match.

Select any card to open that Genie's activation pack. If the Genie doesn't have a pack yet, one is created automatically with sensible defaults the first time you open it — see [Creating an activation pack](/activation-create).

<Note>
  If you don't have any Genies yet, the list shows an empty state instead. Choose **Go to My Genies** to create your first Genie — its activation pack is generated for you as part of setup.
</Note>

## The fastest day-one workflow

At the top of a pack, **How to activate** links to the four highest-value moves:

1. Download the complete launch pack.
2. Get people onto the mobile app.
3. Share the tailored activation presentation.
4. Add the email-signature widget.

For a new physical rollout, start with **Download everything**, review the starter print run, then either send the production files to your preferred printer or download the ZIP and hand it over yourself.

## Download the complete launch pack

**Download everything** builds and checks the full pack before downloading it. If an expected file cannot be created or fetched, the download reports the problem rather than silently producing a partial pack.

The ZIP is organised for handoff rather than as a folder of loose files:

* **Send to printer** — the sticker PDF, A4 poster pack, and A4 mobile-app install poster.
* **Placement inspiration** — the lookbook showing where stickers, signs, cards, and QR placements can work. It is a reference guide, not manufacturing artwork.
* **Digital launch assets** — QR images, social artwork, the app-poster image, the email-signature HTML, and the website embed snippet.
* **Promo copy** — the available launch email, social, SMS, team, and website-banner drafts.
* **START-HERE**, **PRINT-JOB**, and **MANIFEST** — the launch order, starter quantities, production notes, expected files, and the exact files included.

The recommended starter run is **100 QR stickers, 20 posters, and 10 app-install posters**. These are starting quantities, not a required order.

<Note>
  The ZIP and printer-email workflow prepare and hand off a production job. Help Genie does not quote, manufacture, or ship printed materials. Your printer should confirm the final proof, stock, finish, price, lead time, and delivery address before going to print.
</Note>

## Get people onto the mobile app

The mobile activation section is intentionally near the top of the pack. Its smart link uses an install-first experience on iPhone and Android, with **Continue on the web** as a fallback. Desktop visitors can open the Genie on the web or send the install link to a phone.

You can:

* copy the install link;
* use the App Store and Google Play links;
* download the branded app poster as PNG or 300-DPI A4 PDF;
* share or print the install QR code.

The app poster, email-signature widget, and activation pack all use the canonical public Help Genie link, so artwork prepared from a preview or staging screen does not permanently embed a temporary hostname.

## Send the production job to a printer

**Order printed packs** opens a draft printer handoff. A fresh draft starts with the recommended sticker and app-poster quantities and adds one poster design as the 20-poster starter run.

Use **Add designs to print** to choose another poster or add the generated sticker and app-poster files. Change quantities in the order, enter the printer's email, and add notes such as the stock, finish, deadline, and delivery address. **Send to Printer** opens a final review sheet and emails verified production links to files owned by this activation pack. Replies go to the person who sent the order.

When you confirm the handoff, Help Genie freezes every production file into a versioned printer snapshot so an edit in progress, a stale browser tab, or a second simultaneous send cannot substitute different quantities or files. Editing any pack input used by the artwork retires the open draft automatically, so the next printer handoff is rebuilt from the updated files.

The poster and app-poster production files are rendered at A4 print resolution. The sticker file is rendered at its configured physical size. Always approve the printer's proof before the full run.

## Share the tailored activation presentation

The activation presentation is built specifically for this Genie — it uses its public description, purpose, audience, welcome message, and business branding, and its example outcomes change with the Genie's actual role.

Use **Preview** to open it, then copy the link for customers or the team. A visible **Get the app** control stays available throughout the presentation. Portal packs use portal-appropriate wording rather than presenting the portal as a single Genie.

## Add the email-signature widget

The email-signature section shows a live preview of a compact branded card with two clear actions: talk to the Genie and get it on a phone. It uses email-safe table markup and inline styles.

Choose **Copy signature** to place both rich HTML and a plain-text fallback on the clipboard. Paste it into the signature editor in Gmail, Outlook, or Apple Mail. You can also download the `.html` source when an IT team manages signatures centrally.

If a mail client strips the formatting, paste the plain-text version or use the installation hint shown in the section. No scripts or interactive embeds are used inside email signatures.

## Activate customers by email

**Activate customers** accepts a pasted list or CSV of up to 300 customers and sends one combined onboarding email per recipient with the presentation, app-install link, and a working talk link.

Duplicates are removed; malformed addresses are shown and must be corrected before sending, and a list over the limit is rejected rather than silently shortened.

Every campaign has a durable recipient ledger. A retry sends only addresses that are definitely known not to have been sent; confirmed deliveries and ambiguous provider outcomes stay locked against automatic duplicates. If you intentionally start a new campaign while delivery is unknown, Help Genie warns that doing so may duplicate an email.

<Note>
  This customer launch does not grant dashboard access. Use **Manage access** when a specific person needs to sign in and administer the Genie.
</Note>

## Placement ideas and posters

The **Lookbook** is a placement-inspiration guide showing ways the Genie can appear in the real world. Download it for the customer or use it to decide what to produce, but send the individual sticker, poster, or app-poster production file to the printer.

The **Posters** gallery contains the standalone poster designs. Download the full poster PDF from the gallery or add a selected design directly to the printer handoff.

## Promote

The **Promote** section gives you ready-to-paste launch copy written from your Genie's name, description, and link. There's a card for each of:

* **Launch Email** — announce your Genie to customers and prospects (includes a subject line).
* **Social Post** — a post to share with your network.
* **Customer SMS** — a short text for existing customers.
* **Team Announcement** — an internal note so staff know how it works (includes a subject line).
* **Website Banner** — short copy for a homepage strip or popup.

Each card has a **tone** switch — **Professional**, **Friendly**, or **Punchy**. Switching tone drafts that version the first time you pick it. Use **Copy** to grab the text, or the refresh button to draft a fresh version. Each card shows when it was last generated.

## Pack settings

Expand **Pack settings** to change the pack name, description, contact channels, materials, sticker options, QR treatment, logo, phone-number visibility, and tagline. Each block has its own **Edit** toggle; your changes are held until you choose **Save Changes** in the header.

Saving an input that changes artwork clears the old generated-asset cache. Saving the name, target, or description also clears affected launch copy. The next build regenerates those snapshots, so a previous logo, URL, sticker size, or tagline is not quietly sent to print.

For a walkthrough of these same settings while first building a pack, see [Creating an activation pack](/activation-create).

## Deleting a pack

Open **Pack settings**, choose **Delete this pack**, and confirm in the side sheet. Deleting the activation pack does not delete the underlying Genie. You can open Activation later to create a fresh pack.


# Creating an activation pack
Source: https://docs.helpgenie.ai/voice-guide/activation-create

How activation packs are created — automatically for each Genie, or built by hand for a Genie or portal with the channels and materials you choose.

An activation pack is the bundle of shareable assets that gets a Genie in front of people — a smart link, QR codes, print materials, an email signature, an embed snippet, and launch copy. There are two ways a pack comes into being: it's created for you automatically, or you build one yourself. Once it exists, you manage it from its detail page — see [Activation](/activation).

## The automatic pack (recommended)

Most packs create themselves. The first time you open Activation for a Genie that doesn't have a pack yet — by selecting it in the [Activation list](/activation), or using the **Activation pack** link from the Genie's workspace or a conversation — a pack is generated automatically with sensible defaults, and its assets are pre-built so the page is ready when you arrive.

A brief loading screen ("Creating your activation pack…", then "Building your pack…") appears while this happens, then you land straight on the finished pack. New Genies also get a default pack as part of setup, so in most cases there's nothing to create — you just open it.

The default pack promotes the web link to your Genie and generates a QR sticker, email signature, and social card. You can adjust any of this later in **Pack settings**.

## Building a pack by hand

To create a pack yourself — for example a second pack for the same Genie, or a pack for a **portal** — go to **Create Activation Pack** (`/genie-hub/activation/new`). The page walks top to bottom, and the **Create Pack** button stays disabled until the required pieces are filled in. A hint under the button always tells you what's still missing.

### Target & Details

First, choose **what you'd like to activate**:

* **Genie** — pick one of your active Genies.
* **Portal** — pick one of your portals.

Then give the pack a **name** (required — e.g. "Main Marketing Materials") and an optional **description** describing what it's for.

### Contact Channels

Choose how customers can reach your Genie or portal. At least one channel is required:

* **Web Widget** — a link to your Genie's web page.
* **Phone Call** — a direct number to call the Genie.
* **SMS** — a text message to start a conversation.
* **WhatsApp** — a WhatsApp chat with the Genie.

### Materials

Pick which assets to generate. At least one material is required. They're grouped as:

* **Physical Materials** — **QR Code Sticker**: weather-resistant stickers for vehicles, equipment, and storefronts.
* **Digital Assets** — **Email Signature** (an HTML signature block with your Genie link) and **Social Card** (a shareable image for social profiles).

Every pack also includes the activation presentation and app-install route. The **complete bundle** adds an app poster, poster pack, placement lookbook, website embed snippet, and generated launch copy.

### Customization

Fine-tune how the materials look:

* **Tagline** — the line shown on stickers and marketing materials (e.g. "Scan to talk to our assistant").
* **Sticker Size** — 2"×2", 3"×3", or 4"×4". Shown only when the QR Code Sticker material is selected.
* **Sticker shape and QR treatment** — adjust the sticker outline and QR code style.
* **Include logo in QR codes** — on by default.
* **Include phone number on materials** — on by default.
* **Social card preference** — choose which social card style to generate.

### Creating the pack

When a target, name, at least one channel, and at least one material are all set, **Create Pack** turns on. Selecting it creates the pack and builds its assets right away, then takes you to the finished pack. Launch copy for the **Promote** section drafts in the background and appears shortly after.

<Note>
  You can change every one of these settings after the pack exists. Open the pack, expand **Pack settings**, edit any block, and choose **Save Changes**. The one thing that's fixed is the target — a pack stays tied to the Genie or portal it was created for.
</Note>

## What happens next

However a pack is created, you end up on its detail page with everything ready to share — the activation presentation, QR codes, the smart link, launch copy, and a one-click **Download .zip** of the whole bundle. See [Activation](/activation) for a full tour of the pack and how to use each part.

<Note>
  The print order is a secure handoff to your chosen printer, not a Help Genie manufacturing service. Confirm the proof, materials, price, lead time, and delivery details with the printer before production.
</Note>


# Genie Trust Center
Source: https://docs.helpgenie.ai/voice-guide/brand-integrity

Stress-test a Genie's behaviour across the conversations it might face — run full audits, targeted evaluations, and manual tests, then review the results and export a report.

The Genie Trust Center is where you check how a Genie behaves across the awkward, tricky, and off-script conversations it might face in the real world. You run audits and tests against a Genie, then review scenario-by-scenario transcripts to see where it held up and where it slipped.

You'll find it under **Genie Hub → Genie Trust Center** (`/genie-hub/brand-integrity`).

<Frame>
  <img alt="Genie Trust Center" />
</Frame>

<Note>
  You need at least one Genie before you can run anything here. If you have none, the page points you to **My Genies** to create one first.
</Note>

## The main page

At the top you'll see the **Genie Trust Center** heading and four actions:

* **Run Full Audit** — the primary action. Runs a comprehensive, tailored audit against the selected Genie (see [Running a full audit](#running-a-full-audit)). You must pick a Genie first — until you do, the button is disabled and hovering it shows a "Select a genie first" hint.
* **Custom Test** — opens the evaluation builder, where you pick exactly which tests to run (see [Running a custom evaluation](#running-a-custom-evaluation)).
* **Manual** — start a live voice conversation with a Genie and save the transcript for review (see [Manual tests](#manual-tests)).
* **Export** — download a spreadsheet report for the selected Genie (see [Exporting results](#exporting-results)). Also requires a Genie to be selected.

There's also a **Preview new live audit experience** link near the heading — see [The live audit experience (preview)](#the-live-audit-experience-preview).

### Filters

Below the header, a filter panel controls which results you see:

* **Genie** — pick a single Genie to focus on, or choose **All Genies**. Selecting a Genie here is also what enables **Run Full Audit** and **Export**.
* **Status** — **All Tests**, **Passed**, or **Needs Review**.
* **Date Range** — **Last 7 days**, **Last 30 days**, **Last 90 days**, or **All time**.

### Results list

Past runs appear as a list, newest first, with more loading as you scroll. A count at the bottom shows how many of the total runs you're viewing. Each card shows the Genie's avatar and name, when the run happened, and a status summary that depends on the run type:

* **Full Audit** runs show a **Full Audit** tag and, once finished, an overall **Score out of 100** and an **Audit Complete** badge.
* **Evaluation** runs show a passed/needs-review count and a badge — **All Passed**, or **\<n> Need Review**.
* **Manual** runs show a **Manual Test** badge and a microphone icon.
* Runs still in progress show a **Running** (or **Audit Running**) badge. Full audits also show a **Watch Live** button that opens the [live audit experience](#the-live-audit-experience-preview).
* Runs that didn't finish show a **Failed** badge.

Select any card to expand it. Inside you'll see:

* For full audits, an **Audit summary** with the overall score and a short written narrative.
* For runs that failed, a card explaining what went wrong.
* The individual results, grouped by category (for example, **Competitor Handling**, **Pricing & Objections**, **Jailbreak Resistance**). Each result shows whether it **Passed** or **Needs Review** — or, for manual tests, a **View Transcript** link with the number of conversation turns.

Select an individual result to open a drawer with the full details and transcript for that scenario.

## Running a full audit

Select a Genie in the filters, then choose **Run Full Audit**. A panel opens that's tailored to that Genie.

* The audit reads the Genie's own setup — its prompt, knowledge base, goal, and tone — and generates bespoke scenarios written specifically for it.
* Scenarios are spread across **11 review areas**: Competitor Handling, Pricing & Objections, Off-Topic Deflection, Data Security, Service Accuracy, Professional Boundaries, Edge Cases, Brand Voice Consistency, Jailbreak Resistance, Hallucination Resistance, and Lead Capture & Escalation.
* Each area starts with a recommended number of scenarios, which you can adjust from **1 to 20** per area. The panel shows the running total it will generate.

Every scenario runs as a real conversation with your Genie. When it finishes you get an overall score, a breakdown by area, and the exact transcripts where the Genie slipped.

Select **Run Full Audit** to start. Audits typically take **3–5 minutes** and continue in the background — you can close the panel or leave the Genie Trust Center entirely, and you'll be notified when results are ready. While it runs, the panel shows two phases: **Tailoring your audit** (writing the scenarios) and **Running scenarios** (holding the conversations). A progress card also appears at the top of the results list.

From the running panel you can select **Watch live** to follow the audit conversation-by-conversation in the [live audit experience](#the-live-audit-experience-preview).

When the audit completes, the panel shows:

* A **score out of 100** with a plain-language band: **Strong** (85+), **Worth a look** (65–84), or **Needs attention** (below 65).
* The number of scenarios tested.
* **View Detailed Results**, which jumps you to that run in the list so you can read every transcript.

<Note>
  A branded, one-click **Executive PDF** is marked "Coming soon" in the completed view. For now, use **View Detailed Results** or the [Export](#exporting-results) option for a shareable report.
</Note>

If an audit can't finish, the panel shows the reason and a **Try the audit again** option.

## Running a custom evaluation

**Custom Test** opens the **Run Evaluation** builder, where you choose exactly which checks to run rather than a full audit.

1. **Select a Genie.** The Genie must be set up for voice conversations; if it isn't, you'll see a note and won't be able to run the evaluation.
2. A summary card shows how many tests are selected out of the **maximum of 30 per run**. Choose **Customize** to open the test picker.
3. Pick from three groups:
   * **Core Tests** — the standard set of behaviour checks, all selected by default.
   * **Recommended** — tests tailored to this specific Genie. Use **Regenerate** to refresh them.
   * **My Custom Tests** — tests you've written yourself. Use **Add Test** to create a new one (see [Creating a custom test](#creating-a-custom-test)).
4. Use **Select All** / **Deselect All** to adjust quickly. If you go over 30, the builder tells you how many to remove.

Select **Run** to start. The evaluation runs in the background, and you can navigate away — progress shows in the results list and the sidebar.

### Creating a custom test

From the evaluation builder, **Add Test** opens a form to write your own scenario:

* **Test Name** (required) — for example, "Return Policy Questions".
* **Description** — a short summary of what the test checks.
* **Test Prompts** — the messages a simulated user will send to your Genie. Add at least one; add more to cover different phrasings of the same scenario.

Select **Create Test** to save it. It's added to your custom tests and selected for the current run. Your custom test then simulates a conversation using those prompts and evaluates how the Genie handles it.

## Manual tests

**Manual** opens a live voice test. Pick a Genie that's set up for voice, then select the avatar (or **Start Conversation**) to begin talking to it directly — a real, spoken conversation, up to 20 minutes long.

When you're done, select the avatar again or **End & Save Conversation**. The transcript is saved to the Genie Trust Center as a **Manual Test** run, where you can reopen it later. If the conversation drops unexpectedly, it's saved automatically so you don't lose it.

## Exporting results

Select a Genie in the filters, then choose **Export** to download a spreadsheet report for that Genie over the current date range. You can choose what to include:

* **Include Conversation Transcripts** — full turn-by-turn logs for each test.
* **Include Criteria Breakdown** — detailed pass/fail results for each evaluation criterion, with reasoning.

The report contains an executive summary, a list of test runs, detailed results, an issues analysis, and — depending on your choices — transcripts and a criteria breakdown. Select **Export Excel** to download. If there's no test data in range, you'll be told there's nothing to export.

## The live audit experience (preview)

The **Preview new live audit experience** link opens `/genie-hub/brand-integrity/preview`, a real-time view of an audit running scenario-by-scenario — live conversation tiles, a running scenario count, elapsed time, and a feed of recent verdicts (passed or flagged, with the reason).

<Warning>
  This is an early-access preview and is labelled as such in the product. It may change, and some details may still be evolving — treat it as a look ahead rather than final, stable behaviour. The stable way to run and review audits is the [full audit flow](#running-a-full-audit) described above.
</Warning>

There are two ways you'll land here:

* **Static preview** — opening the link on its own shows a **Preview** badge and a looping sample audit with placeholder data, so you can see how the experience looks. A note on the page confirms it's a static preview.
* **Live view** — opening it from a running full audit's **Watch live** or **Watch Live** button shows a **Live** badge and streams that audit's real scenarios as they complete. When the audit finishes you'll see a completion card with the score and number of flagged scenarios, plus **View full report**; if it stops early, you'll see why.

Use **Back to Trust Center** at any time to return to the main page.


# Email Templates
Source: https://docs.helpgenie.ai/voice-guide/email-templates

Customize the colors, fonts, sections and branding of the report emails your Genies send, and preview them live before saving.

Email Templates lets you control how the report emails your Genies send actually look — the colors, fonts, logo, branding, and which sections appear. Every change shows up instantly in a live preview, so you can match the emails to your brand before anything goes out.

You'll find it under **Genie Hub → Email Templates** (`/genie-hub/email-templates`).

<Frame>
  <img alt="Email Templates" />
</Frame>

## The three report types

At the top of the page, a set of tabs lets you style each kind of report email separately:

* **Conversation Reports** — the analysis email sent after a conversation, with metrics, topics, insights, and the transcript.
* **Customer Reports** — the recap email sent to a customer, with key takeaways, highlights, and useful links.
* **Meeting Recaps** — the follow-up email after a meeting, with attendees, decisions, and an action plan.

Switching tabs loads that report's saved configuration. Each report type keeps its own colors, fonts, sections, and branding.

## Choosing which Genie a template applies to

Just below the header is a **Genie** selector. It controls whose template you're editing:

* **All Genies** (the default) — edits the template used by every Genie that doesn't have its own customization.
* **A specific Genie** — pick a Genie to give it a template of its own, overriding the shared one.

When a specific Genie is selected, the panel can pull in that Genie's own brand colors and logo as suggestions, and the **Button & Layout** options unlock if that Genie has a follow-up link configured.

## The editing layout

The page is split into two columns:

* **On the left**, a stack of collapsible settings sections (Colors, Fonts, Branding, Button & Layout, Report Sections) plus the action buttons.
* **On the right**, a live **Email Preview** showing exactly how the email will look to recipients. It updates as you make changes — scroll inside it to see the full email.

Click any section heading to expand or collapse it.

## Colors

The Colors section controls the palette of the email:

| Color                               | What it affects                                                            |
| ----------------------------------- | -------------------------------------------------------------------------- |
| **Primary Color**                   | The main brand color used for headers and highlights.                      |
| **Accent Color**                    | A secondary color for accents and emphasis.                                |
| **Text Color**                      | The body text color.                                                       |
| **Background Color**                | The email's background.                                                    |
| **Header Color** *(optional)*       | Overrides the header color; falls back to the primary color if left empty. |
| **Section Background** *(optional)* | A light tint behind sections; falls back to a default if left empty.       |

For each color you can use the color picker or type a hex value (for example `#4E9CFF`).

<Info>
  If you've selected a specific Genie that already has brand colors, a **Colors from \[Genie]** panel appears at the top of this section with its brand swatches. Click any swatch to apply it as your Primary color.
</Info>

A couple of helpers keep your emails readable:

* **Contrast protection** — if your text color would be hard to read against the background, it's automatically nudged to keep it legible, and a **⚠ Low contrast** warning appears when needed.
* **Generate a tint** — next to Section Background, the **Primary** and **Accent** buttons generate a soft, light version of that color to use as the section tint.

## Fonts

The Fonts section sets the typeface and heading size:

* **Font** — choose from a curated list of web fonts (Poppins is the default).
* **Heading Size** — the size of headings in pixels, from **16** to **64** (default **32**).

## Branding

The Branding section handles your logo and identity:

* **Apply branding in one click** — when a Genie (or, for **All Genies**, your team) has branding set up, a preview card shows its logo and colors with an **Apply** button that copies those into the template. If there's no branding configured, the card says so.
* **Logo** — shows the current logo. Use **Change Logo** to upload an image or paste a direct image URL (PNG, JPG, or SVG). If you've set a custom logo, **Reset to Default** restores the standard Help Genie logo.
* **Company Name** — the name shown in the email.
* **Applied Colors** — a read-only summary of the current Primary, Accent, Text, and Background colors. Edit these in the Colors section above.

## Button & Layout

These options control the shape and styling of visual elements in the email:

* **Border Radius** — corner rounding for cards, sections, and containers, from **0** to **24** px (default **8**).
* **Button Style** — **Rounded**, **Square**, or **Pill** for the call-to-action button.
* **Enable Shadow** — adds a soft shadow around the main container.
* **Button Text** — the label on the call-to-action button (default *View Full Report*).

<Note>
  Button & Layout options only apply when the selected Genie has a follow-up link (redirect URL) configured. If it doesn't, this section is greyed out with a reminder.
</Note>

## Report Sections

The **Report Sections** editor controls which blocks appear in the email and in what order. Each report type comes with its own built-in blocks — for example a Conversation Report includes metrics, topics, insights, and the transcript.

For every section you can:

* **Reorder** — drag the grip handle to move a section up or down.
* **Show or hide** — use the toggle on the right.
* **Rename** — click the pencil to give a section a custom label (the original name stays visible in brackets for reference).

Built-in sections can be reordered, renamed, and hidden, but not deleted.

### Adding your own sections

Use **Add Section** to insert custom blocks. You can add up to **10** custom sections:

* **Text Section** — a custom heading and body text, with left/center/right alignment.
* **Call to Action** — a clickable button with your own text and URL.
* **Divider** — a horizontal line separator.
* **Image** — an image from an upload or URL, with alt text, a max width, and alignment.

Expand a custom section (the chevron) to edit its content, and use the trash icon to remove it. Once you reach the limit, the Add Section button shows **(max 10)** and is disabled.

## Saving and resetting

At the bottom of the settings column:

* **Save Configuration** — saves the current template for the selected Genie (or for All Genies).
* **Clone from Default** — starts from a fresh copy of the standard template for this report type. If a specific Genie is selected, its branding is applied to the copy automatically. You'll be asked to confirm first.
* **Reset to Defaults** — reverts the settings on screen back to the built-in defaults.

<Note>
  Changes aren't applied to outgoing emails until you select **Save Configuration**. Clone and Reset only change what's shown in the editor and preview.
</Note>


# Genie Access
Source: https://docs.helpgenie.ai/voice-guide/genie-access

Manage who can use each of your private Genies — approve or deny access requests, review current users, set access expiry, and see who's scanned your QR codes.

Genie Access is where you control who can use your private Genies. For each Genie you can review people asking for access, manage the users who already have it, and see a record of QR code scans.

You'll find it under **Genie Hub → Genie Access** (`/genie-hub/genie-access`). Access is managed one Genie at a time, so you start by choosing which Genie to work on.

<Frame>
  <img alt="Genie Access" />
</Frame>

## Choosing a Genie

At the top of the page, use the **Select a Genie** dropdown to pick which Genie's access you want to manage. The list shows every Genie you own or have been given access to; Genies that belong to a teammate are marked with a **Team** label.

Until you pick a Genie, the page prompts you to choose one — everything below is specific to the selected Genie. You can switch Genies at any time to manage another.

Once a Genie is selected, three tabs appear: **Requests**, **Users**, and **QR Codes**. The **Requests** tab shows a small badge with the number of pending requests waiting on you.

## Requests

The **Requests** tab lists people who have asked for access to this Genie. It's split into two groups:

* **Pending requests** — each shows the person's email and the date they asked. For each one you can choose **Approve** (grants them access) or **Deny** (turns them down).
* **Resolved requests** — requests you've already handled, shown dimmed with an **Approved** or **Denied** badge and the date you resolved them.

Approving a request adds that person to the **Users** tab for this Genie. If there are no requests for the selected Genie, the tab tells you so.

## Users

The **Users** tab lists everyone who currently has direct access to this Genie. Each person shows their name (or email) and photo where available. Access granted by a teammate is marked with a **Team** badge.

For each user you can:

* **Set or change an access expiry.** Select the expiry field (it shows **No expiry**, a date, or **Expired**) to pick a date after which their access ends. Save the change with the check button, or discard it with the cancel button. To give someone open-ended access again, clear the date before saving. Expired access is flagged in red.
* **Remove access.** Select **Remove** to revoke this person's access to the Genie.

If no one has been granted direct access yet, the tab lets you know.

<Note>
  Expiry is optional. Leave it as **No expiry** for access that doesn't end on its own, or set a date when you only want to grant temporary access.
</Note>

## QR Codes

The **QR Codes** tab shows a record of every time someone scanned one of this Genie's QR codes to reach it. Each entry lists what was scanned along with details captured at the time, which may include the device, platform, timezone, approximate location, and the email of the person who scanned it, plus the date and time.

Use this to see how your printed and shared QR codes are being used. If no scans have been recorded for the selected Genie, the tab says so.

## Related

* [Activation](/activation) — create the QR codes, smart links, and print materials that people scan and use to reach your Genie.
* [My Genies](/my-genies-list) — where you set a Genie to public or private and manage everything else about it.


# Listener Genies & Reviewing Your Genie
Source: https://docs.helpgenie.ai/voice-guide/genie-setup-listener-form

Set up a meeting-recording Listener Genie, then review and fine-tune any Genie before creating it.

This page covers two parts of setup: the short **Listener Genie** form, and the **Review Your Genie** screen that every setup passes through before a Genie is created.

<Frame>
  <img alt="Listener Genie form" />
</Frame>

## The Listener Genie form

A Listener Genie is a different kind of Genie: instead of answering callers, it sits in on your meetings and video calls, records them, transcribes with speaker labels, and sends you a full recap with action items. Because its job is simpler, it has its own short form rather than the full guided conversation.

You reach it by choosing **Listener Genie** on the [setup start screen](/genie-setup-overview#choosing-how-to-start). The form asks for just a few things:

* **Genie Name** *(required)* — what you'll call it, for example "Sales Call Listener" or "Team Meeting Recorder".
* **What will it record?** *(optional)* — a short description of the meetings it will attend, such as weekly sales calls or client onboarding sessions. If you leave this blank, it defaults to general meeting and call recording.
* **Primary Language** — the main language spoken in your meetings. English, Spanish, French, German, Portuguese, Italian, Dutch, Polish, Hindi, Japanese, Korean, and Chinese (Mandarin) are available.

Select **Create Listener Genie** to finish. You can go **Back** at any time to return to the setup options.

<Note>
  The name is the only required field. Everything else has a sensible default, so you can create a Listener Genie in seconds and refine it later.
</Note>

## Reviewing and creating your Genie

Every other setup path — voice, chat, image, or a [template](/genie-templates) — ends on the **Review Your Genie** screen. This is where you confirm the draft we built and fine-tune it before the Genie is created.

### Two ways to work through it

A toggle in the top-right switches how the review is laid out:

* **Step-by-Step** *(default)* — move through one section at a time with **Continue** and **Back** buttons. A progress bar and stepper at the top show where you are and which steps are done. Required steps are marked, and you can jump back to any completed step to change it.
* **All Fields** — see every section on a single scrolling page, handy for a quick once-over or small edits.

Each required step is checked as you go; if something's missing or invalid, you'll see exactly what to fix before you can continue.

### What you can set

The review is grouped into these sections:

* **Branding & Appearance** — pick an avatar and visual identity. You can choose from example Genies or set your own image and colors.
* **Identity & Purpose** — the Genie's name, category, and use case.
* **Voice & Conversation** — choose the voice your Genie speaks with, write the **first message** callers hear, and pick **personality traits** (Professional, Friendly, Empathetic, Direct, Patient, Energetic). We suggest a voice and pre-select traits based on your description, and a smart suggestion is offered for the first message.
* **Insights & Outcomes** — what the Genie should collect from conversations and who gets notified.
* **Knowledge Base** — attach documents so the Genie can answer from your own content. Documents still being processed are linked automatically once they're ready. See the [Knowledge Base guide](/knowledge-base).
* **Advanced Settings** — finer conversation settings and custom **pronunciations** for names or terms your Genie should say correctly.
* **Ownership** — choose who owns the Genie.
* **Review & Create** — a final summary of everything, with a link back to edit any section.

<Note>
  A setup advisor panel opens alongside the review to suggest improvements as you work. When it applies a change, you can **Undo** and **Redo** it from the buttons at the top.
</Note>

### Creating, discarding, or cancelling

* **Create My Genie** — builds the Genie and takes you to the success screen, where you can test it, view your Genies, or start another. If any documents were still processing, they're attached automatically once ready.
* **Discard** — abandons the draft and returns you to the start. You'll be asked to confirm first.
* **Cancel** *(All Fields mode)* — stops setup and clears your changes after a confirmation.

<Warning>
  Discarding or cancelling a setup can't be undone — your draft configuration is cleared. If you might want it later, resume it instead of discarding. See [Resuming a setup](/genie-setup-overview#resuming-a-setup).
</Warning>


# Setting Up a Genie
Source: https://docs.helpgenie.ai/voice-guide/genie-setup-overview

How the guided setup flow works — pick a starting point, describe your Genie, review the details, and create it.

Genie Setup is the guided flow that turns an idea into a working Genie. You describe what you need, we build a draft configuration for you, and you review and adjust it before your Genie goes live.

You'll reach it under **Genie Hub → Set Up a Genie** (`/user-hub/genie-setup`), from the **New Genie** buttons around the app, or by choosing a ready-made Genie from the [template catalogue](/genie-templates). It opens full-screen so you can focus on the setup.

<Frame>
  <img alt="Genie setup start screen" />
</Frame>

## Choosing how to start

When the flow opens, you pick a starting point:

* **Browse Genies** *(Recommended)* — open the [template catalogue](/genie-templates) and pick a ready-made Genie for the job. It arrives pre-configured, and you land straight in the review step to add your own touches.
* **Type to Set Up** *(Fast)* — set up by chatting. Describe what you need in text and Your Genie builds the configuration as you go.
* **Talk to Set Up** *(Magical)* — speak with the setup guide out loud. It asks a few questions and builds your Genie as you talk. See [Setting up by voice](/genie-setup-voice-flow).
* **Listener Genie** *(New)* — a different kind of Genie that records and transcribes meetings and video calls rather than answering callers. It has its own short form. See [The Listener Genie form](/genie-setup-listener-form).
* **Upload Image Instead** — upload a photo of your business (a storefront, a menu, a flyer) and we extract the details to pre-fill your Genie.

You can leave setup at any time using the **Exit** button in the top-left corner; you'll return to where you came from.

## The three stages

However you start, setup moves through the same three stages.

### 1. Describe

You tell us what the Genie is for — by talking, typing, uploading an image, or starting from a template. The setup guide gathers what it needs: the Genie's purpose, tone, first thing it says, and more.

When you finish a voice or chat conversation, we analyze it to draft your Genie's settings. A status message and loading screen keep you posted while this runs. If anything goes wrong, your conversation is saved safely and you can pick up where you left off — see [Resuming a setup](#resuming-a-setup).

<Note>
  Starting from a template or an uploaded image skips straight to the review stage — the draft is built for you, so there's nothing to describe first.
</Note>

### 2. Review

This is the **Review Your Genie** screen, where you confirm and fine-tune everything before creating the Genie. It's organized into steps you can move through one at a time, or switch to **All Fields** to see everything on one page. See [Reviewing and creating your Genie](/genie-setup-listener-form#reviewing-and-creating-your-genie) for a full walkthrough of this stage.

The steps cover:

* **Branding** — avatar and visual identity.
* **Identity** — name, category, and what the Genie is for.
* **Voice** — the voice it speaks with and its personality traits.
* **Insights** — what it should collect and who gets notified.
* **Knowledge** — documents and resources it can draw on.
* **Advanced** — finer conversation settings and pronunciations.
* **Ownership** — who owns the Genie.
* **Review** — a final summary before you create.

You can jump back to any completed step to make changes, and a setup advisor panel opens alongside to suggest improvements as you go.

### 3. Confirmation

When you select **Create Genie**, we build it and show a success screen. From there you can:

* **Test Your Genie** — opens your new Genie in a live session in a new tab.
* **View My Genies** — go to your [My Genies](/my-genies) list.
* **Create Another** — start a fresh setup.

<Note>
  Creating a Genie requires an active subscription. If your plan isn't active, you'll be taken to My Genies to review your options.
</Note>

## Resuming a setup

Setup is designed so you never lose your work. If analysis fails or you leave mid-way, your conversation is stored and can be resumed:

* A **Resume Setup** button appears on the setup screen if something interrupted the analysis. Selecting it rebuilds your draft from the saved conversation and drops you into the Review stage.
* You can also resume an unfinished setup later from your Genies list — it reopens on the review screen with your details ready to confirm.

If you decide not to keep a draft, the review screen's **Discard** option clears it and returns you to the start.


# Setting Up a Genie by Voice
Source: https://docs.helpgenie.ai/voice-guide/genie-setup-voice-flow

Talk your Genie into existence — how the voice setup step works, plus screen-awake and iPhone tap behavior.

The **Talk to Set Up** option lets you build a Genie by speaking with our setup guide. You have a natural conversation about what you need, and we turn it into a draft configuration you then review. It's the fastest way to capture the details when you'd rather talk than type.

You reach it from the [setup start screen](/genie-setup-overview#choosing-how-to-start) by choosing **Talk to Set Up**.

<Frame>
  <img alt="Voice setup screen" />
</Frame>

## Starting the conversation

The talk step shows a large Genie avatar in the middle of the screen with a status message above it that tells you what's happening ("Click to start setting up your Genie", "Listening…", "Thinking…", and so on).

* Select the avatar or **Begin Setup** to start. Your browser will ask for microphone permission the first time.
* Talk naturally — describe your business, who calls, and what you want the Genie to handle. The guide asks follow-up questions and responds out loud.
* A live transcript of the conversation appears alongside so you can follow along.

### Typing instead, mid-conversation

You don't have to stay hands-free. A text box sits below the controls: type a message and send it at any point, even during a spoken conversation. You can also attach an image (for example, a photo of a menu or price list) using the attachment button, and it's included as context.

You can mute all audio during the conversation if you need quiet — the Genie keeps listening and you keep the transcript.

## Finishing and analyzing

When you're done, select **End Setup & Analyze**. We analyze the whole conversation to extract your Genie's settings — its purpose, tone, first message, and more — and a loading screen keeps you posted. When it finishes, you land on the **Review Your Genie** screen to check and adjust everything before creating.

<Note>
  If analysis is interrupted, your conversation is saved safely. A **Resume Setup** button appears so you can rebuild your draft without starting over. See [Resuming a setup](/genie-setup-overview#resuming-a-setup).
</Note>

## Keeping your screen awake

Voice setup needs your screen to stay on and your microphone active for as long as you're talking. To prevent your device from going to sleep mid-conversation, the flow automatically keeps the screen awake while a conversation is running, and releases it the moment you end the conversation or leave the page. You don't need to do anything to turn this on.

## The iPhone tap reminder

iPhones and iPads are especially aggressive about dimming and locking the screen, which can interrupt a voice conversation. To help, on those devices a small reminder appears periodically during a conversation, prompting you to **tap the screen** to keep things active.

* The first reminder shows shortly after the conversation starts, then it repeats at intervals while you're connected.
* Tapping the reminder (or anywhere on the screen) refreshes the screen-awake behavior and keeps your conversation going smoothly.
* The reminder only appears on iPhone and iPad — you won't see it on a computer or Android device — and it stops automatically when the conversation ends.

<Note>
  If your iPhone screen does dim during a long conversation, a quick tap brings everything back — you won't lose the conversation or your place in setup.
</Note>


# Genie Templates
Source: https://docs.helpgenie.ai/voice-guide/genie-templates

Browse a catalogue of ready-made Genies by business function and deploy one pre-configured in a couple of minutes.

The Genie Templates catalogue is a menu of ready-made Genies, each built for a specific job. Instead of starting from a blank setup, you pick the Genie that matches the work you need done — support, sales, bookings, compliance, and more — and it arrives pre-configured. You add your branding and knowledge, then switch it on.

You'll find it under **Genie Hub → Templates** (`/genie-hub/templates`), or by choosing **Browse Genies** on the [setup start screen](/genie-setup-overview#choosing-how-to-start).

<Frame>
  <img alt="Genie templates catalogue" />
</Frame>

## Browsing the catalogue

The catalogue is organized like a menu, with Genies grouped under business functions:

* **Customer Service** — Genies that take care of your existing customers.
* **Account Management** — Genies that grow and retain your customer base.
* **Marketing** — Genies that get you in front of the right people.
* **Operations** — Genies that run the back-office work that eats your week.
* **Sales** — Genies that win new business: qualify, quote, dial, close.
* **People (HR & L\&D)** — Genies for hiring, employee experience, and learning.
* **Compliance & Insights** — Genies that make sure nothing slips and capture the signal.

Each section stacks its Genies as a list. A row shows the Genie's mascot, its name, a one-line description of what it does, and roughly how long it takes to launch. A **jump-to-section** bar at the top lets you skip straight to a category — each one shows a count of how many Genies it holds — without losing your place.

Select any Genie to open its details.

## The Genie preview

Choosing a Genie opens a preview (the "kickstart" screen) so you know exactly what you're getting before committing. It shows:

* The Genie's mascot, name, and tagline.
* A fuller description of how the Genie works.
* **What this Genie will do for you** — a short list of the concrete jobs it handles.
* **What happens when you deploy** — a reminder that the template is cloned pre-wired, then you add your branding, point it at your knowledge, and connect your channels.

From here you can go **Back to catalogue** to keep browsing, or **Deploy this Genie** to set it up.

## Deploying a template

Selecting **Deploy this Genie** takes you into [Genie Setup](/genie-setup-overview) with the template already loaded. Behind the scenes this opens the setup flow with the template applied (`/user-hub/genie-setup?template=<name>`), so you skip the "describe your Genie" stage entirely.

The template pre-fills your draft with:

* The Genie's **name** and **purpose**.
* A ready-made **first message** and conversation prompt.
* Sensible **conversation settings** and category.
* Any **tools** and **knowledge** the template comes with.

You land directly on the **Review Your Genie** screen, where the whole configuration is filled in and ready to customize. Everything is editable — swap the voice, adjust the wording, add your branding, attach your own documents — before you select **Create Genie**. See [Reviewing and creating your Genie](/genie-setup-listener-form#reviewing-and-creating-your-genie) for the full review walkthrough.

<Note>
  Deploying a template never creates a Genie on its own — it only pre-fills the setup. Nothing goes live until you review the details and choose **Create Genie**.
</Note>


# Inbox
Source: https://docs.helpgenie.ai/voice-guide/inbox

See every conversation your Genies have had, and turn those conversations into spreadsheet-style Views you can shape however you want.

The Inbox is where every conversation your Genies have lands. From here you can browse those conversations one by one, or turn them into **Views** — spreadsheets you build by describing what you want in plain English.

You'll find it under **Genie Hub → Inbox** (`/genie-hub/inbox`). The page has two tabs: **Conversations** and **Views**.

<Frame>
  <img alt="Inbox" />
</Frame>

## Conversations tab

The Conversations tab lists your Genies' recent interactions, newest first. It's the default view when you open the Inbox.

Each entry summarizes a single conversation. Conversations you haven't looked at yet are marked as unreviewed, and the list updates on its own as new conversations come in — you don't need to refresh the page.

### Filtering and layout

* **Filters** — open the filter panel to narrow the list by Genie and by time range. The time range defaults to the last 7 days. A dot on the Filters button shows when a filter is active.
* **View toggle** — switch between table, rows, and card layouts. Your choice is remembered for next time.
* **Count** — the total number of conversations currently shown appears on the right.

### Actions

* **Open a conversation** — select any conversation to open its full analysis page, where you can read the transcript and review the details.
* **Mark All Reviewed** — when you have unreviewed conversations, this button clears them all at once and shows how many were marked.

<Note>
  If you haven't created a Genie yet, the Conversations tab prompts you to create your first Genie — conversations only appear once a Genie starts handling them.
</Note>

## Views tab

**Views turn conversations into spreadsheets.** You describe what you want to track, and your Genies read the transcripts and fill in the columns for you. It's the standout feature of the Inbox, so it appears as a highlighted tab.

### Creating a View

At the top of the Views tab is a prompt box. Describe the spreadsheet you want in plain English — for example, "list every caller who asked about pricing, with their name and what they wanted." Your Genies read the matching conversations, design the columns, and build the table.

Before you submit, you can set the scope:

* **Genies** — choose which Genies' conversations to include, or leave it open to include all of them.
* **Time range** — choose how far back to look. New Views default to the last 30 days.

While a View is being built, a panel shows the progress as your Genies read the transcripts and design the columns.

### Getting suggestions

Not sure what to build? Select **Suggest views for me** (or **Get ideas**). Your Genies read your selected Genies' recent conversations and propose three Views you could save with one click. You can regenerate the suggestions or change the Genie/time-range scope to get different ideas.

If your Genies haven't had any conversations yet, the Views tab tells you so — suggestions and Views appear once there are conversations to read.

### Your saved Views

Saved Views are listed below the prompt, each showing a preview of its rows. From the list you can:

* **Open a View** — select it to expand the full table and refine it.
* **Pin a View** — keep your most-used Views at the top.

### Working inside a View

Open a View to see its full table. Each row comes from one conversation; select a row to jump to that source conversation. From inside a View you can:

* **Refresh** — bring in new conversations since your last refresh. Your existing rows, notes, and edits stay exactly as they are — Refresh only adds new rows. You'll see how many new rows were added, or a note that the View is already up to date.
* **Refine in plain English** — type an instruction like "drop the cold leads," "add a phone column," or "group by pickup city." Refinements can add columns or filter which rows you see. Suggested refinement chips appear beneath the box.
* **Filter columns** — filter any column by a search term. Active filters show as removable chips, along with how many rows are shown out of the total.
* **Edit columns** — rename or delete columns, or add a new one by describing what it should capture. Renaming a column offers to regenerate its data to match the new name.
* **Rename the View** and **edit which Genies** it analyzes.
* **Export CSV** — download the current table as a spreadsheet file.
* **Delete** — remove the View after a confirmation.

<Note>
  A refresh brings in only conversations that arrived since the last one, so your existing rows are never overwritten. If your columns turn out too specific for what the conversations actually contain, the View tells you how many conversations it analyzed and suggests simplifying or rephrasing.
</Note>

## What happened to Leads, Support, and the other tabs?

The Inbox used to have separate tabs for things like **Leads**, **Support**, **Bookings**, **Orders**, **Quotes**, **Surveys**, **Forms**, **Interviews**, **Reviews**, and **Training**. These have all been **folded into Views**.

Instead of a fixed tab for each, you now build exactly the breakdown you want by describing it. Want just your leads? Create a View for them. Want support questions with their outcomes? Describe that. Views replaces every one of those tabs with a single, flexible tool.

<Note>
  Old links still work. If you follow a bookmark to one of the retired tabs (for example `/genie-hub/leads` or `/genie-hub/support`), it automatically opens the Views tab so nothing breaks.
</Note>


# Insights
Source: https://docs.helpgenie.ai/voice-guide/insights-hub

Understand what's working across your Genies — a plain-English story of your conversations, performance analytics, and an audit trail of every change, all in one place.

The **Insights** hub is where you step back and see the bigger picture: what your Genies are actually doing, how they're performing, and what changed behind the scenes. It reads across your conversations and turns them into trends, outcomes, and things worth your attention — so you're not scrolling through calls one by one.

You'll find it under **Genie Hub → Insights** (`/genie-hub/insights`). The page opens on the **Conversational Insights** tab, and a row of tabs at the top lets you switch between four views:

* **Conversational Insights** — the story across all your conversations, with wins, trends, and prompts you can ask about them.
* **Per-call Analysis** — the full drill-down list of every individual call, with topics, lead details, and export.
* **Analytics** — headline numbers, a conversation timeline, and a per-Genie performance leaderboard.
* **Activity** — an audit trail of changes to your Genies, knowledge, and settings, plus what needs your attention.

<Note>
  The **Analytics** and **Activity** views live inside this hub as tabs. Old bookmarks to `/genie-hub/analytics` or `/genie-hub/activity` still work — they open the Insights hub on the matching tab automatically.
</Note>

If you haven't created a Genie yet, most of these tabs will prompt you to create your first Genie — there's nothing to analyze until a Genie starts handling conversations.

<Frame>
  <img alt="Insights hub" />
</Frame>

## Conversational Insights

This is the default tab: a briefing on everything your Genies have handled over a chosen period. Rather than a raw list, it reads your conversations and tells you the story.

### Filters

Three filters at the top shape everything below them:

* **Filter by Genie** — focus on a single Genie or leave it on **All Genies**. Genies shared with you by your team are marked **Team**.
* **Analysis Status** — show all conversations, only those that have been analyzed, or only those still waiting for analysis.
* **Date Range** — last 7 days, last 30 days (the default), last 90 days, or all time.

<Frame>
  <img alt="The three filter controls: Filter by Genie, Analysis Status, and Date Range at the top of the Conversational Insights tab" />
</Frame>

### The story this period

At the top, a highlighted card gives you a short, plain-English read of the period — how many conversations came in, whether sentiment leaned positive or negative, the topic that came up most, and how many calls are worth a closer look. When a richer Smart summary is available it's used; otherwise a quick summary is generated from your conversations.

### The pulse strip

Four at-a-glance cards sit beneath the story:

* **Volume** — how many conversations came in this period, with an up/down comparison against the previous period.
* **Sentiment mix** — the split between positive, neutral, and negative conversations, plus an average satisfaction score when available.
* **Avg duration** — the typical call length, and roughly how much of the time your Genie was talking.
* **Escalations** — how many calls were handed off to a human, and what share of total calls that represents.

### What stood out, trends, and signals

When a Smart digest is available, a **What stood out** section surfaces decision-shaped highlights — labelled **Win**, **Opportunity**, **Theme**, or **Worth a look** — each with a short explanation and links to example calls.

Below that:

* **Topic trends** — what customers keep bringing up, with newly-appearing topics flagged as **new**. Select any topic to ask your Genie about it in more depth.
* **Recurring signals** — patterns and recommendations your Genies flagged across multiple calls. Select one to dig into it.
* **Action queue** — the conversations worth reviewing first, sorted by urgency and tagged with why they're flagged (negative sentiment, an escalation, a missing lead, or analysis not yet run). Select a row to open the full conversation.

### Ask Your Genie

Two ways to turn this data into answers:

* **Ask Your Genie** button — opens a chat pre-filled with a summary of your current filters, so your Genie can give you a Smart breakdown of the period. Selecting a topic, signal, or suggested prompt does the same thing with a more specific question.
* **Suggested questions** — a grid of ready-made prompts near the bottom, such as *"Where is my genie struggling?"*, *"Show me hot leads I missed"*, *"Coach my genie"*, and *"Draft my follow-up emails."* Select one to send it straight to chat, already scoped to your selected Genie and date range.

<Frame>
  <img alt="The Ask Your Genie button and suggested questions grid" />
</Frame>

<Note>
  Once people start talking to your Genies, this is where the story lands. If there's nothing here yet, share your Genie's link or QR code to get the first conversations flowing.
</Note>

## Per-call Analysis

The **Per-call Analysis** tab is the detailed drill-down: every individual conversation, listed newest first, using the same Genie / Analysis Status / Date Range filters as the Insights tab.

### What each row shows

Every conversation shows the Genie that handled it, the date and duration, a short summary, its topics, and any lead information captured (name, contact details, and other fields your Genie collected). Conversations handled by a team member's Genie are marked **Team**.

* **Expand a conversation** — open a row to see its full analysis: overall sentiment and satisfaction, a talk-time breakdown (how much the Genie, the customer, and silence each took), a summary, top insights, and all its topics. From the expanded view you can copy the transcript or **Open full conversation**.
* **Run analysis** — if a conversation hasn't been analyzed yet, a play button lets you analyze it on the spot to fill in its summary, topics, and lead details.

<Frame>
  <img alt="A conversation row expanded to show its full analysis panel" />
</Frame>

The list loads more conversations as you scroll, and shows how many of the total you're currently viewing.

### Selecting, asking, and exporting

* **Select conversations** — tick individual rows, or use the header checkbox to select everything currently visible. A bar appears at the bottom of the screen showing how many you've selected.
* **Ask Your Genie about a selection** — from that bar, send just the selected conversations to chat to compare, summarize, or pull insights from them.
* **Export a selection** — download the selected conversations as an Excel spreadsheet.
* **Export Analysis** — export every conversation for the current filters at once. This requires a single Genie to be selected first; until you pick one, the button stays disabled with a *"Filter by a Genie first"* hint.

<Frame>
  <img alt="The selection bar at the bottom of the screen with Ask Your Genie and Export options" />
</Frame>

## Analytics

The **Analytics** tab is the numbers view — headline stats, a timeline you can plot per Genie, and a performance leaderboard.

### Overview

Four cards summarize your whole account:

* **Total Conversations** — across all your Genies.
* **Active Genies** — how many Genies you have.
* **Avg. Conversations/Genie** — the average spread of conversations across them.
* **Top Performing Genie** — the Genie with the most conversations.

### Conversation Timeline

A chart plots conversation volume over time. Use the **date range** control to switch between the last 7, 30, or 90 days. By default, every Genie that has had conversations is plotted; you choose which Genies appear by selecting them in the performance list below.

### Genie Performance

A ranked list of your Genies, ordered by how many conversations each has handled. Each entry shows the Genie's avatar and name, who owns it, its brand, its **Total Conversations**, and its activity in the **Last 7 Days**. Genies shared by teammates are marked **Team**.

* **Select a Genie** — tick a Genie (or select its card) to add it to the timeline chart above. A count shows how many Genies are currently plotted.
* **Select All Active / Deselect All** — add or remove every Genie that has conversations from the timeline in one click. Genies with no conversations are left out.

## Activity

The **Activity** tab is the audit trail — what your Genies did, what changed in your account, and what needs a closer look. It focuses on meaningful events (edits to Genies, knowledge, and settings) rather than routine clicks.

### This week's digest

Four tiles at the top summarize the last 7 days:

* **Conversations** — how many came in, compared with the previous week.
* **Resolved without you** — how many of those conversations your Genies handled start-to-finish, with no handoff to your team.
* **Needs attention** — how many items are flagged for review; select this tile to jump straight to them.
* **Silent Genies** — how many live Genies had no conversations, out of your total.

<Frame>
  <img alt="The four digest tiles at the top of the Activity tab" />
</Frame>

### Needs your attention

A dedicated panel groups anything from the last 7 days worth reviewing, sorted by recency:

* **Escalations** — calls your Genies handed off to a human.
* **Low sentiment** — conversations that left callers frustrated, with a sentiment score.
* **Negative feedback** — direct thumbs-down left by end users.
* **Silent Genies** — live Genies with zero conversations in the last week.

Select any item to open the related conversation or Genie. When there's nothing to flag, this panel shows an **All clear this week** message.

### Recent changes

A running feed of meaningful events — edits to Genies, knowledge documents, account settings, and more. Each entry shows what happened, which Genie or resource it affected, when it occurred, and its category. Items that failed or are high priority are marked with a colored dot, and you can select an entry to open the affected Genie, conversation, or document.

You can shape the feed with:

* **Search** — find activity by keyword.
* **Date Range** — Today, Yesterday, Last 7 days (the default), Last 30 days, or a custom start/end range.
* **Category** — filter to one or more types, such as Conversation Analysis, User Management, genie, document, account, security, or settings. Active categories appear as removable chips, and **Clear filters** resets everything.
* **Show routine actions** — off by default. Routine events like page views and your own edits are hidden to keep the feed meaningful; turn this on to see everything.

The feed loads more as you scroll or via **Load more**, and tells you when you've reached the end of the selected window.


# Knowledge Base
Source: https://docs.helpgenie.ai/voice-guide/knowledge-base

Capture, shape, and activate the knowledge your Genies use to answer callers.

Your Knowledge Base is the home for the material your Genies rely on: documents, web pages, transcripts, notes, and research. You can capture material from several sources, review and organize it, then decide what becomes active knowledge and which Genies should use it.

You'll find it under **Genie Hub → Knowledge Base** (`/genie-hub/knowledge-base`). The page begins with a guided knowledge-readiness area, followed immediately by the **Documents** and **By Genie** views.

<Frame>
  <img alt="Knowledge Base" />
</Frame>

## Capture, shape, activate

The knowledge-readiness area turns building a useful Knowledge Base into three steps:

* **Capture** — bring useful files, pages, recordings, notes, and research into one workspace.
* **Shape** — review and organize captured sources, including anything still waiting to be activated.
* **Activate** — make dependable sources available in the Knowledge Base and attach them to the right Genies.

Each step shows a live count based on your current documents. Four pathways take you directly to a useful starting point: **Files & media**, **Web & cloud**, **Write, record & research**, or **Find knowledge gaps**.

The header keeps the two common actions close at hand. **Add knowledge** opens the acquisition panel, while **Find knowledge gaps** opens guided coverage checks.

## Documents tab

The Documents tab lists everything you've captured. Each row shows the document's name, type, date added, and status:

* **In KB** — the document is active in your Knowledge Base and available to your Genies.
* **Not In KB** — the document has been captured but hasn't been activated yet.

A processing indicator appears next to items that are still being prepared (for example, a PDF being read or an audio file being transcribed) — these become available once processing finishes. Documents added by a teammate are marked **Team**.

### Searching and filtering

* **Search** — use the search box to find documents by name. Results update as you type.
* **Filter** — narrow the list by Genie or document type. On mobile, filters open in a sheet. Select **Clear** to reset them.
* **Folders** — the sidebar (on the left on larger screens) lets you browse and organize documents into folders. You can collapse it to free up space.

### Actions on a single document

Select a document to open its details, where you can view, edit, and manage it. From the row itself you can also:

* **View source** — opens the original file or page in a new tab (when a source is available).
* **Edit** — change the document's name, description, and settings.
* **Add to Knowledge Base** — activate a captured document so your Genies can use it.
* **Delete** — permanently removes the document after confirmation.

<Warning>
  Deleting a document can't be undone, and it's removed from any Genies it was attached to.
</Warning>

### Bulk actions

Select the checkbox on one or more documents (or the header checkbox to select all) and a toolbar appears at the bottom of the screen. With multiple documents selected you can:

* **Move to Folder** / **Remove from Folder** — organize the selected documents.
* **Assign to Genie** — attach active documents to a Genie. Documents must be in the Knowledge Base first; any that aren't are skipped with a notice.
* **Consolidate** — merge selected documents into one combined document, with the option to remove the originals after merging.
* **Delete** — permanently remove all selected documents after a confirmation.

<Note>
  Consolidate needs at least two documents selected, and it won't merge files larger than 5MB or with more than 100 pages. Oversized files are listed so you know which ones to leave out.
</Note>

## By Genie tab

The **By Genie** tab shows each of your Genies with its category, active status, and current document count. Use the search box to find a Genie by name, description, or category, and the group tabs to narrow the view. Select a Genie to open its dedicated knowledge view and manage only that Genie's attached documents. See the [Genie knowledge view](/knowledge-base-genie) for details.

## Adding knowledge

Select **Add knowledge**, or choose a pathway in the knowledge-readiness area, to open the acquisition panel. Pathways open directly on a useful method. You can switch methods using three labelled groups; on mobile, choose a group first to keep the list compact.

**Files & cloud** includes:

* **Bulk Upload** — add many files at once.
* **PDF File** — upload a PDF from your device.
* **Document** — upload TXT, CSV, DOC, or DOCX files.
* **Image** — extract text from an image.
* **Cloud Storage** — import files from a connected cloud drive.

**Web & media** includes:

* **PDF URL** — pull a PDF in from a link.
* **Website** — capture the content of one web page.
* **Web Scraping** — capture multiple pages from a site.
* **YouTube** — capture the transcript from a video.
* **Audio** — transcribe an audio file.
* **Video** — transcribe spoken content from a video file or link.

**Write & research** includes:

* **Notes** — write or paste a text note directly.
* **Quick Research** / **Deep Research** — gather a focused or detailed brief and save it as a document.
* **Custom Integration** — talk with the team about a tailored source.

The **Knowledge destination** selector stays visible above each form. Choose a Genie to attach new content immediately, or choose **Knowledge Base only** and assign it later. When you add knowledge from a specific Genie's knowledge drawer, that Genie is selected automatically.

## Find knowledge gaps

Select **Find knowledge gaps** to open a panel of ready-made prompts that review your content and recent conversations. They help you spot what's missing and decide what to work on next — for example:

* **What should I add this week?** — top recommendations, ranked by impact.
* **What does my Genie not know yet?** — gaps drawn from recent calls.
* **Which Genies have thin knowledge?** — a coverage audit across your Genies.
* **Which documents matter most?** — your most-used, highest-value content.
* **Are any documents contradicting?** — a quality check for stale or conflicting content.
* **Draft an FAQ I'm missing** / **Suggest a folder structure** — content and organization help.

Selecting a prompt opens Your Genie with the request ready to run.


# A Genie's Knowledge
Source: https://docs.helpgenie.ai/voice-guide/knowledge-base-genie

View, coach, and manage the documents attached to a single Genie.

Each Genie has its own knowledge view — a focused page showing only the documents that Genie draws on, along with tools to coach and manage them. It's the best place to see what one Genie actually knows and to fill in the gaps.

You reach it from the Knowledge Base **By Genie** tab (`/genie-hub/knowledge-base`): select a Genie card to open its knowledge view at `/genie-hub/knowledge-base/:genieId`. Select **Back to Knowledge Base** at the top to return.

<Frame>
  <img alt="A Genie's knowledge view" />
</Frame>

## What you'll see

At the top, a header card shows the Genie's name, description, category, active status, and branding. Below it:

* **A statistics bar** — the number of documents in this Genie's knowledge base and when it was last updated.
* **The document list** — every document attached to this Genie, newest activity first.

If the Genie has no documents yet, you'll see a prompt to go add some from the main Knowledge Base.

Each document shows its name, an icon for its type, its description (if any), the date it was added, and a status badge — **In Knowledge Base** or **Not in KB**.

## Coach this Genie's knowledge

Near the top of the page is a **Coach Genie's knowledge** card. It hands this Genie's document list and recent conversations to Your Genie and asks for concrete advice on what to add, fix, or remove.

* **Coach this genie's knowledge** — the main button, for a full prioritized review.
* Quick prompts for focused help: **What's missing?** (gap analysis), **Suggest 3 docs to add** (a prioritized list), **Draft an FAQ** (ready to upload), and **Audit what's there** (a quality check).

Selecting any of these opens Your Genie with the request ready to run.

## Actions on a document

Each document row has a set of controls:

* **View source** — opens the original file or page in a new tab (when a source is available).
* **Edit** — opens the document's details so you can change its name, description, and settings.
* **Unlink from genie** — removes the document from this Genie. The document stays in your knowledge base and can be re-attached later; you'll be asked to confirm first.
* **Delete** — permanently removes the document everywhere. You'll be asked to confirm first.

<Note>
  **Unlink** and **Delete** are different. Unlinking only detaches the document from this Genie — it's still in your knowledge base. Deleting removes it entirely and can't be undone.
</Note>

### Full details

Select **View Full Details & Content** on a document to expand it in place and see its full content and metadata. Select **Hide Full Details** to collapse it again.

## Adding documents to a Genie

You don't add new documents from this view — you attach existing ones. To do that, go back to the main **Knowledge Base**, then either use **Assign to Genie** in the bulk toolbar, or choose this Genie when you upload new content. Newly attached documents then appear here.


# Genie Appearance & Advanced Settings
Source: https://docs.helpgenie.ai/voice-guide/my-genies-advanced-settings

Fine-tune how your Genie looks and behaves — branding, page resources, closing page, response intelligence, conversation flow, tools, events, and private data sources.

The remaining cards on a Genie's configuration screen cover its look, the extra content on its page, and the finer controls over how it thinks and behaves. Most are read-only until you select **Edit**; **Save** confirms your changes and **Cancel** discards them.

This follows on from [Knowledge & distribution](/my-genies-knowledge-distribution).

<Frame>
  <img alt="Genie appearance and advanced settings" />
</Frame>

## Branding

The **Branding** card sets your Genie's visual identity. It previews your logo (or a colored circle if none is set) and your primary color, plus a secondary color and a gradient tag when those are in use. Select **Edit** to open the branding editor, where you set colors, upload a logo, and enable a gradient.

## Resources

The **Resources** card manages the documents, links, and banner shown on your Genie's live page. Select **Edit** to configure three sections:

* **Documents** — upload up to **10** files (each under **25 MB**). Supported types include PDF, Word, PowerPoint, Excel, text, CSV, and images. Each file can be renamed or removed.
* **Banner Image** — paste an image URL to show a banner, with a live preview.
* **Links** — add up to **10** links, each with a **label** and a **URL** (validated as you add them).

## Closing page

The **Closing page** card is the wrap-up people see when a conversation ends. Select **Edit** to set:

* **Closing message** — a short message up to **240 characters** (a friendly default is used if you leave it blank).
* **Next-step buttons** — up to **4** call-to-action buttons, each with a **label** (such as "Book a call") and a **URL**.

Take-away documents and links on the closing page come from the **Resources** section above.

## Extra

The **Extra** card holds a few post-call options. Select **Edit** to configure:

* **Redirect After Call** — a web address to send people to when the conversation ends.
* **Capture Leads** — when on (the default), conversations automatically create lead records.
* **Genie Memory** — when on, the Genie remembers context from past conversations. Off by default.

## Model & Intelligence

The **Model & Intelligence** card tunes how your Genie generates responses. Select **Edit** to adjust:

* **Response intelligence** — choose the intelligence level for your Genie, from a fast everyday option to a more capable one for complex conversations.
* **Temperature** — a slider from **Precise** to **Creative** (0 to 2, default 0.7). Lower values keep answers focused and consistent; higher values make them more varied and creative. A live label reads **Very Precise**, **Balanced**, **Creative**, or **Very Creative**.
* **Max response length** — an optional cap on how long each response can be.
* **Knowledge Retrieval** — when on, the Genie pulls relevant material from its knowledge base while answering.

## Conversation Behavior

The **Conversation Behavior** card controls timing and turn-taking:

* **Max Duration** — the longest a single conversation can run, in seconds.
* **Turn Mode** — **Turn Based** (default) or **Silence Based**, which changes how the Genie decides a speaker has finished.
* **Turn Timeout** — how long to wait during a turn.
* **Silence End Call** — how much silence ends the call.
* **Text Only Mode** — run the conversation as text, without voice.

## External Tools

The **External Tools** card lists the capabilities your Genie can use during a conversation, each with a name and description. A badge shows how many are enabled. Select **Edit** to turn each capability on or off.

<Note>
  Some tools are marked **Managed by Sync** — these are set up automatically and can't be toggled here.
</Note>

## Client Events

The **Client Events** card controls which events your Genie streams to connected applications, each with a label and description. A badge shows how many are enabled, and events that are on by default carry a **Default** badge. Select **Edit** to enable or disable each event.

## Private Context Source

The **Private Context Source** card attaches a connected data source your Genie can search privately during conversations:

* If you haven't set up any sources yet, you'll be pointed to the **Integrations** page to create your first one.
* If sources exist, use **Choose integration…** to pick one — each is tagged by type (**document**, **API**, or connected service) — and attach it.
* Once attached, a panel confirms the source and lists a few of its available resources. You can **Change** it, **Refresh** its capabilities, or **Detach** it.

For call limits and purchasing more capacity, see [Usage & billing](/my-genies-billing).


# Genie Usage & Billing
Source: https://docs.helpgenie.ai/voice-guide/my-genies-billing

See a Genie's call limits and top up capacity — the usage and billing controls on a Genie's configuration screen.

The **Usage & Billing** card, at the bottom of a Genie's configuration screen, shows how much calling capacity the Genie has and where to manage it. It follows on from the [appearance and advanced settings](/my-genies-advanced-settings).

<Frame>
  <img alt="Genie usage and billing" />
</Frame>

## What you'll see

* **Current Daily Call Limit** — the number of calls this Genie can handle per day, or **Not set** if no limit is applied.
* A short explanation that call limits and additional call purchases are managed in your account settings, so the same balance and plan apply across your Genies.

## Managing limits and buying more

Select **Go to Account Settings** to open your account's calls and purchases area, where you can:

* Review and adjust call limits.
* Buy additional calls to add capacity.

<Note>
  Usage and purchases are handled at the account level, not per Genie — so topping up adds capacity you can use across all of your Genies. See [Account Settings](/account-settings) for the full billing and plan details.
</Note>


# Genie Identity, Voice & Prompts
Source: https://docs.helpgenie.ai/voice-guide/my-genies-identity-voice

Configure who your Genie is and how it speaks — name and profile, voice and speech, system prompt, welcome messages, and pronunciations.

Opening a Genie from [My Genies](/my-genies-list) brings you to its configuration screen, where everything about that Genie is organized into cards. This page covers the first group: **identity, voice, and prompts** — the settings that shape who your Genie is and how it sounds.

<Frame>
  <img alt="Genie identity and voice settings" />
</Frame>

## Getting around the configuration screen

When you open a Genie, you land in one of two places:

* **Setup canvas** — new or unfinished Genies open on a guided, step-by-step canvas. Select **View all features** to reveal the full set of settings cards. Your choice is remembered.

<Frame>
  <img alt="Setup canvas with the View all features button visible" />
</Frame>

* **Full settings** — the complete stack of configuration cards. A **Back to setup** link returns you to the guided canvas at any time.

A toolbar runs along the top of the full settings view:

* **Back** returns to your Genies list.
* A **List / Grid** toggle changes how the cards are laid out (on desktop).
* Quick-jump links scroll you to each section: **Identity**, **Prompts**, **Insights**, **Knowledge**, **Distribution**, **Branding**, **Conversation**, **Intelligence**, **Tools**, and **Extra**.
* **Delete** permanently removes the Genie, after a confirmation. This action can't be undone.

<Frame>
  <img alt="Full settings toolbar showing the List/Grid toggle, quick-jump links, and Delete button" />
</Frame>

At the top of the screen, the Genie's header shows its avatar, name, and welcome message, along with badges for its purpose, **Voice** or **Listener** type, **Active/Inactive** status, **Private** (when not public), and ownership. From here you can:

* **Quick Test** — start a test conversation (also available by tapping the avatar).
* **Share** — share the Genie's link, or open the sharing panel for a private Genie.
* **Genie Access** — manage who can use this Genie.
* **Genie Trust Center** — review the Genie's brand integrity and trust settings.

<Frame>
  <img alt="Genie header showing avatar, badges, and the Quick Test, Share, Genie Access, and Genie Trust Center actions" />
</Frame>

<Note>
  Most cards work the same way: they're read-only until you select **Edit**, which reveals the fields. **Save** confirms your changes and shows a brief confirmation; **Cancel** discards them.
</Note>

## Identity & Purpose

The **Identity & Purpose** card holds your Genie's basic profile. In view mode it shows the name, category, purpose type, status, visibility, brand, and description, plus a read-only **Voice** or **Listener** badge showing which kind of Genie it is (defaults to **Voice**). Select **Edit** to change:

<Frame>
  <img alt="Identity and Purpose card in edit mode" />
</Frame>

* **Name** — what your Genie is called.
* **Description** — a short summary of what it does.
* **Brand** — the brand it represents.
* **Category** — pick from the list (defaults to **Other**).
* **Purpose Type** — **None**, **Leads**, or **Support** (not the same as the Voice/Listener badge above, which is set separately).
* **Public Genie** — when on, anyone with the link can access it; it isn't listed publicly.
* **Marketplace Genie** — when on, the Genie is offered in the marketplace.

## Voice & Speech

The **Voice & Speech** card controls how your Genie sounds. In view mode it shows the current voice (with an expandable detail view for accent, age, gender, and best use), the primary language, speech speed, the chosen voice style, and any additional languages the Genie can speak. Select **Edit** to change:

* **Voice** — pick from the voice selector. An advanced option lets you enter a specific voice reference manually.

<Frame>
  <img alt="Voice selector open, showing available voices" />
</Frame>

* **Language** — choose the Genie's primary language.
* **Voice Style** — choose one of six presets, each tuned for a different feel:
  * **Consistent & Calm** — steady and predictable, good for support and information.
  * **Warm & Friendly** — approachable, with a little natural variation.
  * **Expressive & Engaging** — dynamic, good for sales and storytelling.
  * **Professional & Neutral** — balanced and business-like.
  * **Energetic & Lively** — high energy, good for promotions.
  * **Precise & Clear** — maximum consistency, good for instructions.

<Frame>
  <img alt="Voice Style presets showing all six options" />
</Frame>

* **Advanced settings** — fine-tune **Stability** (steady vs. expressive), **Speed**, and **Similarity** (how closely the voice is matched) if you want manual control.

## System Prompt

The **System Prompt** card defines your Genie's personality and behavior — how it responds and what it should keep in mind. In view mode the prompt is shown as formatted text (or "No system prompt configured"). In edit mode you get:

* An editor with **Edit** and **Preview** tabs — Preview shows your formatted text live.
* An **Enhance** button that automatically improves your prompt.
* An expand button that opens a larger full-screen editor for longer prompts.

<Frame>
  <img alt="System Prompt card in edit mode, showing the Edit/Preview tabs and Enhance button" />
</Frame>

The prompt supports simple formatting, so you can structure it with headings and lists.

## Welcome Messages

The **Welcome Messages** card sets your Genie's first impression in two places:

* **Voice Welcome Message** — spoken when someone starts a voice conversation.
* **Web Page Message** — shown on the Genie's web page.
* **Page URL** — your Genie's public web address, with a copy button. In edit mode you can change the URL slug to something memorable.

If the Genie isn't public, an **Access Limited** notice appears with a **Manage Access** button, since only the owner and granted team members can reach it.

## Pronunciations

The **Pronunciations** card lets you control how your Genie says specific words — useful for brand names, product names, or unusual terms. Existing entries appear as chips showing the word and its custom pronunciation. Select **Manage** to open the pronunciation editor and add or change entries.

<Frame>
  <img alt="Pronunciations card showing existing entries as chips, and the Manage button" />
</Frame>

If you haven't added any, you'll see a prompt to get started.

Next, see [Knowledge & distribution](/my-genies-knowledge-distribution) to give your Genie something to talk about and get it in front of people.


# Genie Knowledge & Distribution
Source: https://docs.helpgenie.ai/voice-guide/my-genies-knowledge-distribution

Give your Genie knowledge, decide what it collects, and get it in front of people — insights, knowledge base, branded documents, and distribution channels.

Once your Genie's [identity and voice](/my-genies-identity-voice) are set, the next group of cards on its configuration screen gives it knowledge, tells it what to collect from each conversation, and puts it in front of the people you want to reach.

<Frame>
  <img alt="Genie knowledge and distribution settings" />
</Frame>

## Insights

The **Insights** card defines what information your Genie extracts from each conversation — for example a caller's name, email, or the reason they got in touch.

* **Attached Insight** shows the insight currently in use, or a note that none is attached. When one is attached, you'll see how many fields it collects and a grid of those field labels.
* **Create Insight** opens a short form where you describe what you want to capture in plain language; the fields are generated for you and attached to the Genie.
* **Edit** adjusts an attached insight's name, description, and fields; **Remove** detaches it.
* **Manage Insights** opens the Insight Manager to view, edit, organize, and reuse insights across Genies.

The collected fields are extracted automatically after each conversation.

## Knowledge Base

The **Knowledge Base** card lists the documents this Genie draws on to answer people. When empty, it prompts you to link documents. When documents are linked, each appears as a card where you can:

* **View** — open the original document in a new tab.
* **Edit** — open the document's details to update it.
* **Delete** — remove the document.

Select **Manage Knowledge** to open a drawer where you link existing documents to this Genie or manage what's already attached. For the full library of content across all your Genies, see the [Knowledge Base](/knowledge-base).

## Branded Documents

The **Branded Documents** card turns your Genie's knowledge into a polished, co-branded guide you can share or print. You'll see a set of document templates, each with a name and short description. Select **Create a document** to open the generator and produce a branded guide from what your Genie knows.

## Distribution

The **Distribution** card is where you choose how people reach your Genie. A prominent **Activation Pack** banner links to a single page that bundles QR codes, an embed snippet, an email signature, and print-ready assets. Below that are individual channels:

* **Phone** — manage phone numbers and call routing for the Genie.
* **Web Embed** — add the Genie to any website. See [Embedding on your website](#embedding-on-your-website).
* **QR Code** — create a scannable code people can use to start a conversation. See [Sharing with a QR code](#sharing-with-a-qr-code).
* **Access** — manage users, access requests, and access QR codes.

### Embedding on your website

The web embed panel offers two styles, each with copy-ready code in **JavaScript**, **HTML**, and **React**:

* **Popup Widget** — a chat bubble that opens on your page. Pick a widget style and a popup size — **Small** (compact), **Medium** (balanced, recommended), **Large** (more room), or **XL** (a full-width panel) — with a live preview.
* **Full Page Embed** — embed the complete Genie interface into one of your pages.

Copy the snippet for your platform and paste it into your site.

### Sharing with a QR code

The QR code panel lets you customize and download a code:

* **Style** — choose a preset look.
* **Label Text** — the text shown with the code (including a "Talk to \[your Genie]" option).
* **Colors** — set the code and background colors, with a **Reset** to your brand defaults.
* **Options** — show your logo, or use a transparent background.
* **Format** — download as **PNG** or **SVG** (downloads are higher resolution than the preview).
* **Public Page URL** — review or change the Genie's web address before generating.
* **Customer Invitation QR** — when on, scanning invites the person to register and adds this Genie to their favorites.

Previously saved codes appear in a gallery where you can re-download or delete them, and a history shows recent URL changes.

<Note>
  A QR code becomes available once your Genie is fully set up. If setup isn't finished, you'll be prompted to complete it first.
</Note>

## Conversation Reports

The **Conversation Reports** card controls the summaries and alerts your team receives after conversations. In view mode it shows whether reporting is on, who receives email summaries, and which notification channels are connected. Select **Edit** to:

* Turn reporting on or off.
* Manage **Email Recipients** — add or remove the email addresses that receive summaries.

Connected **Notification Channels** (such as chat and messaging platforms) each have an on/off toggle; these are set up first under Connections. Customers can also ask the Genie during a conversation to send them a copy of the report, and you can tailor the wording under Email Templates.

## Escalation

The **Escalation Webhook** card lets you trigger an outbound notification whenever your Genie escalates a conversation — for example to hand off to a human. Configure the escalation destination here so the right people are alerted when a conversation needs attention.

For the finer conversation, appearance, and advanced settings, continue to [Appearance & advanced settings](/my-genies-advanced-settings).


# My Genies
Source: https://docs.helpgenie.ai/voice-guide/my-genies-list

Browse, search, group, and organize all of your Genies from one place — the home base for everything you've built.

My Genies is your home base — a list of every Genie you own or have access to. From here you search, filter, group, reorder, and open any Genie to configure it.

You'll find it under **Genie Hub → My Genies** (`/genie-hub/my-genies`). Selecting a Genie opens its configuration screen; see [Identity, voice & prompts](/my-genies-identity-voice) to start.

<Frame>
  <img alt="My Genies list" />
</Frame>

## The page at a glance

Across the top you'll see:

* **My Genies** heading with a short subtitle.
* A **Genie limit** banner (only when you've hit your plan's cap) showing how many Genies you've used and an **Upgrade** button. See [When you reach your limit](#when-you-reach-your-limit).
* **Learn more** — a quick link to guidance for this area.

Below the heading is a controls bar, then your Genies in either grid or table view.

## Ownership filter

When one or more of your Genies belongs to a teammate, a count bar appears with three filters:

* **Total** — every Genie you can see.
* **Personal** — only Genies you own.
* **Team** — Genies owned by other members of your team that you've been given access to.

If nothing is shared with you, this simply shows your total count. Genies owned by someone else are marked with a **Team** badge wherever they appear.

## Searching

Use the **Search genies…** box to filter the list as you type. Search matches a Genie's name, description, welcome message, and category. If nothing matches, you'll see a "No genies found" message with a **Clear search** link to reset.

## Grid and table views

A view toggle switches between two layouts, and your choice is remembered for next time:

<Frame>
  <img alt="Grid/table view toggle in the controls bar" />
</Frame>

* **Grid** — a card per Genie, showing its avatar, name, status, and quick actions.
* **Table** — a compact row per Genie with columns for **Name**, **Category**, **Ownership** (Personal/Team), **Group**, **Status** (active or inactive), feature icons (a phone number is attached, knowledge is attached), and when it was **Created**.

In the table, select a row to expand it and reveal quick actions — **Test your Genie**, **Share**, **Configure**, **Insights**, and **Full details**.

<Frame>
  <img alt="Table view with a row expanded showing the quick actions" />
</Frame>

### What each Genie card shows

In grid view, each card adapts to the Genie's state:

* A **Public** or **Private** badge, and a **Team** badge for Genies owned by others.
* A **Voice** or **Listener** type badge, showing which kind of Genie it is.
* A status pill: **Inactive**, **Live**, **Live · Ready to share**, or **Live · N chats this week** (conversations in the last 7 days).
* **Open** to enter the Genie's configuration screen, and tapping the avatar opens the live Genie to chat or preview.
* One adaptive primary button that reflects what to do next — **Test your Genie** (inactive), **See what people asked** (live with recent chats), or **Activate this Genie** (live but quiet).
* A **Manage** toggle that expands **Share**, **Configure**, **Insights**, and **Full details**.

<Frame>
  <img alt="A Genie card in grid view showing the badges, status pill, and Manage toggle expanded" />
</Frame>

**Share** copies the public link for a public Genie (or uses your device's share sheet on mobile); for a private Genie it opens a sharing panel for team and link access.

## Groups

Groups let you organize Genies into named collections. A row of tabs sits above the list:

* **All** and **Ungrouped** tabs, each with a count, plus a tab for every group you've created.
* Select a tab to filter the list to that group.
* Drag group tabs to reorder them.
* Each group tab has an **×** to delete it — you'll be asked to confirm, and any Genies inside are moved to **Ungrouped** (nothing is deleted). Team groups can't be deleted and are shown with a distinct style.
* **New Group** opens the group panel.

<Frame>
  <img alt="Group tabs row showing All, Ungrouped, custom group tabs, and the New Group button" />
</Frame>

On smaller screens the group bar collapses under a **Genies Groups** header.

### Creating or editing a group

The group panel lets you set a **Group Name** (required, up to 50 characters) and an optional **Description** (up to 200 characters), with live character counters. **Save Group** is enabled once you've entered a name.

<Frame>
  <img alt="Group panel open with the Group Name and Description fields" />
</Frame>

### Moving a Genie into a group

Each Genie has a group selector (a small pill showing its current group, or **Ungrouped**). Open it to pick a group and reassign the Genie. Personal Genies can only join personal groups, and team Genies can only join team groups.

<Frame>
  <img alt="Group selector open on a Genie card, showing available groups" />
</Frame>

## Reordering

Drag any Genie card (grid) or row (table) using its grip handle to change the order they appear in. Your new order is saved automatically.

<Note>
  Reordering is turned off while a search term is active — clear the search to drag Genies again.
</Note>

## Creating a new Genie

* The **Unlock your next genie** card at the bottom of the list starts a new setup. See [Setting Up a Genie](/genie-setup-overview).
* The **Unfinished setups** button (a checkmark icon in the controls bar) takes you to Genies whose setup you haven't finished.
* If you have no Genies yet, an empty state offers **Create Your First Genie**.

## When you reach your limit

Your plan includes a maximum number of Genies. When you reach it:

* A **Genie limit reached** banner appears at the top with your current count and an **Upgrade** button.
* An upgrade card replaces the "create" prompt, showing how many Genies you've used and the benefits of upgrading (unlimited Genies, advanced customization, priority support and analytics).
* **Upgrade to Premium** takes you to the pricing page.

Existing Genies keep working — the limit only affects creating new ones.


# Portals
Source: https://docs.helpgenie.ai/voice-guide/portals

Create custom pages that showcase multiple genies together — group your genies, brand the page, and share it with a single link.

Portals are custom pages that bring several genies together in one place. Use one to showcase your support team, a set of product assistants, or any collection of genies you want visitors to reach from a single link.

You'll find Portals under **Genie Hub → Portals** (`/genie-hub/portals`). The list page is where you create, search, reorder, and remove portals; selecting **Edit Portal** opens a portal's own page where you configure its genies, branding, and settings.

<Frame>
  <img alt="Portals list" />
</Frame>

## The list page

Across the top you'll see:

* A **Portals** heading with a short subtitle.
* **Learn more** — a quick link to guidance for this area.
* **Create Portal** — starts a new portal (see [Creating a portal](#creating-a-portal)).

Below the heading, a **Your Portals** count shows how many portals you have, alongside a **Search portals…** box. Your portals then appear as a stack of cards.

If you have no portals yet, an empty state explains what portals are and offers **Create Your First Portal**.

### Searching

Type in the **Search portals…** box to filter the list as you go. Search matches a portal's name, description, and URL slug. If nothing matches, you'll see a "No portals found" message with a **Clear search** button to reset.

### What each portal card shows

Each card has a branded panel on the left and details on the right:

* The panel previews up to five of the portal's genie avatars (with a **+N** chip when there are more), plus a chip showing the total **genie count**. If the portal has no genies yet, it shows the portal's logo or its first initial instead.
* **Status badges** — **Public** (public and active), **Inactive**, or **Private**, plus a **Protected** badge when the portal is password protected.
* The portal's **name** and its **/slug**.
* The **description**, when one is set.
* Quick facts along the bottom: the grid column count (for example, **3 Col Grid**), an **Embed On** tag when embedding is allowed, and the welcome message, when set.

Card actions:

* **Preview** — opens the live portal in a new tab.
* **Edit Portal** — opens the portal's own page.
* **Copy link** and **Copy embed code** icons — copy the portal's share link or embed snippet to your clipboard.
* **Delete** (trash icon) — removes the portal (see [Deleting a portal](#deleting-a-portal)).

### Reordering

Drag any card by its grip handle (top-left of the branded panel) to change the order your portals appear in. The new order is saved automatically.

<Note>
  Reordering is turned off while a search term is active — clear the search to drag portals again.
</Note>

### Deleting a portal

Selecting the trash icon opens a confirmation dialog. Deleting a portal can't be undone, but **the genies inside it are not deleted** — only the portal page is removed. Confirm with **Delete** or back out with **Cancel**.

## Creating a portal

**Create Portal** opens a side panel where you set up the basics:

* **Portal Name** (required) — shown at the top of your portal page.
* **Description** — a short summary of what the portal offers.
* **Welcome Message** — greeting shown to visitors when they land on the portal.
* **Branding** (optional, collapsible) — by default a new portal uses your account branding. You can turn that off to set a custom **Primary Color**, **Secondary Color**, and **Enable Gradient** just for this portal. More branding options are available after the portal is created.

Select **Create Portal** to finish. You'll be taken straight to the new portal's page so you can add genies.

<Note>
  Account branding is only available once you've set up brand colors and a logo in **Account Settings**. Until then, the account-branding option is unavailable and new portals use default colors.
</Note>

## Editing a portal

A portal's own page (`/genie-hub/portals/:portalId`) is where you manage everything about it. Use **Back to Portals** to return to the list.

At the top you'll see the portal's name, its **/portal/slug**, and badges for **Active/Inactive** and **Public** status, plus three quick actions:

* **Preview Portal** — opens the live portal in a new tab.
* **Copy Link** — copies the portal's public link.
* **Save Changes** — saves edits made in any of the sections below.

<Note>
  Changes you make in the sections below are applied when you select **Save Changes**.
</Note>

### Portal details

Configure the portal's **Name**, **URL Slug**, **Description**, and **Welcome Message**. The slug is the last part of the portal's web address (`/portal/your-slug`); it's automatically tidied into lowercase words separated by hyphens.

### Layout & visibility

* **Grid Columns** — how many columns of genies the portal shows: **2**, **3**, or **4**.
* **Active** — when on, the portal is accessible to visitors; turn it off to take it offline.
* **Public** — when on, anyone with the link can view the portal.

### Branding

Choose how the portal looks:

* **Use Account Branding** — inherit the colors and logo from your account settings. When this is on, a preview shows the account colors and logo that will be used.
* Turn it off to set **custom branding** for this portal only, using the branding editor. A **Reset to Account** button restores the account colors at any time.

When account branding hasn't been set up yet, this section links you to **Account Settings** to configure your brand colors and logo once and reuse them across all portals.

At a glance (outside edit mode), this section shows whether the portal uses **Account Branding** or **Custom Branding**, its colors (solid or gradient), and its logo.

### Genies

This is where you choose which genies appear on the portal.

* **In This Portal** lists the genies already added, with a count. Drag any genie by its grip handle to reorder how they appear on the portal, or use the trash icon to remove one. A **Featured** badge marks any genie set as featured.
* **Available Genies** shows the rest of your genies as a grid of avatars. Use the **Search genies…** box to narrow it down, then select a genie to add it to the portal. Genies already in the portal don't appear here; once every genie has been added, a note tells you so.

<Note>
  Removing a genie only takes it off this portal — the genie itself is not deleted and stays available in My Genies.
</Note>

### Share & embed

* **Portal Link** — your portal's public address, with a button to copy it.
* **Embed Code** — **Copy Embed Code** copies a snippet you can paste into your own website to embed the portal.

## If a portal can't be found

If you open a portal link that doesn't exist or that you don't have access to, you'll see a **Portal Not Found** message with a **Back to Portals** button to return to the list.


# Suite Apps
Source: https://docs.helpgenie.ai/voice-guide/suite-apps

Meet the Help Genie Suite apps — Mail, Outbound and Sync. Each is a companion app you reach from its splash page inside Genie Hub.

The Help Genie **Suite** is a set of companion apps that extend what your genies can do beyond voice. Each one lives in its own dedicated app, and inside Genie Hub you get a splash page that introduces the product and takes you there.

<Frame>
  <img alt="Suite Apps" />
</Frame>

All three apps are in **early access**, so every splash page works the same way:

* A short introduction to what the product does.
* A **Beta** badge noting it's early access.
* **Contact Sam** — books a discovery call so the team can scope the product for your business.
* **See what is possible** — opens the companion app in a new tab, already signed in with your Help Genie account.

<Note>
  Because these are early-access apps, access is arranged with the team. If **See what is possible** doesn't let you in yet, use **Contact Sam** to request access.
</Note>

## Mail

**Where to find it:** Genie Hub → Channels → Mail (`/genie-hub/channels/mail`)

Help Genie Mail brings Gmail and Outlook together into one place, then handles triage, replies and follow-ups in the background. The idea is a quiet inbox: the only messages you see are the ones that actually need you.

Mail is **invite-only** and currently onboarding teams. From the splash page:

* Select **See what is possible** to open the Mail app in a new tab (you'll arrive already signed in).
* Or select **Contact Sam** to book a call and get your team set up.

## Outbound

**Where to find it:** Genie Hub → Channels → Outbound (`/genie-hub/channels/outbound`)

Help Genie Outbound lets your genie place real phone calls and run calling campaigns end to end. Your genie dials, talks, listens, and then reports back with a transcript, a recommended next step, and the contact updated in your CRM.

From the splash page:

* Select **See what is possible** to open the Outbound app in a new tab, already signed in.
* Or select **Contact Sam** to scope a calling campaign for your business.

## Sync

**Where to find it:** Genie Hub → Channels → Sync (`/genie-hub/channels/sync`)

Sync is a bolt-on for Help Genie Voice that lets your genie act across the other tools you run. It gives your genie a secure vault of credentials, a library of reusable recipes, and a durable workflow engine — so it can read, write and take action in the systems where your work actually happens.

From the splash page:

* Select **See what is possible** to open the Sync app in a new tab, already signed in.
* Or select **Contact Sam** to talk through the workflows you'd like to connect.


# Unfinished Setups
Source: https://docs.helpgenie.ai/voice-guide/unfinished-setups

Pick up a Genie setup you started earlier but didn't finish — resume where you left off, review what you'd already covered, or remove setups you no longer want.

When you start setting up a Genie but leave before finishing, HelpGenie keeps that in‑progress setup so you don't have to start over. **Unfinished Setups** is where you find those saved setups and decide what to do with each one.

You'll find it under **Genie Hub → Unfinished Setups** (`/genie-hub/unfinished-setups`), and you can also reach it from **My Genies**. Use the **Back to My Genies** button at the top to return.

<Frame>
  <img alt="Unfinished setups list" />
</Frame>

## What you'll see

Each unfinished setup appears as its own card showing how long ago it was started (for example, "Setup started 2 days ago"). A badge next to the heading shows how many unfinished setups you have, and you can collapse or expand the list using the arrow beside it.

A setup only stays here while it's genuinely unfinished. Once a setup is completed and turns into a real Genie — or once you remove it — it drops off the list automatically. If you have no unfinished setups, the list is simply empty.

## Reviewing a setup

Not sure which setup a card refers to? Select **See details** to open a transcript of that setup, so you can read back through what you'd already gone over before deciding whether to resume or remove it.

## Resuming a setup

Select **Resume** to continue a setup from where you left off. HelpGenie reopens the guided Genie setup with your earlier answers already loaded, so you can carry on rather than begin again. The button shows a brief "Resuming…" state while it prepares your setup.

If the setup can't be reopened — for example, if its saved details are no longer available — you'll see a message letting you know, and you can start a fresh setup instead.

## Removing a setup

Select the trash icon on a card to remove that setup from the list. This clears out setups you don't intend to finish so only the ones you still care about remain. The setup disappears from the list right away, and you'll get a short confirmation that it was removed.

<Note>
  Removing a setup only takes it off this list — it doesn't affect any Genies you've already finished setting up.
</Note>

## Related

* [Genie Setup](/genie-setup-overview) — the guided flow that resuming a setup returns you to.
* [My Genies](/my-genies-list) — where your finished Genies live once a setup is complete.


# Voice Playground
Source: https://docs.helpgenie.ai/voice-guide/voice-playground

Browse, filter, preview and test the voices available for your Help Genie — then create your own custom voice to match your brand.

The Voice Playground is where you explore and test different voices for your genies. Listen to samples, compare options across accents and languages, try any voice on your own text, and create a brand-new voice when you need something unique.

You'll find it under **Genie Hub → Voice Playground** (`/genie-hub/voice-playground`). The page opens on a curated set of voices so you have somewhere to start straight away.

<Frame>
  <img alt="Voice Playground" />
</Frame>

## The header

Across the top you'll see:

* A **Voice Playground** heading with a short subtitle.
* **Create a Voice** — opens the voice creation panel (see [Creating a voice](#creating-a-voice)).
* **Refresh** — reloads the voice catalog so any newly created voices show up.
* **Learn more** — a quick link to guidance for this area.

## Browsing voices

Voices are organized into tabs:

* **Preselected** — a curated shortlist of recommended voices. This is what you see when you first open the page.
* **Favorites** — voices you've saved for quick access. See the note under [Favoriting voices](#favoriting-voices) — this feature is not yet available.
* **All Voices** — the full catalog of over 2,000 voices, loaded a page at a time. A small spinner shows on the tab while more are loading.

Under the tabs, a results summary tells you how many voices you're seeing (for example, *"Showing 12 of 40 preselected voices"*, or a matching-count line when you've searched).

### Choosing how voices are displayed

Use the view switcher (top right of the filter bar) to change the layout:

* **List** — a dense, single-line row per voice. Best for scanning many voices quickly.
* **Compact** — small cards in a grid.
* **Detailed** — larger cards showing the full description, labels, and the voice's verified languages.

### Filtering and searching

The filter bar lets you narrow the list:

* **Search voices…** — type to filter by name as you go.
* **Category**, **Accent**, **Language**, **Age**, and **Gender** — pick a value from each dropdown to filter the list. Each defaults to "All".

Active filters appear as removable chips below the bar — select a chip's **×** to drop that filter, or use **Reset All** to clear everything at once.

<Note>
  On the **All Voices** tab, filtering and searching run against the full catalog on the server. On the **Preselected** and **Favorites** tabs, they filter the voices already on screen.
</Note>

When nothing matches your filters, an empty state appears with a short hint to adjust your search or filters.

### What each voice shows

Depending on the view, a voice displays:

* A **genie avatar** — in List view, selecting the avatar plays a preview.
* The voice's **name** and quick labels: **gender**, **age**, **accent**, and **category**.
* **Language flags** for the languages the voice supports.
* A short **description** of the voice.

Longer lists don't all load at once — use **Load More** at the bottom to reveal additional voices (or the next page on the All Voices tab).

## Previewing a voice

Select the **Play** control (or the avatar in List view) to hear a short sample. A spinner shows while the sample is prepared, then it plays automatically. Selecting **Play** again on the same voice stops playback, and starting another voice stops the first.

## Testing a voice on your own text

Select **Try Text** on any voice to open the **Try this voice** panel. From there you can:

1. Type or edit the sample text (a friendly default is filled in for you).
2. Select **Generate** to create the spoken sample. It plays automatically once ready.
3. Use the **Play / Pause** and **Restart** controls to replay the sample.

This is the quickest way to hear how a voice handles your actual greeting or script before committing to it.

## Favoriting voices

Each voice has a **heart** icon intended for saving voices to your **Favorites** tab for quick access later.

<Warning>
  Favorites are not yet available. Selecting the heart currently shows a message that the feature isn't ready, and the Favorites tab will stay empty. This capability is coming in a future update — for now, use the **Preselected** and **All Voices** tabs to find voices.
</Warning>

## Creating a voice

Select **Create a Voice** in the header to open the **Create a Custom Voice** panel. It offers three ways to build a voice, each on its own tab:

### Voice Design

Describe the voice you want in plain language (tone, gender, accent, personality) and, optionally, sample text for the preview. Select **Generate previews** to get a few variations, listen to each, tick **Use this voice** on your favorite, give it a name, and select **Create voice**. Best when you don't have any audio to work from.

### Instant Clone

Create a voice from real recordings. Give it a name, optionally add a description, and upload audio samples.

* Upload **1–25 audio files** (MP3 or WAV).
* For best results use clear recordings with minimal background noise; **30 seconds to 3 minutes** of audio total is recommended.
* Leave **Clean up audio automatically** ticked if your recordings have background noise.

Select **Create instant clone** to finish. Great for keeping a consistent brand voice using an existing spokesperson or team member.

### Voice Remixing

Take a voice you've already created and adjust it — make it warmer, more energetic, or shift the accent.

* Only voices **you've created** (via Voice Design or Instant Clone) can be remixed. If you don't have any yet, the tab prompts you to create one first.
* Pick a voice, describe how it should change, and optionally add sample text (at least **100 characters**, or leave it blank to have suitable text generated for you). A live counter tells you how many more characters are needed.
* Select **Generate remix previews**, choose the variation you like, name it, and select **Create remix voice**.

<Note>
  After a voice is created you'll see a confirmation, and the panel returns you to the **Preselected** tab. Use **Refresh** if a newly created voice doesn't appear right away.
</Note>