Documentation Index
Fetch the complete documentation index at: https://docs.helpgenie.ai/llms.txt
Use this file to discover all available pages before exploring further.
These routes use resource: "genies" and require no API key. They are intended for consumer-facing surfaces — embedded widgets, public genie pages, QR code landing pages, and marketplace listings.
Only Genies with is_public: true (or is_marketplace_genie: true) are returned. Private Genies can be accessed via the url action by passing a valid X-Agent-Access-Token header.
Actions
get
Returns a single public Genie by UUID, including its page and QR code data.
Parameters
| Field | Type | Required | Description |
|---|
id | string | Yes | Genie UUID (request ID) |
{
"agent": {
"id": "agent-uuid",
"name": "Support Genie",
"description": "AI-powered support assistant",
"elevenlabs_id": "el-agent-id",
"is_active": true,
"is_public": true,
"category": "Support",
"branding": { },
"agent_pages": { },
"saved_qr_codes": [ ]
}
}
AGENT_NOT_FOUND if the Genie does not exist or is not public.
all
Paginated list of public Genies with full data (including page and QR codes). Supports search and filtering.
Parameters
| Field | Type | Required | Description |
|---|
search / name | string | No | Case-insensitive name search |
category | string | No | Filter by category |
is_marketplace_genie | boolean | No | Filter to marketplace Genies only |
is_demo_genie | boolean | No | Filter to demo Genies only |
limit | number | No | Results per page (default 30) |
offset | number | No | Pagination offset (default 0) |
{
"agents": [ /* full Genie objects */ ],
"count": 42,
"limit": 30,
"offset": 0
}
list
Paginated list of public Genies with a lightweight field set — suitable for dropdowns and catalogue views.
Parameters
| Field | Type | Required | Description |
|---|
searchTerm | string | No | Searches name and description |
category | string | No | Filter by category |
is_marketplace_genie | boolean | No | Filter to marketplace Genies |
is_demo_genie | boolean | No | Filter to demo Genies |
limit | number | No | Default 30 |
offset | number | No | Default 0 |
{
"agents": [
{
"id": "agent-uuid",
"name": "Support Genie",
"description": "...",
"elevenlabs_id": "el-agent-id",
"is_active": true,
"category": "Support",
"branding": { },
"created_at": "2024-01-01T00:00:00Z"
}
],
"count": 42,
"limit": 30,
"offset": 0
}
url
Loads a Genie by its URL slug (url_name). Used by the embedded widget and genie page to bootstrap a conversation. Validates access for private Genies via an access token.
Parameters
| Field | Type | Required | Description |
|---|
url_name | string | Yes | URL slug of the Genie |
| Header | Description |
|---|
X-Agent-Access-Token | Access grant token for private Genies. Required if the Genie is not public. |
{
"agent": { /* full Genie object with page, QR codes, and access grants */ }
}
is_public: false and no valid token):
{
"success": false,
"error": {
"code": "GENIE_PRIVATE",
"message": "This Genie is private",
"status": 403,
"genieName": "Support Genie"
}
}
agent_access_grants — expired or exhausted grants are rejected. Each valid use increments the grant’s use_count.
request-access
Submits an access request for a private Genie identified by URL slug. Notifies the Genie owner by email. If the requester does not have an account, one is created automatically and a welcome email with a set-password link is sent.
Parameters
| Field | Type | Required | Description |
|---|
url_name | string | Yes | URL slug of the Genie |
email | string | Yes | Requester’s email address |
is_public: false). Returns VALIDATION_ERROR if the Genie is already public.
accept-invite
Accepts an invitation to access a Genie. Grants the user direct access via agent_users and links the Genie to their consumer profile. If the user does not have an account, one is created and a welcome email is sent.
Parameters
| Field | Type | Required | Description |
|---|
url_name | string | Yes | URL slug of the Genie |
email | string | Yes | Invitee’s email address |
agent_id | string | Yes | Genie UUID |
{
"success": true,
"consumerId": "user-uuid"
}
log-qr-scanned
Logs a QR code scan event to the activity feed. Optionally associates the scan with a known consumer.
Parameters
| Field | Type | Required | Description |
|---|
genieId | string | Yes | Genie UUID |
genieName | string | No | Genie name (for the activity log title) |
urlName | string | No | URL slug |
consumerId | string | No | UUID of the authenticated consumer, if known |
Error codes
| Code | Meaning |
|---|
VALIDATION_ERROR | Missing required parameter or invalid request |
NOT_FOUND | Genie not found |
AGENT_NOT_FOUND | Genie not found or not public |
GENIE_PRIVATE | Genie is private and no valid access token was provided |
FORBIDDEN | Access denied |
INTERNAL_ERROR | Unexpected server error |
