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

# Brand Integrity

> Run and manage Brand Integrity audits — automated tests that verify your Genie behaves on-brand across a suite of conversation scenarios.

Brand Integrity lets you simulate conversations with a Genie and score the results against expected behaviour. Audits run asynchronously; progress is broadcast over the `brand-tests` Supabase Realtime channel. Workspace members share access to their owner's test runs.

***

## Actions

### `all`

Returns all **completed** test runs for a specific Genie, each with its results array embedded.

**Parameters**

| Field       | Type    | Required | Description                                                                  |
| ----------- | ------- | -------- | ---------------------------------------------------------------------------- |
| `agentId`   | string  | Yes      | Genie UUID to fetch runs for                                                 |
| `dateRange` | string  | No       | Filter by recency — e.g. `"7d"`, `"30d"`. Omit or pass `"all"` for no filter |
| `adminMode` | boolean | No       | Admin only — bypass ownership filter                                         |
| `userId`    | string  | No       | Admin only — target a specific user                                          |

**Response**

```json theme={null}
{
  "items": [
    {
      "id": "run-uuid",
      "agent_id": "agent-uuid",
      "status": "completed",
      "run_type": "full_audit",
      "total_tests": 12,
      "progress": 12,
      "started_at": "2024-01-01T00:00:00Z",
      "completed_at": "2024-01-01T00:05:00Z",
      "results": [ /* brand_test_results rows */ ]
    }
  ]
}
```

***

### `get`

Returns a single test run by ID with its full results array.

**Parameters**

| Field | Type   | Required | Description                          |
| ----- | ------ | -------- | ------------------------------------ |
| `id`  | string | Yes      | Test run UUID (passed as request ID) |

**Response**

```json theme={null}
{
  "testRun": {
    "id": "run-uuid",
    "agent_id": "agent-uuid",
    "status": "completed",
    "results": [ /* brand_test_results rows */ ]
  }
}
```

***

### `list`

Paginated list of test runs across one or more Genies, optionally filtered by status.

**Parameters**

| Field          | Type      | Required | Description                                  |
| -------------- | --------- | -------- | -------------------------------------------- |
| `agentId`      | string    | No       | Filter to a single Genie                     |
| `agentIds`     | string\[] | No       | Filter to multiple Genies                    |
| `dateRange`    | string    | No       | e.g. `"7d"`, `"30d"`, `"all"`                |
| `statusFilter` | string    | No       | `"all"` (default), `"passed"`, or `"failed"` |
| `page`         | number    | No       | Page number, default `1`                     |
| `pageSize`     | number    | No       | Results per page, default `20`, max `100`    |
| `adminMode`    | boolean   | No       | Admin only                                   |
| `userId`       | string    | No       | Admin only                                   |

**Response**

```json theme={null}
{
  "items": [ /* test runs with embedded results */ ],
  "totalCount": 42,
  "page": 1,
  "pageSize": 20
}
```

***

### `list-results`

Returns all individual test results for a specific run.

**Parameters**

| Field | Type   | Required | Description   |
| ----- | ------ | -------- | ------------- |
| `id`  | string | Yes      | Test run UUID |

**Response**

```json theme={null}
{
  "items": [ /* brand_test_results rows, ordered by created_at asc */ ]
}
```

***

### `list-scenarios`

Returns all custom (non-predefined) test scenarios belonging to the authenticated user or workspace.

**Parameters** — none

**Response**

```json theme={null}
{
  "items": [
    {
      "id": "scenario-uuid",
      "name": "Refund Policy Check",
      "description": "Verifies agent handles refund requests correctly",
      "testPrompts": ["I want a refund", "My order never arrived"],
      "isCustom": true,
      "userId": "user-uuid",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}
```

***

### `create-scenario`

Creates a custom test scenario.

**Parameters**

| Field         | Type      | Required | Description                                 |
| ------------- | --------- | -------- | ------------------------------------------- |
| `name`        | string    | Yes      | Scenario name                               |
| `testPrompts` | string\[] | Yes      | Non-empty array of user prompts to simulate |
| `description` | string    | No       | Optional description                        |
| `category`    | string    | No       | Category label, defaults to `"custom"`      |

