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.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.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.Create genie
Creates a new voice AI genie with the specified configuration. The genie is automatically provisioned in the voice agent system.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.Delete genie
Permanently deletes a genie, removes it from the voice agent system, releases any associated phone numbers, and permanently deletes its email mailbox.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.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).Analytics
Returns conversation analytics per genie — total conversations, recent conversations (last 7 days), and last-used timestamp.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).Response
Inactive genies (admin)
Admin only. Lists genies across the platform that have had no conversation for at leastdays, 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.
Response
Returns
FORBIDDEN for non-admin callers.Timeline
Returns a day-by-day conversation count for a genie over a specified date range.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 returnNOT_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.Embed code
Returns an HTML embed snippet for embedding a genie on an external website.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.Accept invite
Accepts an invitation to access a genie using an access token.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 setsoutbound_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).
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 defaultsignatureStyle 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.

