# Help Genie API

> AI voice agent platform. Create and manage AI voice agents (Genies) that handle phone
> calls, capture leads, run automations, and integrate with 3000+ apps.

## Docs

- https://helpgenie.ai/docs: Full API reference (human-readable)
- https://helpgenie.ai/openapi.yaml: OpenAPI 3.1 specification (machine-readable)

## Base URL

```
https://api.helpgenie.ai/v1
```

## Authentication

Two equivalent methods — use whichever your HTTP client supports:

### Option A: Authorization Header (most common)
```
Authorization: Bearer hg_live_YOUR_KEY
```

### Option B: X-API-Key Header
```
X-API-Key: hg_live_YOUR_KEY
```

**Key details:**
- API keys have the `hg_live_` prefix (standard) 
- Rate limit: 60 requests/minute per key
- Get a key: Log in to Help Genie → Settings → API Keys → Create Key
- API keys carry the same permissions as the user who created them
- To manage API keys themselves, you must use a session JWT (not an API key)

### First Request Test

```bash
curl https://api.helpgenie.ai/v1/genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY"
```

Expected response:
```json
{
  "success": true,
  "data": {
    "data": [...],
    "nextCursor": "2024-01-14T15:20:00.000Z",
    "hasMore": true,
    "total": 5
  }
}
```

If you get an error, check the error codes section below for troubleshooting.

## Request/Response Format

Standard REST: `GET /v1/{resource}`, `GET /v1/{resource}/{id}`, `POST`, `PATCH`, `DELETE`

Custom actions use POST with an `action` field in the body:
```json
POST /v1/{resource}
{ "action": "custom-action-name", "id": "optional-id", "data": { ... } }
```

Success response:
```json
{ "success": true, "data": { ... } }
```

Error response:
```json
{ "success": false, "error": { "code": "ERROR_CODE", "message": "Human-readable description", "status": 400 } }
```

## Pagination

Two patterns are used:

### Cursor-based (GET /v1/{resource})
```json
// Request
GET /v1/genies?limit=10

// Response
{
  "success": true,
  "data": {
    "data": [...],
    "nextCursor": "2024-01-14T15:20:00.000Z",
    "hasMore": true,
    "total": 42
  }
}

// Next page
GET /v1/genies?limit=10&cursor=2024-01-14T15:20:00.000Z
```

### Offset-based (GET /v1/{resource}/list)
```json
// Request
GET /v1/genies/list?limit=10&offset=0

// Response
{
  "success": true,
  "data": {
    "genies": [...],
    "count": 42,
    "limit": 10,
    "offset": 0
  }
}
```

## Error Codes

| Code | Status | Description | What to do |
|------|--------|-------------|------------|
| UNAUTHORIZED | 401 | No auth header provided | Add `Authorization: Bearer hg_live_YOUR_KEY` or `X-API-Key: hg_live_YOUR_KEY` |
| INVALID_KEY_PREFIX | 401 | Key doesn't start with `hg_live_` | Check your API key format |
| KEY_NOT_FOUND | 401 | Key not found or revoked | Generate a new key at Settings → API Keys |
| INVALID_TOKEN | 401 | Token is invalid or expired | Check your API key or session token |
| FORBIDDEN | 403 | User lacks permission | Check role-based access |
| NOT_FOUND | 404 | Resource not found | Verify the resource ID |
| VALIDATION_ERROR | 400 | Invalid request format | Check required fields and data types |
| INVALID_ACTION | 400 | Action not supported | Check the resource's supported actions below |
| RATE_LIMIT_EXCEEDED | 429 | Too many requests | Wait and retry; limit is 60 req/min per key |
| INTERNAL_ERROR | 500 | Server error | Retry or contact support |

## Public Resources

### Public Agents — `/public/genies` (no authentication required)
Publicly available agents and marketplace genies.
- `GET /public/genies/all` — full list with relationships (params: limit, offset, search, name, is_marketplace_genie, category)
- `GET /public/genies/list` — slim list (id, name, description, category, branding) (params: limit, offset, searchTerm, is_marketplace_genie, category)
- `GET /public/genies/{id}` — full detail for a public agent

## Resources

### Genies — `/v1/genies`
AI voice agents. Core resource of the platform.
- `GET /v1/genies` — paginated list (params: limit, cursor)
- `GET /v1/genies/list` — slim list (id, name, category, is_active)
- `GET /v1/genies/{id}` — full detail including phone, page, knowledge_base
- `POST /v1/genies` — create (required: genieName, useCase, systemPrompt, firstMessage, webWelcomeMessage)
- `PATCH /v1/genies/{id}` — update
- `DELETE /v1/genies/{id}` — delete
- Custom actions: `reorder` — batch reorder positions, `clone` — clone existing genie configuration

### Genie Groups — `/v1/genie-groups`
Organize genies into named groups.
- `GET /v1/genie-groups` — list all groups
- `GET /v1/genie-groups/{id}` — get group
- `POST /v1/genie-groups` — create (required: name)
- `PATCH /v1/genie-groups/{id}` — update
- `DELETE /v1/genie-groups/{id}` — delete
- Custom actions: `reorder`, `counts` (agent count per group), `sync` (assign genie to group)

