Roles
Roles are reusable prompt injection templates. A role's description is injected into the agent's system prompt, shaping how it behaves during execution.
Overview
Roles are reusable prompt injection templates. The description field of a role is injected verbatim into the agent's LLM system prompt. This directly shapes how the agent behaves during execution. Write it as instructions the model should follow, not as a narrative for humans.
For example, a description like "You are an impatient power user who uses keyboard shortcuts and skips optional steps" will cause the agent to navigate faster and avoid filling optional fields. A description like "You are a screen reader user who relies entirely on keyboard navigation" will test your application's accessibility.
Three default roles are created for each tenant: Discovery Explorer, Functional QA, and UX Auditor. These cannot be deleted but their descriptions can be customized.
Create a new role
Parameters
| Parameter | Type | In | Required | Description |
|---|---|---|---|---|
name | string | body | Yes | Role name |
description | string | body | Yes | Role description (injected into the test run system prompt) |
Status Codes
| Code | Description |
|---|---|
201 | Role created |
400 | Validation error |
401 | Unauthorized |
409 | Duplicate role name |
Response Body
{
"id": "dd0e8400-e29b-41d4-a716-446655440000",
"tenant_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Power User",
"description": "You are an impatient power user who uses keyboard shortcuts",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}/api/v1/rolesList roles
Parameters
| Parameter | Type | In | Required | Description |
|---|---|---|---|---|
limit | integer | query | No | Number of results to return (default: 20) |
cursor | uuid | query | No | Cursor for pagination |
Status Codes
| Code | Description |
|---|---|
200 | OK |
401 | Unauthorized |
Response Body
{
"roles": [
{
"id": "dd0e8400-e29b-41d4-a716-446655440000",
"tenant_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Power User",
"description": "You are an impatient power user who uses keyboard shortcuts",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
],
"next_cursor": "ee0e8400-e29b-41d4-a716-446655440000"
}/api/v1/rolesGet role by ID
Parameters
| Parameter | Type | In | Required | Description |
|---|---|---|---|---|
id | uuid | path | Yes | Role ID |
Status Codes
| Code | Description |
|---|---|
200 | OK |
400 | Invalid UUID |
401 | Unauthorized |
404 | Role not found |
Response Body
{
"id": "dd0e8400-e29b-41d4-a716-446655440000",
"tenant_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Power User",
"description": "You are an impatient power user who uses keyboard shortcuts",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}/api/v1/roles/{id}