Brand Integrity

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

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

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

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

{
  "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"`

Response — 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

Response

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

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

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

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

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

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

Actions

`all`

`get`

`list`

`list-results`

`list-scenarios`

`create-scenario`

`delete-scenario`

`get-audit-scenarios`

`save-manual-test`

`run-full-audit`

`run-custom-audit`

Error codes

​Actions

​all

​get

​list

​list-results

​list-scenarios

​create-scenario

​delete-scenario

​get-audit-scenarios

​save-manual-test

​run-full-audit

​run-custom-audit

​Error codes

Actions

`all`

`get`

`list`

`list-results`

`list-scenarios`

`create-scenario`

`delete-scenario`

`get-audit-scenarios`

`save-manual-test`

`run-full-audit`

`run-custom-audit`

Error codes