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

# 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 body="resource" type="string" required>
  Must be `"genies"`
</ParamField>

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

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="limit" type="number" default="30">
      Results per page. Maximum 500.
    </ParamField>

    <ParamField body="offset" type="number" default="0">
      Number of results to skip.
    </ParamField>

    <ParamField body="searchTerm" type="string">
      Filter genies by name or description (case-insensitive). Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="category" type="string">
      Filter by category (e.g. `"Support"`, `"Sales"`). Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="voiceLabel" type="string">
      Filter by voice label (partial match). Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="isActive" type="boolean">
      Filter by active status. Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="isPublic" type="boolean">
      Filter to public or private genies. Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="isDemoGenie" type="boolean">
      Filter to demo genies only. Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="isMarketplaceGenie" type="boolean">
      Filter to marketplace genies. Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="onlyMarketplace" type="boolean">
      When `true`, return only marketplace genies (equivalent to `isMarketplaceGenie: true`).
    </ParamField>

    <ParamField body="includeMarketplace" type="boolean">
      When `true`, include marketplace genies in results (by default they are excluded).
    </ParamField>

    <ParamField body="filters" 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 body="selectedUsername" type="string">
          Admin only. Filter by owner's full name (partial, case-insensitive match). Only applies when `adminMode` is `true`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="adminMode" type="boolean" default="false">
      Admin only. When `true`, includes owner profile in each item and allows `userId` filtering.
    </ParamField>

    <ParamField body="userId" 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 body="resource" type="string" required>
  Must be `"genies"`
</ParamField>

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

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="limit" type="number" default="30">
      Results per page, between 1 and 500.
    </ParamField>

    <ParamField body="cursor" type="string">
      Opaque pagination cursor returned from a previous request as `nextCursor`. Pass it unchanged to fetch the next page.
    </ParamField>

    <ParamField body="searchTerm" type="string">
      Filter by name or description (case-insensitive). Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="category" type="string">
      Filter by category. Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="voiceLabel" type="string">
      Filter by voice label (partial match). Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="isActive" type="boolean">
      Filter by active status. Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="isPublic" type="boolean">
      Filter to public or private genies. Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="isDemoGenie" type="boolean">
      Filter to demo genies. Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="isMarketplaceGenie" type="boolean">
      Filter to marketplace genies. Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="groupId" type="string">
      Filter by group UUID. Pass `"ungrouped"` to return genies not assigned to any group.
    </ParamField>

    <ParamField body="dailyCallLimit" type="number">
      Filter to genies with this specific daily call limit. Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="llmModel" type="string">
      Filter by the language model configured in the genie's settings. Can also be passed inside `filters`.
    </ParamField>

    <ParamField body="adminMode" type="boolean" default="false">
      Admin only. When `true`, includes owner profile information in the response.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Filter genies to those owned by a specific user.
    </ParamField>

    <ParamField body="role" 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 body="resource" type="string" required>
  Must be `"genies"`
</ParamField>

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

<ParamField body="id" type="string" required>
  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 body="resource" type="string" required>
  Must be `"genies"`
</ParamField>

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

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="genieName" type="string" required>
      Display name for the genie.
    </ParamField>

    <ParamField body="useCase" type="string" required>
      Primary use case describing what the genie does.
    </ParamField>

    <ParamField body="systemPrompt" type="string" required>
      System prompt defining the genie's behavior and personality.
    </ParamField>

    <ParamField body="firstMessage" type="string" required>
      Initial greeting message spoken when a conversation starts.
    </ParamField>

    <ParamField body="webWelcomeMessage" type="string" required>
      Welcome message displayed on the web interface before a call begins.
    </ParamField>

    <ParamField body="voiceId" type="string">
      Voice identifier. Defaults to the platform default voice.
    </ParamField>

    <ParamField body="llmModel" type="string" default="gemini-3-flash-preview">
      Language model identifier.
    </ParamField>

    <ParamField body="temperature" type="number" default="0.7">
      Model temperature between 0 and 2.
    </ParamField>

    <ParamField body="maxTokens" type="number" default="8000">
      Maximum number of tokens in the response.
    </ParamField>

    <ParamField body="isMultilingual" type="boolean" default="true">
      Enable multilingual voice support.
    </ParamField>

    <ParamField body="voiceStability" type="number" default="0.5">
      Voice stability between 0 and 1.
    </ParamField>

    <ParamField body="voiceSimilarity" type="number" default="0.8">
      Voice similarity between 0 and 1.
    </ParamField>

    <ParamField body="speechSpeed" type="number" default="1.0">
      Speech speed multiplier.
    </ParamField>

    <ParamField body="conversationSettings" type="object">
      <Expandable title="properties">
        <ParamField body="maxDuration" type="number" default="600">
          Maximum conversation duration in seconds.
        </ParamField>

        <ParamField body="turnTimeout" type="number" default="7">
          Seconds before a turn times out.
        </ParamField>

        <ParamField body="silenceTimeout" type="number" default="30">
          Seconds of silence before ending the call.
        </ParamField>

        <ParamField body="turnMode" type="string" default="silence">
          Turn detection mode.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="brand" type="string">
      Brand or company name.
    </ParamField>

    <ParamField body="category" type="string">
      Genie category or type.
    </ParamField>

    <ParamField body="description" type="string">
      Detailed description of the genie.
    </ParamField>

    <ParamField body="supportEmails" type="string[]">
      Email addresses for the support team.
    </ParamField>

    <ParamField body="sendConversationReports" type="boolean" default="true">
      Send email reports after each conversation.
    </ParamField>

    <ParamField body="attachPhoneNumber" type="boolean" default="false">
      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 body="resource" type="string" required>
  Must be `"genies"`
