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.

The role list can include global roles managed by Aiqaramba. Tenant users cannot edit or delete global roles.

GET /api/v1/roles

List visible roles

Returns tenant-owned and platform-global roles in descending ID order.

Parameters

Parameter	Type	In	Required	Description
`limit`	integer	query	No	Maximum roles to return.
`cursor`	uuid	query	No	Return roles with IDs lower than this role ID.

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/roles" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Visible roles.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`roles`	object[]
`roles[].id`	uuid
`roles[].tenant_id`	uuid
`roles[].name`	string
`roles[].description`	string
`roles[].system_prompt`	string
`roles[].created_at`	date-time
`roles[].updated_at`	date-time
`next_cursor`	uuid

POST /api/v1/roles

Create a role

Creates a tenant role, or a global role when requested by support.

Request Body (application/json)

Field	Type	Required	Description
`name`	string	Yes	Role name
`description`	string	No	Human-facing subtitle for the role list. When omitted the server auto-generates one from the name and system prompt.
`system_prompt`	string	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.
`global`	boolean	No	Create a platform-global role; support access is required.

Example Request

curl

curl -X POST "http://app.aiqaramba.com/api/v1/roles" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "<string>",
    "system_prompt": "<string>"
  }'

Status Codes

Code	Description
`201`	Role created.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`403`	The authenticated principal is not authorized for this operation.
`409`	The request conflicts with the current resource state.
`500`	The server could not complete the request.
`502`	A required upstream service could not complete the operation.

Response Fields (201)

Field	Type	Description
`id`	uuid
`tenant_id`	uuid
`name`	string
`description`	string
`system_prompt`	string
`created_at`	date-time
`updated_at`	date-time

GET /api/v1/roles/{id}

Get a visible role

Parameters

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

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/roles/<id>" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Role found.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`id`	uuid
`tenant_id`	uuid
`name`	string
`description`	string
`system_prompt`	string
`created_at`	date-time
`updated_at`	date-time

PUT /api/v1/roles/{id}

Replace a role

Replaces role behavior fields; global roles require support access.

Parameters

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

Request Body (application/json)

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

Example Request

curl

curl -X PUT "http://app.aiqaramba.com/api/v1/roles/<id>" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "<string>",
    "system_prompt": "<string>"
  }'

Status Codes

Code	Description
`200`	Role updated.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`409`	The request conflicts with the current resource state.
`500`	The server could not complete the request.
`502`	A required upstream service could not complete the operation.

Response Fields (200)

Field	Type	Description
`id`	uuid
`tenant_id`	uuid
`name`	string
`description`	string
`system_prompt`	string
`created_at`	date-time
`updated_at`	date-time

DELETE /api/v1/roles/{id}

Delete a role

Deletes the role after removing its stored knowledge documents.

Parameters

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

Example Request

curl

curl -X DELETE "http://app.aiqaramba.com/api/v1/roles/<id>" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`204`	Role deleted.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

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

List role knowledge documents

Parameters

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

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/roles/<id>/knowledge" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Attached knowledge documents.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`documents`	object[]
`documents[].id`	uuid
`documents[].role_id`	uuid
`documents[].filename`	string
`documents[].mime_type`	string
`documents[].size_bytes`	integer
`documents[].status`	string	Values: processing, ready, failed.
`documents[].extraction`	string	Values: ok, partial, empty.
`documents[].error_message`	string
`documents[].overview`	object
`documents[].chunk_count`	integer
`documents[].created_at`	date-time
`documents[].updated_at`	date-time

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

Upload role knowledge

Stores one reference document and queues asynchronous indexing.

Parameters

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

Request Body (multipart/form-data)

Field	Type	Required	Description
`file`	file	Yes	The document to attach (multipart form field name: 'file')

Example Request

curl

curl -X POST "http://app.aiqaramba.com/api/v1/roles/<id>/knowledge" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -F 'file=@./file'

Status Codes

Code	Description
`202`	Document stored and indexing queued.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`413`	The request body or uploaded artifact is too large.
`500`	The server could not complete the request.
`507`	The tenant does not have enough storage quota.

Response Fields (202)

Field	Type	Description
`id`	uuid
`role_id`	uuid
`filename`	string
`mime_type`	string
`size_bytes`	integer
`status`	string	Values: processing, ready, failed.
`extraction`	string	Values: ok, partial, empty.
`error_message`	string
`overview`	object
`chunk_count`	integer
`created_at`	date-time
`updated_at`	date-time

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

Delete all role knowledge

Parameters

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

Example Request

curl

curl -X DELETE "http://app.aiqaramba.com/api/v1/roles/<id>/knowledge" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`204`	Knowledge deleted.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

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

Delete a role knowledge document

Parameters

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

Example Request

curl

curl -X DELETE "http://app.aiqaramba.com/api/v1/roles/<id>/knowledge/<documentID>" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`204`	Knowledge document deleted.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.