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

# Voices

> Browse and search voices, manage favorites, and track voice usage

## List voices

Retrieves all available voices from the voice library.

<ParamField body="resource" type="string" required>
  `voices`
</ParamField>

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

<ParamField body="data" 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 body="resource" type="string" required>
  `voices`
</ParamField>

<ParamField body="action" type="string" required>
  `list-shared`
</ParamField>

<ParamField body="data" 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 body="resource" type="string" required>
  `voices`
</ParamField>

<ParamField body="action" type="string" required>
  `search`
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="terms" type="string[]" required>
      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 body="resource" type="string" required>
  `voices`
</ParamField>

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

<ParamField body="action" type="string" required>
  `add-favorite`
</ParamField>

<ParamField body="id" type="string" required>
  The voice ID to add to favorites.
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="voice_data" 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 body="resource" type="string" required>
  `voices`
</ParamField>

<ParamField body="action" type="string" required>
  `remove-favorite`
</ParamField>

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

<ParamField body="action" type="string" required>
  `track-usage`
</ParamField>

<ParamField body="id" type="string" required>
  The voice ID to track usage for.
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="context" 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 body="agentId" 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>