> ## 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.

# Public Genies

> Unauthenticated endpoints for loading, browsing, and interacting with 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**

```json theme={null}
{
  "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**

```json theme={null}
{
  "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**

```json theme={null}
{
  "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**

```json theme={null}
{
  "agent": { /* full Genie object with page, QR codes, and access grants */ }
}
```

**Private Genie error** (when `is_public: false` and no valid token):

```json theme={null}
{
  "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**

```json theme={null}
{ "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**

```json theme={null}
{
  "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**

```json theme={null}
{ "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                                 |