</ParamField>

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

<ParamField body="id" type="string" required>
  The UUID of the genie to update.
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="name" type="string">
      Updated genie name.
    </ParamField>

    <ParamField body="description" type="string">
      Updated description.
    </ParamField>

    <ParamField body="settings" type="object">
      Nested settings object. Fields are merged, not replaced.

      <Expandable title="properties">
        <ParamField body="conversation_config" type="object">
          <Expandable title="properties">
            <ParamField body="agent" type="object">
              <Expandable title="properties">
                <ParamField body="first_message" type="string">Updated greeting.</ParamField>

                <ParamField body="prompt" type="object">
                  <Expandable title="properties">
                    <ParamField body="prompt" type="string">Updated system prompt.</ParamField>
                    <ParamField body="temperature" type="number">Model temperature (0–2).</ParamField>
                    <ParamField body="max_tokens" type="number">Max response tokens.</ParamField>
                  </Expandable>
                </ParamField>
              </Expandable>
            </ParamField>

            <ParamField body="tts" type="object">
              <Expandable title="properties">
                <ParamField body="voice_id" type="string">New voice identifier for the voice platform.</ParamField>
                <ParamField body="stability" type="number">Voice stability (0–1).</ParamField>
                <ParamField body="similarity_boost" type="number">Voice similarity (0–1).</ParamField>
                <ParamField body="speed" type="number">Speech speed multiplier.</ParamField>
              </Expandable>
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="branding" 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 body="resource" type="string" required>
  Must be `"genies"`
</ParamField>

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

<ParamField body="id" type="string" required>
  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 body="resource" type="string" required>
  Must be `"genies"`
</ParamField>

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

<ParamField body="id" type="string" required>
  The UUID of the genie to clone.
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="name" type="string">
      Name for the cloned genie. Defaults to `"Copy of {original name}"`.
    </ParamField>

    <ParamField body="promptReplacements" type="array">
      Array of string replacements applied to the system prompt and first message. Useful for white-labeling.

      <Expandable title="item properties">
        <ParamField body="from" type="string" required>Text to find.</ParamField>
        <ParamField body="to" type="string" required>Replacement text.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="userId" 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 body="resource" type="string" required>
  Must be `"genies"`
</ParamField>

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

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="sort" type="object" required>
      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 body="action" type="string" required>
  `analytics`
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="adminMode" type="boolean">
      Admin only. Return analytics across all users.
    </ParamField>

    <ParamField body="userId" 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 body="action" type="string" required>
  `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 body="action" type="string" required>
  `timeline`
</ParamField>

<ParamField body="id" type="string" required>
  Genie UUID.
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="startDate" type="string" required>
      ISO 8601 start date (inclusive).
    </ParamField>

    <ParamField body="endDate" type="string" required>
      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 body="action" type="string" required>
  `url`
</ParamField>

<ParamField body="id" type="string" required>
  Genie UUID.
</ParamField>

***

## Embed code

Returns an HTML embed snippet for embedding a genie on an external website.

<ParamField body="action" type="string" required>
  `embed-code`
</ParamField>

<ParamField body="id" type="string" required>
  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 body="action" type="string" required>
  `request-access`
</ParamField>

<ParamField body="id" type="string" required>
  Genie UUID.
</ParamField>

***

## Accept invite

Accepts an invitation to access a genie using an access token.

<ParamField body="action" type="string" required>
  `accept-invite`
</ParamField>

<ParamField body="id" type="string" required>
  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                     |