### Knowledge Base — `/v1/knowledge-base`
Documents attached to genies for context.
- `GET /v1/knowledge-base` — list (filters: searchTerm, folderId, limit, offset)
- `GET /v1/knowledge-base/{id}` — get document
- `POST /v1/knowledge-base` — create document
- `PATCH /v1/knowledge-base/{id}` — update (mode: "data" for metadata, "content" for re-upload)
- `DELETE /v1/knowledge-base/{id}` — delete
- Custom actions: `attach` (add docs to genie KB), `detach`, `replace` (replace entire KB), `sync-with-agents`

### Conversations — `/v1/conversations`
Call records from genie interactions.
- `GET /v1/conversations` — list (filters: agentId, limit, offset)
- `GET /v1/conversations/{id}` — get conversation
- `PATCH /v1/conversations/{id}` — update
- `DELETE /v1/conversations/{id}` — delete
- Custom actions: `sync` (pull from ElevenLabs, requires agentId), `analyze` (AI analysis, requires id)

### Leads — `/v1/leads`
Contacts captured during calls.
- `GET /v1/leads` — list (filters: agentId, status, searchTerm, dateRange, limit, offset)
- `GET /v1/leads/{id}` — get lead
- `POST /v1/leads` — create
- `PATCH /v1/leads/{id}` — update (status, priority, notes, etc.)
- `DELETE /v1/leads/{id}` — delete
- Custom actions: `stats` (aggregated counts by status), `log`, `getLogs`
- Status values: new, contacted, qualified, converted

### Lead Notes — `/v1/lead-notes`
Notes attached to leads.
- `GET /v1/lead-notes?leadId={id}` — list notes for a lead
- `GET /v1/lead-notes/{id}` — get note
- `POST /v1/lead-notes` — create (required: data.leadId, data.content)
- `PATCH /v1/lead-notes/{id}` — update (content, is_pinned)
- `DELETE /v1/lead-notes/{id}` — delete
- Custom actions: `togglePin`, `pinned` (get all pinned for a lead)

### Insights — `/v1/insights`
Conversation insight presets — define what information to extract from conversations.
- `GET /v1/insights` — list (filters: searchTerm, limit, offset)
- `GET /v1/insights/{id}` — get insight
- `POST /v1/insights` — create (required: name; optional: description, fields)
- `PATCH /v1/insights/{id}` — update
- `DELETE /v1/insights/{id}` — delete
- `POST /v1/insights?action=attach` — attach insight to a genie (required: agentId, insightId)
- `POST /v1/insights?action=detach` — detach insight from a genie (required: agentId)
- `POST /v1/insights?action=generate` — generate insight fields from a description using AI (required: description; optional: genieContext)

### API Keys — `/v1/api-keys`
Manage developer API keys. Requires session JWT (not an API key).
- `GET /v1/api-keys` — list keys (full key never returned)
- `POST /v1/api-keys` — create key (name required; full key returned once only)
- `PATCH /v1/api-keys/{id}` — revoke key
- `DELETE /v1/api-keys/{id}` — permanently delete key
- Limit: max 5 active keys per user

### Analytics — `/v1/analytics`
Usage metrics and trends.
- `GET /v1/analytics` — overview (genie count, conversation count, lead count, doc count)
- Custom actions: `trends` (daily points, period: 7d/30d/90d), `genie-performance`, `compare`

### Billing — `/v1/billing`
Subscription and payment management.
- `GET /v1/billing` — current plan, phone subscriptions, call purchases
- Custom actions: `usage`, `invoices`, `checkout`, `billing-portal`, `update-subscription`,
  `sync`, `purchase-calls`, `cancel-calls`, `add-phone-number`, `remove-phone-number`

### Branding — `/v1/branding`
White-label branding settings.
- `GET /v1/branding` — get settings
- Custom actions: `update` (with data object), `clear`, `generate-logo`

### Generate-Logo — via Image Handler
AI-powered logo generation (handled by the `image-handler` edge function with `action: generate-logo`).
- `POST /v1/branding` with `action: generate-logo` — generate logo (required: name; optional: description, style, industry)
  - Returns: image_url, storage_path, replicate_prediction_id
  - Styles: modern, classic, bold, friendly, tech, luxury
  - Industries: automotive, marine, appliances, office-equipment, home-builders, travel-hospitality, trades, plumbing, electrical, hvac, landscaping, real-estate, healthcare, fitness, restaurant, retail, technology, education, finance, legal

### Voices — `/v1/voices`
ElevenLabs voice management.
- Custom actions (all POST): `favorites`, `popular`, `recent`,
  `add-favorite` (id + data.voice_data), `remove-favorite` (id), `track-usage` (id + data.context)

