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.

string

required

Genie UUID to fetch runs for.

string

Filter by recency — e.g. "7d", "30d". Omit or pass "all" for no filter.

boolean

Admin only — bypass ownership filter.

string

Admin only — target a specific user’s data.

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.

string

Filter to a single Genie.

string[]

Filter to multiple Genies. Ignored when agentId is set.

string

Filter by recency — e.g. "7d", "30d", "all".

string

default:"all"

"all", "passed", or "failed".

number

default:"1"

Page number.

number

default:"20"

Results per page. Maximum 100.

boolean

Admin only — bypass ownership filter.

string

Admin only — target a specific user’s data.

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.

string

required

Scenario name.

string[]

required

Non-empty array of user prompts to simulate in the test.

string

Optional description.

string

default:"custom"

Category label.

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.

string

required

Genie UUID.

array

required

Non-empty array of conversation turn objects.

string

Voice provider conversation ID for the recorded session.

number

Duration of the conversation in seconds.

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.

string

required

Genie UUID to audit.

boolean

Force regeneration of scenarios even if they already exist for this Genie.

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.

string

required

Genie UUID.

string

required

Voice provider agent ID for the Genie (available from the Genie’s voice settings).

string[]

Category IDs to include in the audit.

object[]

Tailored test objects to run. Each item should include id, name, description, simulatedUserPrompt, and evaluationCriteria.

string[]

Saved custom scenario UUIDs to include.

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