Skip to main content

​
Base URLs

HelpGenie supports both REST-style routes and direct Supabase function invocation. 
Primary: https://api.helpgenie.ai/v1
Alternative: https://helpgenie.ai/api/v1
Direct Supabase: POST https://api.helpgenie.ai/v1
REST routes follow: 
{BASE_URL}/{resource}[/{id}]

​
Authentication

All auth methods use the Authorization header. 
Authorization: Bearer <token>

Authorization: Bearer hg_live_...
  • Prefix: hg_live_
  • Rate limit: 60 requests/minute per key
  • Maximum 5 active keys per user

​
Session JWT (browser/app context)

Authorization: Bearer <supabase_access_token>

​
Service role key (server-to-server)

Authorization: Bearer <SUPABASE_SERVICE_ROLE_KEY>
x-user-id: <user-uuid>
Content-Type: application/json

​
Request formats

GET    /v1/{resource}         → action: "all"
GET    /v1/{resource}/list    → action: "list"
GET    /v1/{resource}/{id}    → action: "get"
POST   /v1/{resource}         → action: "create"
PATCH  /v1/{resource}/{id}    → action: "update"
DELETE /v1/{resource}/{id}    → action: "delete"

​
Custom actions (POST body)

POST /v1/{resource}
{
  "action": "custom-action",
  "id": "optional-id",
  "data": {}
}

​
Direct invocation (POST body)

POST https://api.helpgenie.ai/v1
{
  "resource": "genies",
  "action": "list",
  "id": null,
  "data": {}
}
​
resource
string
required
API resource name. Example: genies, knowledge-base, integrations, api-keys.
​
action
string
required
Action for the selected resource (for example list, get, create, update, delete).
​
id
string
Optional resource identifier for single-record actions.
​
data
object
Action-specific parameters (filters, pagination, payload fields).

​
Response envelope

{
  "success": true,
  "data": {
    // action-specific response data
  }
}
Error (4xx / 5xx): 
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "status": 400
  }
}

​
Error codes

CodeStatusDescription
UNAUTHORIZED401Missing or invalid Authorization header
INVALID_TOKEN401Token is invalid or expired
FORBIDDEN403User lacks permission for the resource
NOT_FOUND404Resource not found
AGENT_NOT_FOUND404Genie not found or access denied
VALIDATION_ERROR400Invalid request format or data
INVALID_ACTION400Action not supported for the resource
RATE_LIMIT_EXCEEDED429Too many requests
INTERNAL_ERROR500Server error

​
Access control

Roles determine access scope:
  • internal_admin - Full cross-account access.
  • standard_user - Access to their own business data.
  • consumer - Limited read-only/interaction access.
Admin users can pass adminMode: true or a userId parameter to operate on resources owned by other users.

​
Resource map

Genies

Create, update, list, and delete voice AI genies

Genie groups

Group and organize genies

Conversations

Sync, analyze, and manage conversations

Knowledge base

Manage documents and attach them to genies

Document folders

Organize knowledge base documents into folders

Voices

Manage voice favorites and track usage

Voice collections

Create and manage curated voice collections

Leads

Capture and manage customer leads

Lead notes

Add and manage notes on leads

Marketplace

Browse and publish genie templates

Profiles

Manage user profiles and settings

Teams

Create teams, invite members, manage roles

Activities

Track platform activity and audit logs

Goals

Manage agent goals and outcomes

API keys

Create, revoke, and delete developer API keys

Phone numbers

Provision, release, and manage Twilio phone numbers

QR codes

Manage QR code images for genie pages

Worker genies

Autonomous background AI agents for tasks and integrations

Analytics

Platform analytics, trends, and genie performance

Billing

Subscriptions, usage, invoices, and checkout

Branding

Team branding, logos, and style configuration

Portals

Create multi-genie portal pages

Agent pages

Manage individual genie landing pages

Integrations

Connect external services and APIs

Automations

Create and manage automated workflows

Playbooks

Browse and apply pre-built genie playbooks

Capabilities

Discover resources and actions at runtime