Roles

Roles are reusable prompt injection templates. A role's system prompt is injected into the agent's system prompt, shaping how it behaves during execution. Roles can carry attached knowledge documents (reference material) that the agent can consult while running.

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.

POST /api/v1/roles

Create a new role

Parameters

Parameter	Type	In	Required	Description
`name`	string	body	Yes	Role name
`system_prompt`	string	body	Yes	Verbatim text injected into the agent's system prompt at the start of every run. This is the only field that influences runtime behavior.
`description`	string	body	No	Human-facing subtitle for the role list. When omitted the server auto-generates one from the name and system prompt.

Status Codes

Code	Description
`201`	Role created
`400`	Validation error
`401`	Unauthorized
`409`	Duplicate role name
`502`	Description auto-generation failed; supply one explicitly

Response Body

{
  "id": "dd0e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Power User",
  "description": "An impatient power user persona",
  "system_prompt": "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 Key

name *

system_prompt *

description

cURL

Response

GET /api/v1/roles

List 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": "An impatient power user persona",
      "system_prompt": "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 Key

limit

cursor

cURL

Response

GET /api/v1/roles/{id}

Get 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": "An impatient power user persona",
  "system_prompt": "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 Key

id *

cURL

Response

PUT /api/v1/roles/{id}

Update a role

Replaces the role's name and system prompt. When description is omitted the server regenerates one from the updated name and system prompt.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Role ID
`name`	string	body	Yes	Role name
`system_prompt`	string	body	Yes	Verbatim text injected into the agent's system prompt at the start of every run
`description`	string	body	No	Human-facing subtitle. When omitted the server auto-generates a fresh one.

Status Codes

Code	Description
`200`	Role updated
`400`	Validation error
`401`	Unauthorized
`404`	Role not found
`409`	Duplicate role name
`502`	Description auto-generation failed; supply one explicitly

Response Body

{
  "id": "dd0e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Power User",
  "description": "An impatient power user persona",
  "system_prompt": "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 Key

id *

name *

system_prompt *

description

cURL

Response

DELETE /api/v1/roles/{id}

Delete a role

Deletes a role along with its attached knowledge documents and their stored files.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Role ID

Status Codes

Code	Description
`204`	Role deleted
`400`	Invalid UUID
`401`	Unauthorized
`404`	Role not found

API Key

id *

cURL

Response

GET /api/v1/roles/{id}/knowledge

List a role's knowledge documents

Returns the reference documents attached to the role. Each document carries an indexing status: processing (indexing in progress), ready, or failed.

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

{
  "documents": [
    {
      "id": "ee0e8400-e29b-41d4-a716-446655440000",
      "role_id": "dd0e8400-e29b-41d4-a716-446655440000",
      "filename": "style-guide.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 204800,
      "status": "ready",
      "chunk_count": 12,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:31:00Z"
    }
  ]
}

API Key

id *

cURL

Response

POST /api/v1/roles/{id}/knowledge

Upload a knowledge document to a role

Uploads a reference document via multipart/form-data (form field name: 'file'). The document is stored immediately and indexed asynchronously; its status transitions from processing to ready (or failed). Max 20MB.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Role ID
`file`	file	body	Yes	The document to attach (multipart form field name: 'file')

Status Codes

Code	Description
`202`	Document stored; indexing queued
`400`	Unsupported file type or invalid form
`401`	Unauthorized
`404`	Role not found
`413`	File too large
`507`	Storage quota exceeded

API Key

id *

file *

cURL

Response

DELETE /api/v1/roles/{id}/knowledge/{documentID}

Delete a single knowledge document

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Role ID
`documentID`	uuid	path	Yes	Knowledge document ID

Status Codes

Code	Description
`204`	Document deleted
`400`	Invalid UUID
`401`	Unauthorized
`404`	Role or document not found

API Key

id *

documentID *

cURL

Response

DELETE /api/v1/roles/{id}/knowledge

Delete all knowledge documents from a role

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Role ID

Status Codes

Code	Description
`204`	All documents deleted
`400`	Invalid UUID
`401`	Unauthorized
`404`	Role not found

API Key

id *

cURL

Response