**Response** — `201`

```json theme={null}
{
  "scenario": {
    "id": "scenario-uuid",
    "name": "Refund Policy Check",
    "testPrompts": ["I want a refund"],
    "isCustom": true,
    "createdAt": "2024-01-01T00:00:00Z"
  }
}
```

***

### `delete-scenario`

Deletes a custom scenario. Only the owner (or an admin) can delete.

**Parameters**

| Field | Type   | Required | Description   |
| ----- | ------ | -------- | ------------- |
| `id`  | string | Yes      | Scenario UUID |

**Response**

```json theme={null}
{ "success": true }
```

***

### `get-audit-scenarios`

Returns AI-generated scenarios that were created for a specific audit run.

**Parameters**

| Field | Type   | Required | Description                                  |
| ----- | ------ | -------- | -------------------------------------------- |
| `id`  | string | Yes      | Audit run ID (numeric, passed as request ID) |

**Response**

```json theme={null}
{
  "items": [ /* brand_test_scenarios rows ordered by severity asc */ ]
}
```

***

### `save-manual-test`

Saves a manually recorded conversation as a completed test run. Useful for logging quick-test sessions from the UI.

**Parameters**

| Field                      | Type   | Required | Description                                  |
| -------------------------- | ------ | -------- | -------------------------------------------- |
| `agentId`                  | string | Yes      | Genie UUID                                   |
| `transcript`               | array  | Yes      | Non-empty array of conversation turn objects |
| `elevenlabsConversationId` | string | No       | Associated ElevenLabs conversation ID        |
| `durationSeconds`          | number | No       | Duration of the conversation                 |

**Response** — `201`

```json theme={null}
{
  "testRun": { /* brand_test_runs row */ }
}
```

***

### `run-full-audit`

Kicks off a full automated Brand Integrity audit for a Genie. Creates a test run in `generating` state, then asynchronously generates scenarios and executes them. Returns immediately with the `testRunId` — subscribe to the `brand-tests` Realtime channel for progress updates.

The Genie must have a voice configured (`elevenlabs_id`).

**Parameters**

| Field                  | Type    | Required | Description                                                                             |
| ---------------------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| `agentId`              | string  | Yes      | Genie UUID to audit                                                                     |
| `regenerate`           | boolean | No       | Force regeneration of scenarios even if they exist                                      |
| `scenariosPerCategory` | object  | No       | Map of `{ [categoryId]: count }` to control scenario volume per category (clamped 1–20) |

**Response** — `201`

```json theme={null}
{
  "testRunId": "run-uuid"
}
```

***

### `run-custom-audit`

Runs a custom audit using a specific selection of categories, AI-suggested tests, and/or saved custom scenario IDs. Returns immediately with `testRunId`; execution is asynchronous.

**Parameters**

| Field            | Type      | Required | Description                                                                                          |
| ---------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `agentId`        | string    | Yes      | Genie UUID                                                                                           |
| `elevenlabsId`   | string    | Yes      | ElevenLabs agent ID for the Genie                                                                    |
| `categories`     | string\[] | No       | Category IDs to include                                                                              |
| `suggestedTests` | object\[] | No       | AI-suggested test objects (`id`, `name`, `description`, `simulatedUserPrompt`, `evaluationCriteria`) |
| `customTestIds`  | string\[] | No       | Saved custom scenario UUIDs to run                                                                   |

**Response** — `201`

```json theme={null}
{
  "testRunId": "run-uuid",
  "status": "running"
}
```

***

## Error codes

| Code               | Meaning                               |
| ------------------ | ------------------------------------- |
| `VALIDATION_ERROR` | Missing or invalid required parameter |
| `NOT_FOUND`        | Test run or scenario not found        |
| `FORBIDDEN`        | You do not own this resource          |
| `AGENT_NOT_FOUND`  | Genie does not exist                  |
| `INTERNAL_ERROR`   | Unexpected server error               |