Introduction - Help Genie

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

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.

{
  "resource": "genies",
  "action": "get",
  "id": "abc-123"
}

The API also supports standard REST-style HTTP method routing as an alternative. See Making requests for details on both approaches.

Request and response format

Every request body follows this structure:

string

required

The resource to operate on (e.g. genies, knowledge-base, leads).

string

required

The operation to perform (e.g. get, all, list, create, update, delete).

string

The identifier of a specific record. Required for get, update, and delete actions.

object

The payload for create and update actions. Contents vary by resource.

Every response uses a consistent envelope:

{
  "success": true,
  "data": { ... }
}

On failure, the response includes an error object instead:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404
  }
}

See Error handling 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

Authentication

Get a Bearer token and authenticate your first request.

Making requests

Learn about request patterns, list vs all, and admin mode.

Help Genie Voice guide

Not building an integration? Learn to use the Help Genie Voice product.

​Two kinds of documentation

​Single endpoint architecture

​Request and response format

​Available resources

​Agents

​Knowledge

​Voice

​CRM

​Marketplace

​Platform

​Authorization and roles

​Next steps

Authentication

Making requests

Help Genie Voice guide

Two kinds of documentation

Single endpoint architecture

Request and response format

Available resources

Agents

Knowledge

Voice

CRM

Marketplace

Platform

Authorization and roles

Next steps