### Voice Collections — `/v1/voice-collections`
Curated voice packs.
- `GET /v1/voice-collections` — list (filters: isPublic, isFeatured)
- `GET /v1/voice-collections/{id}` — get collection
- `POST /v1/voice-collections` — create (name, voice_ids[], is_public)
- `PATCH /v1/voice-collections/{id}` — update
- `DELETE /v1/voice-collections/{id}` — delete

### Activities — `/v1/activities`
Platform audit log (read-mostly).
- `GET /v1/activities` — list (filters: category, activityType, action, startDate, endDate, resourceType, resourceId)
- `GET /v1/activities/{id}` — get activity
- `POST /v1/activities` — create (admin/service-role only; required: activity_type, action, title)

### Marketplace — `/v1/marketplace`
Genie template marketplace.
- `GET /v1/marketplace` — list (filters: category, search, featured, sortBy)
- `GET /v1/marketplace/{id}` — get listing by slug or UUID
- Custom actions: `categories`, `stats`, `reviews`, `favorites`, `collections`, `submissions`, `trending`, `clone`
- Create/update/delete: admin only

### Profiles — `/v1/profiles`
User profile management.
- `GET /v1/profiles/{id}` — get profile (self or admin)
- `PATCH /v1/profiles/{id}` — update profile
- `GET /v1/profiles` — list all (admin only)
- `POST /v1/profiles` — create profile
- `DELETE /v1/profiles/{id}` — delete profile

### Phone Numbers — `/v1/phone-numbers`
Phone provisioning and number operations.
- `GET /v1/phone-numbers` — list numbers
- `GET /v1/phone-numbers/list` — slim list for selectors
- `GET /v1/phone-numbers/{id}` — get number detail
- `PATCH /v1/phone-numbers/{id}` — update number settings
- Custom actions: `stats`, `export`, `provision`, `release`

### Teams — `/v1/teams`
Team and member management.
- `GET /v1/teams/{id}` — get team + members
- `POST /v1/teams` — create (required: name, brand)
- `PATCH /v1/teams/{id}` — update
- `DELETE /v1/teams/{id}` — delete + cleanup
- Custom actions: `members`, `invite` (data.email), `invitations`, `cancel-invite`, `remove-member` (data.memberId)

### Document Folders — `/v1/document-folders`
Organize knowledge documents into folders.
- `GET /v1/document-folders` — list all
- `GET /v1/document-folders/{id}` — get folder
- `POST /v1/document-folders` — create (required: name; optional: color, icon)
- `PATCH /v1/document-folders/{id}` — update
- `DELETE /v1/document-folders/{id}` — delete
- Custom actions: `reorder`, `counts`

### Portals — `/v1/portals`
Multi-genie portal landing pages.
- CRUD: `GET`, `POST`, `PATCH`, `DELETE`
- Custom actions: `reorder`, `add-genie`, `remove-genie`, `reorder-genies`, `share-url`, `embed-code`

### Agent Pages — `/v1/agent-pages`
Single-genie dedicated landing pages.
- CRUD: `GET`, `POST`, `PATCH`, `DELETE`
- Custom actions: `embed-code`, `qr-code`

### Playbooks — `/v1/playbooks`
Pre-built agent configuration templates.
- `GET /v1/playbooks` — list
- `GET /v1/playbooks/{id}` — get playbook
- Custom actions: `categories`, `apply`

### Activation Packs — `/v1/activation-packs`
Bundled setup resources for quick deployment.
- CRUD: `GET`, `POST`, `PATCH`, `DELETE`
- Custom action: `generate-assets`

### Demo Genies — `/v1/demo-genies`
Sandbox/demo genie instances.
- CRUD: `GET`, `POST`, `PATCH`, `DELETE`
- Custom action: `provision`

### Email Templates — `/v1/email-templates`
Email notification templates.
- CRUD: `GET`, `POST`, `PATCH`, `DELETE`

### Email Logs — `/v1/email-logs`
Sent email history (read-only).
- `GET /v1/email-logs` — list
- `GET /v1/email-logs/{id}` — get log entry

## Quick Examples

```bash
# List your genies
curl https://api.helpgenie.ai/v1/genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY"

# Same request with X-API-Key header
curl https://api.helpgenie.ai/v1/genies \
  -H "X-API-Key: hg_live_YOUR_KEY"

# Create a genie
curl -X POST https://api.helpgenie.ai/v1/genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "genieName": "Support Bot",
    "useCase": "customer_support",
    "systemPrompt": "You are a helpful support agent.",
    "firstMessage": "Hi! How can I help you today?",
    "webWelcomeMessage": "Welcome to support!"
  }'

# List leads from a specific genie
curl "https://api.helpgenie.ai/v1/leads?agentId=GENIE_UUID&status=new" \
  -H "Authorization: Bearer hg_live_YOUR_KEY"

# Get analytics trends
curl -X POST https://api.helpgenie.ai/v1/analytics \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "trends", "data": { "period": "30d" } }'

# Custom action example (sync conversations)
curl -X POST https://api.helpgenie.ai/v1/conversations \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "sync", "data": { "agentId": "GENIE_UUID" } }'
```