Skip to main content
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
FieldTypeRequiredDescription
idstringYesGenie UUID (request ID)
Response 
{
  "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": [ ]
  }
}
Returns 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
FieldTypeRequiredDescription
search / namestringNoCase-insensitive name search
categorystringNoFilter by category
is_marketplace_geniebooleanNoFilter to marketplace Genies only
is_demo_geniebooleanNoFilter to demo Genies only
limitnumberNoResults per page (default 30)
offsetnumberNoPagination offset (default 0)
Response 
{
  "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
FieldTypeRequiredDescription
searchTermstringNoSearches name and description
categorystringNoFilter by category
is_marketplace_geniebooleanNoFilter to marketplace Genies
is_demo_geniebooleanNoFilter to demo Genies
limitnumberNoDefault 30
offsetnumberNoDefault 0
Response 
{
  "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
FieldTypeRequiredDescription
url_namestringYesURL slug of the Genie
Headers
HeaderDescription
X-Agent-Access-TokenAccess grant token for private Genies. Required if the Genie is not public.
Response 
{
  "agent": { /* full Genie object with page, QR codes, and access grants */ }
}
Private Genie error (when is_public: false and no valid token): 
{
  "success": false,
  "error": {
    "code": "GENIE_PRIVATE",
    "message": "This Genie is private",
    "status": 403,
    "genieName": "Support Genie"
  }
}
Access tokens are validated against 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
FieldTypeRequiredDescription
url_namestringYesURL slug of the Genie
emailstringYesRequester’s email address
Response 
{ "success": true }
Only valid for private Genies (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
FieldTypeRequiredDescription
url_namestringYesURL slug of the Genie
emailstringYesInvitee’s email address
agent_idstringYesGenie UUID
Response 
{
  "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
FieldTypeRequiredDescription
genieIdstringYesGenie UUID
genieNamestringNoGenie name (for the activity log title)
urlNamestringNoURL slug
consumerIdstringNoUUID of the authenticated consumer, if known
Response 
{ "success": true }

​
Error codes

CodeMeaning
VALIDATION_ERRORMissing required parameter or invalid request
NOT_FOUNDGenie not found
AGENT_NOT_FOUNDGenie not found or not public
GENIE_PRIVATEGenie is private and no valid access token was provided
FORBIDDENAccess denied
INTERNAL_ERRORUnexpected server error