openapi: 3.1.0
info:
  title: Automation Anywhere API Task Execution AccessDetails Roles API
  description: The Automation Anywhere API Task Execution API enables developers to invoke API Tasks — a specialized type of cloud-based bot designed to be called synchronously from external applications like a REST service. The API provides endpoints to list API Task allocations, generate unique execution URLs and tokens, and execute API Tasks in real time. API Tasks execute on cloud infrastructure without requiring local Bot Runner devices, and are designed for low latency with near-real-time response rates. The execution URL and authorization token are short-lived and must be refreshed periodically to prevent authorization failures.
  version: '2019'
  contact:
    name: Automation Anywhere Support
    url: https://support.automationanywhere.com
  termsOfService: https://www.automationanywhere.com/terms-of-service
servers:
- url: https://{controlRoomUrl}/orchestrator/v1/hotbot
  description: Automation Anywhere API Task Orchestrator
  variables:
    controlRoomUrl:
      default: your-control-room.automationanywhere.com
      description: Your Control Room hostname
security:
- bearerAuth: []
- xAuthorization: []
tags:
- name: Roles
  description: Create, list, retrieve, update, and delete user roles
paths:
  /v2/usermanagement/roles:
    post:
      operationId: createRole
      summary: Create a role
      description: Creates a new role in the Control Room with the specified name, description, and set of permissions. Roles are used to grant users access to specific features, folders, and API operations.
      tags:
      - Roles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoleRequest'
      responses:
        '201':
          description: Role created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/usermanagement/roles/list:
    post:
      operationId: listRoles
      summary: List roles
      description: Retrieves a paginated, filterable list of Control Room roles. Supports filtering by name and other attributes. Returns role metadata including permissions and member counts.
      tags:
      - Roles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterRequest'
      responses:
        '200':
          description: List of roles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/usermanagement/roles/{id}:
    get:
      operationId: getRole
      summary: Get role by ID
      description: Retrieves detailed information about a specific role, including its name, description, permissions, and the list of users assigned to it.
      tags:
      - Roles
      parameters:
      - $ref: '#/components/parameters/RoleIdParam'
      responses:
        '200':
          description: Role details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Role not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateRole
      summary: Update a role
      description: Updates an existing role's name, description, and permission set. Changes apply immediately to all users assigned to the role.
      tags:
      - Roles
      parameters:
      - $ref: '#/components/parameters/RoleIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRoleRequest'
      responses:
        '201':
          description: Role updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Role not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteRole
      summary: Delete a role
      description: Permanently deletes a Control Room role. Users assigned only to this role will lose associated permissions. System roles (AAE_Admin, AAE_Basic) cannot be deleted.
      tags:
      - Roles
      parameters:
      - $ref: '#/components/parameters/RoleIdParam'
      responses:
        '204':
          description: Role deleted successfully
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Role not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    PageInfo:
      type: object
      description: Pagination metadata returned with list responses
      properties:
        offset:
          type: integer
          description: Starting index of the returned results
        total:
          type: integer
          description: Total number of records matching the query
        totalFilter:
          type: integer
          description: Total number of records after filters are applied
    RoleListResponse:
      type: object
      description: Paginated list of role records
      properties:
        list:
          type: array
          description: Array of role records matching the filter criteria
          items:
            $ref: '#/components/schemas/RoleResponse'
        page:
          $ref: '#/components/schemas/PageInfo'
    SortCriteria:
      type: object
      description: Sorting direction and field for list results
      properties:
        field:
          type: string
          description: Field name to sort by
        direction:
          type: string
          description: Sort direction
          enum:
          - asc
          - desc
    FilterOperand:
      type: object
      description: A single operand in a filter expression, either a field reference or a nested expression
      properties:
        field:
          type: string
          description: Field name to filter on
        value:
          type: string
          description: Value to compare against
    PageRequest:
      type: object
      description: Pagination parameters for list requests
      properties:
        offset:
          type: integer
          description: Zero-based starting index of the result page
          minimum: 0
        length:
          type: integer
          description: Maximum number of results to return per page
          minimum: 1
          maximum: 1000
    Permission:
      type: object
      description: A single permission entry granting access to a specific feature or resource
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the permission
        action:
          type: string
          description: The action permitted (e.g., view, create, run, edit, delete)
        resourceType:
          type: string
          description: The type of resource this permission applies to
        resourceId:
          type: integer
          format: int64
          description: Specific resource ID if this is a resource-scoped permission
    Error:
      type: object
      description: Standard error response returned when an API request fails
      properties:
        code:
          type: string
          description: Error code identifying the error type
        message:
          type: string
          description: Human-readable description of the error
        details:
          type: array
          description: Additional error context or field-level validation errors
          items:
            type: string
    CreateRoleRequest:
      type: object
      description: Payload to create a new Control Room role
      required:
      - name
      properties:
        name:
          type: string
          description: Unique name for the new role
        description:
          type: string
          description: Human-readable description of the role's purpose
        permissions:
          type: array
          description: List of permission objects granting access to features
          items:
            $ref: '#/components/schemas/Permission'
    FilterExpression:
      type: object
      description: Logical filter expression for querying resources
      properties:
        operator:
          type: string
          description: Logical operator combining child filters (and, or, not)
          enum:
          - and
          - or
          - not
          - eq
          - ne
          - lt
          - le
          - gt
          - ge
          - substring
          - startswith
        operands:
          type: array
          description: Child filter expressions or field/value pairs
          items:
            $ref: '#/components/schemas/FilterOperand'
    RoleResponse:
      type: object
      description: Full role record returned from create, read, or update operations
      properties:
        id:
          type: integer
          format: int64
          description: Unique numeric identifier of the role
        name:
          type: string
          description: Role name
        description:
          type: string
          description: Role description
        permissions:
          type: array
          description: Permissions granted by this role
          items:
            $ref: '#/components/schemas/Permission'
        createdBy:
          type: integer
          format: int64
          description: ID of the user who created the role
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the role was created
        updatedBy:
          type: integer
          format: int64
          description: ID of the user who last modified the role
        updatedOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last update
    UpdateRoleRequest:
      type: object
      description: Payload to update an existing Control Room role
      properties:
        name:
          type: string
          description: Updated name for the role
        description:
          type: string
          description: Updated description of the role's purpose
        permissions:
          type: array
          description: Updated set of permissions; replaces existing permissions
          items:
            $ref: '#/components/schemas/Permission'
    FilterRequest:
      type: object
      description: Generic filtering, pagination, and sorting request body used across list endpoints throughout the Control Room API.
      properties:
        filter:
          $ref: '#/components/schemas/FilterExpression'
        fields:
          type: array
          description: List of field names to include in the response
          items:
            type: string
        sort:
          type: array
          description: Sorting criteria for the result set
          items:
            $ref: '#/components/schemas/SortCriteria'
        page:
          $ref: '#/components/schemas/PageRequest'
  parameters:
    RoleIdParam:
      name: id
      in: path
      required: true
      description: Unique numeric identifier of the role
      schema:
        type: integer
        format: int64
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from the Authentication API
    xAuthorization:
      type: apiKey
      in: header
      name: X-Authorization
      description: JWT token obtained from the Authentication API
externalDocs:
  description: Automation Anywhere API Task Documentation
  url: https://docs.automationanywhere.com/bundle/enterprise-v2019/page/api-task-real-time-endpoint.html