> ## Documentation Index > Fetch the complete documentation index at: https://docs.gorules.io/llms.txt > Use this file to discover all available pages before exploring further. # List roles > Retrieves a paginated list of roles in the organisation with optional search filtering. ## OpenAPI ````yaml /openapi/brms.json get /api/roles openapi: 3.0.3 info: title: GoRules BRMS version: local servers: [] security: [] tags: - name: AI description: >- AI-powered assistant for interactive conversations and decision logic generation - name: Audit log description: Track and export organisation activity logs for compliance and monitoring - name: Branches description: >- Manage feature branches for collaborative decision development with commits and merging - name: Change requests description: Review and approve changes before merging or deploying to environments - name: Cloud description: Cloud-specific endpoints for organisation and client management - name: Decision description: Evaluate and simulate decision graphs with trace and performance data - name: Deployment workflows description: Manage deployment workflow runs and job approvals - name: Deployments description: Configure cloud storage providers for release deployments - name: Document description: Manage decision documents, versions, and file operations within projects - name: Environment description: >- Configure deployment environments with approval workflows and access tokens - name: Group description: Manage permission groups for project-level access control - name: Infrastructure description: Health check and infrastructure status endpoints - name: Integration description: Configure external integrations for HTTP requests and data sources - name: Invitation description: Manage organisation invitations for new members - name: Member description: Manage project membership and group assignments - name: Organisation description: Manage organisation settings, preferences, and licensing - name: Personal access token description: Create and manage personal access tokens for API authentication - name: Profile description: Manage current user profile settings - name: Project description: Create and manage projects with approval workflows - name: Release description: >- Package, version, and deploy decision documents. Learn more about [Releases](https://gorules.io/developers/brms/multi-environment) - name: Roles description: Define custom roles with permissions for organisation-wide access control - name: Security description: Manage project access tokens for API authentication - name: Templates description: Browse and apply project templates for quick onboarding - name: Test events description: Manage test events for decision evaluation and testing - name: User description: Manage organisation users, invitations, and service accounts paths: /api/roles: get: tags: - Roles summary: List roles description: >- Retrieves a paginated list of roles in the organisation with optional search filtering. operationId: listRoles parameters: - schema: type: string in: query name: search description: Search term to filter roles by name - schema: type: number default: 1 in: query name: page description: Current page - schema: type: number default: 10 in: query name: perPage description: Number of items per page responses: '200': description: Paginated list of roles content: application/json: schema: type: object properties: results: type: array items: type: object properties: id: type: string format: uuid description: Unique identifier of the role name: type: string description: Name of the role description: type: string nullable: true description: Description of the role idpGroups: type: array nullable: true items: type: string description: Identity provider groups mapped to this role allProjects: type: boolean description: Whether this role applies to all projects projectPermissions: type: array nullable: true items: type: string enum: - owner - documents - releases - releases:manage - releases:deploy - releases:delete - integrations:manage - documents:full - documents:view-content - documents:edit-content - documents:edit-view - branches - branches:create - branches:merge - branches:delete - project:manage - environments - environments:manage - environments:delete description: >- List of project-level permissions granted by this role projectFilePermissions: type: array nullable: true items: type: object properties: id: type: string nullable: true description: Unique identifier of the file permission effect: type: string enum: - allow - deny description: Permission effect (allow or deny) actions: type: array nullable: true items: type: string enum: - visible - modify - write - delete description: List of actions this permission applies to patterns: type: string nullable: true description: File path patterns this permission applies to required: - effect description: File-level permissions granted by this role groups: type: array items: type: object properties: id: type: string format: uuid description: Unique identifier of the group name: type: string description: Name of the group description: type: string nullable: true description: Description of the group projectId: type: string format: uuid description: ID of the project this group belongs to project: type: object properties: name: type: string description: Name of the project description: Project this group belongs to roleId: type: string nullable: true format: uuid description: ID of the role this group is associated with required: - id - name - projectId description: Groups associated with this role users: type: array items: type: object properties: id: type: string format: uuid description: Unique identifier of the user email: type: string format: email description: Email address of the user firstName: type: string nullable: true description: First name of the user lastName: type: string nullable: true description: Last name of the user required: - id - email description: Users assigned to this role organisationId: type: string format: uuid description: ID of the organisation this role belongs to organisation: type: object properties: id: type: string format: uuid description: Unique identifier of the organisation name: type: string description: Name of the organisation required: - id - name description: Organisation this role belongs to createdAt: type: string description: Timestamp when the role was created updatedAt: type: string description: Timestamp when the role was last updated required: - id - name - allProjects - organisationId - createdAt - updatedAt description: List of roles paginate: type: object properties: current: type: number description: Current page number from: type: number description: Starting record number to: type: number description: Ending record number total: type: number description: Total number of records pageSize: type: number description: Number of records per page required: - current - from - to - total - pageSize description: Pagination metadata required: - results - paginate description: Paginated list of roles security: - personalAccessToken: [] - internalAuth: [] components: securitySchemes: personalAccessToken: type: http scheme: bearer description: Personal access token is obtained through your profile internalAuth: type: http scheme: internal description: Cannot be used directly ````