Public Genies

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)

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

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`)

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

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`

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

Field	Type	Required	Description
`url_name`	string	Yes	URL slug of the Genie

Headers

Header	Description
`X-Agent-Access-Token`	Access 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

Field	Type	Required	Description
`url_name`	string	Yes	URL slug of the Genie
`email`	string	Yes	Requester’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

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

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

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

Response

{ "success": true }

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

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

Actions

`get`

`all`

`list`

`url`

`request-access`

`accept-invite`

`log-qr-scanned`

Error codes

​Actions

​get

​all

​list

​url

​request-access

​accept-invite

​log-qr-scanned

​Error codes

Actions

`get`

`all`

`list`

`url`

`request-access`

`accept-invite`

`log-qr-scanned`

Error codes