Skip to main content
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
FieldTypeRequiredDescription
agentIdstringYesGenie UUID to fetch runs for
dateRangestringNoFilter by recency — e.g. "7d", "30d". Omit or pass "all" for no filter
adminModebooleanNoAdmin only — bypass ownership filter
userIdstringNoAdmin 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
FieldTypeRequiredDescription
idstringYesTest 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
FieldTypeRequiredDescription
agentIdstringNoFilter to a single Genie
agentIdsstring[]NoFilter to multiple Genies
dateRangestringNoe.g. "7d", "30d", "all"
statusFilterstringNo"all" (default), "passed", or "failed"
pagenumberNoPage number, default 1
pageSizenumberNoResults per page, default 20, max 100
adminModebooleanNoAdmin only
userIdstringNoAdmin 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
FieldTypeRequiredDescription
idstringYesTest 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
FieldTypeRequiredDescription
namestringYesScenario name
testPromptsstring[]YesNon-empty array of user prompts to simulate
descriptionstringNoOptional description
categorystringNoCategory 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
FieldTypeRequiredDescription
idstringYesScenario UUID
Response 
{ "success": true }

​
get-audit-scenarios

Returns AI-generated scenarios that were created for a specific audit run. Parameters
FieldTypeRequiredDescription
idstringYesAudit 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
FieldTypeRequiredDescription
agentIdstringYesGenie UUID
transcriptarrayYesNon-empty array of conversation turn objects
elevenlabsConversationIdstringNoAssociated ElevenLabs conversation ID
durationSecondsnumberNoDuration 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
FieldTypeRequiredDescription
agentIdstringYesGenie UUID to audit
regeneratebooleanNoForce regeneration of scenarios even if they exist
scenariosPerCategoryobjectNoMap 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
FieldTypeRequiredDescription
agentIdstringYesGenie UUID
elevenlabsIdstringYesElevenLabs agent ID for the Genie
categoriesstring[]NoCategory IDs to include
suggestedTestsobject[]NoAI-suggested test objects (id, name, description, simulatedUserPrompt, evaluationCriteria)
customTestIdsstring[]NoSaved custom scenario UUIDs to run
Response — 201 
{
  "testRunId": "run-uuid",
  "status": "running"
}

​
Error codes

CodeMeaning
VALIDATION_ERRORMissing or invalid required parameter
NOT_FOUNDTest run or scenario not found
FORBIDDENYou do not own this resource
AGENT_NOT_FOUNDGenie does not exist
INTERNAL_ERRORUnexpected server error