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.
Every request body follows this structure:
The resource to operate on (e.g. genies, knowledge-base, leads).
The operation to perform (e.g. get, all, list, create, update, delete).
The identifier of a specific record. Required for get, update, and delete actions.
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 geniesVoice AI agents. Create, configure, update, and delete genies. genie-groupsGroups for organizing genies. Supports ordering and agent counts. conversationsConversation records. Sync from the voice agent system, analyze, and manage metadata.
Knowledge Resource Description knowledge-baseDocuments that provide context to agents. Supports PDFs, websites, videos, and text. document-foldersFolders for organizing knowledge base documents.
Voice Resource Description voicesVoice discovery and favorites. Browse popular voices, track usage, and save favorites. voice-collectionsCustom collections for organizing saved voices.
CRM Resource Description leadsLeads captured during agent conversations. Includes lifecycle tracking and stats. lead-notesNotes attached to leads. Supports pinning and ordering.
Marketplace Resource Description marketplaceAgent templates available in the marketplace. Browse, create, and manage listings.
Resource Description profilesUser profiles and account data. teamsTeams with member management and invitation workflows. activitiesActivity event log for auditing and tracking.
Authorization and roles Access is controlled by three user roles:
Role Access level internal_adminFull access to all resources across all users. Can impersonate other users. standard_userAccess to their own resources only. Can create and manage agents, documents, and leads. consumerLimited 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.
