> ## Documentation Index > Fetch the complete documentation index at: https://docs.bronto.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a new role > Creates a new role with specified permissions in the organization. Roles define sets of permissions that can be assigned to users to control their access to various system features and resources. The role must have a unique identifier and include at least one permission. ## OpenAPI ````yaml https://s3.eu-west-1.amazonaws.com/docs.brontobytes.io/redocusaurus/brontobytes.yaml post /roles openapi: 3.0.2 info: title: Bronto API license: name: Commercial version: 1.0.0 servers: - url: https://api.eu.bronto.io - url: https://api.us.bronto.io security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: api-keys description: > An Application Programming Interface (API) key is a unique identifier. The API Key must be provided as X-BRONTO-API-KEY in headers for the request to be authenticated and authorized by the API server according to the API Key's role. For further information about roles visit [our API Key docs] https://docs.bronto.io/manage/manage-api-keys - name: context description: > Context is a REST API resource that allows the retrieval of a specified number of log events (default of 100) around a log event of interest, e.g. when a number of log events were returned by a previous query and you then decide you want to see the 50 log events before one of those returned log events. Log events can be retrieved either before, after, or both before and after the specified log event. - name: exports description: > The Bronto Export API allows you to efficiently download large volumes of log data for further analysis. The data to be exported can be filtered by entering the search parameters \"from\", \"where\" and \"time_range\" as per a normal query in the \"search_details\" object. To export data the following steps are required: 1. Create an export using a POST request, which will return an \"export_id\", \"status\" and \"progress\". 2. Use the export id to get the status of the export task by sending a GET request, which will return \"status\" and \"progress\" with a value of percentage completed. When the export is completed, the \"status\" will be \"COMPLETE\" 3. Once the export task has completed you can download your data using curl (or similar) from the \"location\" URL returned in the GET response. - name: collections description: > Collections group datasets together. Each collection contains one or more datasets. - name: datasets description: > Datasets are a sequence of timestamped log events. Datasets can be searched to view events matching a filter or to perform statistical functions on matching events. - name: logs description: > Logs are a sequence of timestamped log events. Logs can be searched to view events matching a filter or to perform statistical functions on matching events. - name: search description: > The REST API for searching data uses queries based on a subset of SQL, with the syntax as per https://docs.bronto.io/query-syntax/overview - name: top-keys description: > Top-Keys is a REST API resource that allows you to easily retrieve the top keys for a specific log. - name: significant-keys description: > Significant-Keys is a REST API resource for the stored, model-ranked keys of a log: which fields are worth charting, how, and how that has changed between scans. - name: usage description: > Usage is a REST API resource that allows you to easily track your Bronto usage by retrieving usage data relating to data ingestion and amount of data searched, and allowing you to drill down for a specific dataset over a defined timeframe. - name: users description: > Users are given specific roles, where each role determines the user's permissions within the application. Those roles are as follows: - "Admin" role has permission for all actions on all entities in the application. - "Standard" role allows Read/Write and Delete actions on entities in non-sensitive areas of the application. - "ReadOnly" role allows only read actions and only on entities in non-sensitive areas of the application. - name: config_assistant description: > The Config Assistant APIs provide endpoints for creating or modifying observability agent configurations. - name: patterns description: > Patterns return the Pattern IDs, templates, and source log ID for all logs matching the given search criteria. paths: /roles: post: tags: - roles summary: Create a new role description: > Creates a new role with specified permissions in the organization. Roles define sets of permissions that can be assigned to users to control their access to various system features and resources. The role must have a unique identifier and include at least one permission. operationId: createRole requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateRoleRequest' required: true responses: '201': description: Role created successfully headers: RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/Role' '400': description: Bad Request - The body in the request is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden - The user does not have the privileges to create roles content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict - A role with the same identifier already exists content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Request - Fair usage limits exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error - An error occurred on the server side. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' default: description: Unexpected Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: CreateRoleRequest: type: object properties: role_type: type: string description: The entity which the roles can be applied to. USER | API display_name: type: string description: The display name of the role description: type: string description: Description of the role permissions: type: array description: Updated list of permissions. example: - tag_write - tag_read - tag_delete items: type: string Role: type: object properties: role_id: type: string description: The ID of the role role_type: type: string description: The entity which the roles can be applied to enum: - USER - API display_name: type: string description: The display name of the role description: type: string description: Description of the role is_system_role: type: boolean description: Whether this is a built-in system role or a custom user-created role metadata: $ref: '#/components/schemas/Metadata' permissions: type: array items: type: object properties: group_name: type: string description: The group name of the permission group_display_name: type: string description: The display name of the permission group name: type: string description: The name of the permission display_name: type: string description: The display name of the permission description: type: string description: Description of the permission type: type: string description: The type of permission (e.g., read, write, delete) restricted: type: boolean description: Indicates if the permission is restricted sensitive: type: boolean description: >- Indicates if the permission is a sensitive permission requiring careful review. Examples of sensitive permissions include Edit Billing, Delete API Keys, Manage User Access, Remove User Access, Read PII Data, and Set Log Retention. ErrorResponse: required: - code - correlation_id - details - type type: object properties: code: maximum: 599 minimum: 400 type: integer description: HTTP status code for the error response. format: int32 type: type: string description: >- HTTP reason phrase associated with the status code (e.g. "Not Found" for 404) example: Not Found correlation_id: type: string description: Unique identifier for the request, used for tracing and debugging. details: type: string description: Human-readable description of the error. example: Resource not found. description: Standard error response returned by the API when a request fails. example: bad_request_validation: summary: Bad Request - Validation Error description: Example error when request validation fails value: code: 400 type: Bad Request correlation_id: 95c6a974e3ab01209b6b0dfedb1b16c5 details: 'Validation failed: ''name'' field is required and cannot be empty' bad_request_invalid_type: summary: Bad Request - Invalid Metric Type description: Example error when an invalid metric type is provided value: code: 400 type: Bad Request correlation_id: 00d8a51bb2874f2583670317a4fb8db7 details: >- Invalid metric_type 'INVALID'. Must be one of: COUNTER, GAUGE, HISTOGRAM forbidden: summary: Forbidden Access description: Example error when user lacks required permissions value: code: 403 type: Forbidden correlation_id: 40276639de0f49d586e32edd8c4f6b34 details: >- Access denied. User does not have permission to create metric definition templates not_found: summary: Resource Not Found description: Example error when requested resource doesn't exist value: code: 404 type: Not Found correlation_id: 605f832bcfe44a1081441691c8d42253 details: >- Metric definition template with id '550e8400-e29b-41d4-a716-446655440000' not found rate_limit: summary: Rate Limit Exceeded description: Example error when API rate limit is exceeded value: code: 429 type: Too Many Requests correlation_id: 53909ed43c544531b7a555e295960437 details: >- Rate limit exceeded. Maximum 100 requests are allowed within a 5-minute window internal_server_error: summary: Internal Server Error description: Example error for unexpected server-side failures value: code: 500 type: Internal Server Error correlation_id: b129b8e0e66c41aa9541a30f67e38ce2 details: An unexpected error occurred while processing your request Metadata: type: object properties: created_at: type: integer description: Creation timestamp in milliseconds since epoch. format: int64 created_by: $ref: '#/components/schemas/Identity' modified_at: type: integer description: Last update timestamp in milliseconds since epoch. format: int64 modified_by: $ref: '#/components/schemas/Identity' deleted_at: type: integer description: Deletion timestamp in milliseconds since epoch. format: int64 deleted_by: $ref: '#/components/schemas/Identity' last_heartbeat_at: type: integer description: Timestamp of the last heartbeat in milliseconds since epoch. format: int64 description: Common metadata attached to all persisted resources. Identity: required: - id - type type: object properties: type: type: string description: Type of actor performing the operation. enum: - API_KEY_ID - USER_ID id: type: string description: Identifier of the actor (user id or API key id). format: uuid description: Actor responsible for an operation. headers: RateLimitLimit: description: The request limit per time window. schema: type: integer example: 20 RateLimitRemaining: description: The number of requests left in the current time window. schema: type: integer example: 12 RateLimitReset: description: The number of seconds left in the current time window. schema: type: integer example: 13 securitySchemes: ApiKeyAuth: type: apiKey name: X-BRONTO-API-KEY in: header BearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.