Skip to main content
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.
Standard users can only manage their own genies. Admin users can manage all genies and view owner information by passing adminMode: true.

List genies

Retrieves a paginated list of genies with essential fields. Optimized for selects, dropdowns, and summary views. Results cover the genies you own. If your account belongs to a workspace, genies owned by the workspace owner are included as well.
string
required
Must be "genies"
string
required
Must be "list"
object
boolean
Whether the request succeeded.
object

Get all genies

Retrieves all genies with full configuration using cursor-based pagination. Returns complete genie objects including settings, phone, group, and knowledge base data.
string
required
Must be "genies"
string
required
Must be "all"
object
boolean
Whether the request succeeded.
object
When adminMode is true, each genie includes an owner field with id, full_name, email, and role. Standard users always see owner: null.

Get genie

Retrieves a single genie by ID with its full configuration, including settings, phone number, group, and knowledge base.
string
required
Must be "genies"
string
required
Must be "get"
string
required
The UUID of the genie to retrieve.
object
boolean
Whether the request succeeded.
object

Create genie

Creates a new voice AI genie with the specified configuration. The genie is automatically provisioned in the voice agent system.
string
required
Must be "genies"
string
required
Must be "create"
object
required
boolean
Whether the request succeeded.
string
Confirmation message.
object
Admin users can create genies on behalf of other users by including impersonatedUserId in the data object.

Update genie

Updates an existing genie’s configuration. Supports partial updates — only the fields you include will be changed.
string
required
Must be "genies"
string
required
Must be "update"
string
required
The UUID of the genie to update.
object
required
boolean
Whether the request succeeded.
string
Confirmation message.
object

Delete genie

Permanently deletes a genie, removes it from the voice agent system, releases any associated phone numbers, and permanently deletes its email mailbox.
string
required
Must be "genies"
string
required
Must be "delete"
string
required
The UUID of the genie to delete.
boolean
Whether the request succeeded.
string
Confirmation message.
This action is irreversible. The genie, its external agent instance, and any attached phone numbers will be permanently removed.

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.
string
required
Must be "genies"
string
required
Must be "clone"
string
required
The UUID of the genie to clone.
object
boolean
Whether the request succeeded.
object
Escalation recipients, goal associations and the insight detail level (goal_collection_effort) are always copied; phone numbers never are. The clone keeps the original’s silence end-call timeout exactly, including Off (-1); only a genie with no timeout set gets the 5-minute (300 seconds) default. Knowledge base documents are copied unless copyKnowledgeBase is false. A failed knowledge base or Resources copy does not fail the clone — the genie is still created, and report shows what was skipped. Non-admins can only clone genies they own directly; team genies return AGENT_NOT_FOUND. If the new genie would end up on any account other than the target, it is deleted and the call fails with INTERNAL_ERROR, so a clone never lands on the wrong account. A clone that timed out may still have been created — check the genie list before retrying.

Reorder genies

Updates the display order of genies. Pass an object mapping genie IDs to their desired position (zero-indexed).
string
required
Must be "genies"
string
required
Must be "reorder"
object
required
boolean
Whether the request succeeded.
string
Confirmation message.

Analytics

Returns conversation analytics per genie — total conversations, recent conversations (last 7 days), and last-used timestamp.
string
required
analytics
object

Response

Returns an array of analytics objects (one per genie):
array

Limits

Returns the genie quota for the authenticated user’s personal account and, if applicable, their workspace (team).
string
required
limits

Response

object

Inactive genies (admin)

Admin only. Lists genies across the platform that have had no conversation for at least days, least recently active first, so unused genies can be reviewed and cleaned up. A genie that never had a conversation counts from when it was created. Setup templates are always left out. Demo and marketplace genies are listed only when you ask for them. Delete the ones you pick with Delete genie.
string
required
admin-inactive
object

Response

object[]
Matching genies.
number
Total number of matching genies.
number
The inactivity threshold used.
number
Page size used.
number
Offset used.
Returns FORBIDDEN for non-admin callers.

Timeline

Returns a day-by-day conversation count for a genie over a specified date range.
string
required
timeline
string
required
Genie UUID.
object
required

Response


URL lookup (authenticated)

Loads a genie by its URL slug. Used by authenticated surfaces (the widget, the genie page, team members) to bootstrap a conversation. Returns the full genie object and, for consumer users where memory is enabled, the caller’s stored memory context. Access is granted when the caller is the genie’s owner, an admin, a workspace team member, holds a valid time-limited access grant, or the genie is public or a marketplace genie. Inactive genies return NOT_FOUND even when access would otherwise be allowed.
For fully public (unauthenticated) genie loading — used by embedded widgets before a user signs in — use the url action on the public genies resource instead.
string
required
Must be "genies"
string
required
Must be "url"
object
required
boolean
Whether the request succeeded.
object
Private genie error (when access is not allowed):

Embed code

Returns an HTML embed snippet for embedding a genie on an external website.
string
required
embed-code
string
required
Genie UUID.

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.
string
required
request-access
string
required
Genie UUID.

Accept invite

Accepts an invitation to access a genie using an access token.
string
required
accept-invite
string
required
Genie UUID.

Outbound connection

Records whether a genie is connected to a Help Genie Outbound workspace. Help Genie Outbound calls this automatically when a genie is connected, disconnected or resynced, using the genie owner’s API key. Connecting sets outbound_connected_at; connecting a genie that is already connected keeps the original timestamp. Disconnecting clears it. While a genie is connected, its genie page shows the visitor callback form. Requires access to the genie (owner, team member or admin).
string
required
Must be "genies"
string
required
Must be "outbound-connection"
object
required
string
The genie UUID.
string
ISO 8601 timestamp of when the genie was connected, or null after disconnecting.
Returns VALIDATION_ERROR when agentId is missing or connected is not a boolean, and UNAUTHORIZED when the caller has no access to the genie.

Signature style

Retrieves and, if necessary, initializes a genie’s email signature style. Fills in a default signatureStyle object when absent, and always refreshes the phoneNumber and liveUrl snapshots within signatureStyle to match the genie’s current phone and public URL. Once signatureStyle exists, only the snapshot fields are ever refreshed — layout preferences and toggle states set by the user are never overwritten. Other branding fields (colors, logo) are never modified by this action.
string
required
Must be "genies"
string
required
Must be "signature-style"
string
required
The UUID of the genie.
boolean
Whether the request succeeded.
object

Error codes