openapi: 3.1.0
info:
  title: Automation Anywhere API Task Execution AccessDetails Users 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: Users
  description: Create, list, retrieve, update, and delete Control Room users
paths:
  /v2/usermanagement/users:
    post:
      operationId: createUser
      summary: Create a user
      description: Creates a new user in the Control Room with the specified username, email, roles, and other attributes. The caller must have the AAE_Admin or user management permissions to invoke this endpoint.
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '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/users/list:
    post:
      operationId: listUsers
      summary: List users
      description: Retrieves a paginated, filterable list of Control Room users. Supports filtering by username, email, role, and other attributes. The response includes user metadata and assigned roles.
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterRequest'
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '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/users/{uid}:
    get:
      operationId: getUser
      summary: Get user by ID
      description: Retrieves detailed information about a specific Control Room user, including their roles, permissions, license assignments, and account status.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/UserIdParam'
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateUser
      summary: Update a user
      description: Updates an existing Control Room user's attributes including email, roles, license type, and enabled/disabled status. Replaces the full user record with the provided values.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/UserIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '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: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteUser
      summary: Delete a user
      description: Permanently deletes a Control Room user account. This action cannot be undone. All automations associated with the user's private workspace may need to be recovered separately using the repository recovery API.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/UserIdParam'
      responses:
        '204':
          description: User deleted successfully
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    UserIdParam:
      name: uid
      in: path
      required: true
      description: Unique numeric identifier of the user
      schema:
        type: integer
        format: int64
  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
    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
    UpdateUserRequest:
      type: object
      description: Payload to update an existing Control Room user account
      properties:
        email:
          type: string
          format: email
          description: Updated email address for the user
        firstName:
          type: string
          description: Updated first name
        lastName:
          type: string
          description: Updated last name
        roles:
          type: array
          description: Updated list of role assignments; replaces existing assignments
          items:
            $ref: '#/components/schemas/RoleRef'
        licenseFeatures:
          type: array
          description: Updated license feature types
          items:
            type: string
        enabled:
          type: boolean
          description: Whether the user account is active
        password:
          type: string
          description: New password for the user
    RoleRef:
      type: object
      description: Reference to a role by its numeric ID
      properties:
        id:
          type: integer
          format: int64
          description: Numeric identifier of the referenced role
        name:
          type: string
          description: Name of the referenced role
    UserListResponse:
      type: object
      description: Paginated list of user records
      properties:
        list:
          type: array
          description: Array of user records matching the filter criteria
          items:
            $ref: '#/components/schemas/UserResponse'
        page:
          $ref: '#/components/schemas/PageInfo'
    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
    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'
    UserResponse:
      type: object
      description: Full user record returned from create, read, or update operations
      properties:
        id:
          type: integer
          format: int64
          description: Unique numeric identifier of the user
        username:
          type: string
          description: The user's login username
        email:
          type: string
          format: email
          description: The user's email address
        firstName:
          type: string
          description: User's first name
        lastName:
          type: string
          description: User's last name
        roles:
          type: array
          description: Roles assigned to the user
          items:
            $ref: '#/components/schemas/RoleRef'
        licenseFeatures:
          type: array
          description: License features assigned to the user
          items:
            type: string
        enabled:
          type: boolean
          description: Whether the user account is currently active
        createdBy:
          type: integer
          format: int64
          description: ID of the user who created this account
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the user was created
        updatedBy:
          type: integer
          format: int64
          description: ID of the user who last updated this account
        updatedOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last update
    CreateUserRequest:
      type: object
      description: Payload to create a new Control Room user account
      required:
      - username
      - email
      - password
      properties:
        username:
          type: string
          description: Unique username for the new user
        email:
          type: string
          format: email
          description: Email address associated with the user account
        password:
          type: string
          description: Initial password for the user (not required for SSO-only users)
        firstName:
          type: string
          description: User's first name
        lastName:
          type: string
          description: User's last name
        roles:
          type: array
          description: List of role IDs to assign to the user
          items:
            $ref: '#/components/schemas/RoleRef'
        licenseFeatures:
          type: array
          description: License feature types assigned to the user (e.g., ATTENDED, UNATTENDED)
          items:
            type: string
        enabled:
          type: boolean
          description: Whether the user account is active and can log in
    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'
  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