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 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 |
{
"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) |
{
"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 |
{
"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 |
{
"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
{
"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" |
201
{
"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 |
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) |
{
"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 |
201
{
"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) |
201
{
"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 |
201
{
"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 |
