Automation Anywhere Workload Management API

openapi: 3.1.0
info:
  title: Automation Anywhere Workload Management API
  description: >-
    The Automation Anywhere Workload Management API provides programmatic control
    over work item queues used to distribute high-volume automation workloads
    across multiple Bot Runner devices. Developers can create and manage work
    item models and queues, add or update individual work items, and retrieve
    queue status and processing results. This API enables enterprise systems such
    as ERP, CRM, and BPM platforms to feed structured data into RPA queues and
    track processing outcomes in real time. The v4 endpoints provide the most
    current capabilities including file-based work item creation, consumer and
    member management, and expiry configuration.
  version: 'v4'
  contact:
    name: Automation Anywhere Support
    url: https://support.automationanywhere.com
  termsOfService: https://www.automationanywhere.com/terms-of-service
externalDocs:
  description: Automation Anywhere Workload Management API v4 Documentation
  url: https://docs.automationanywhere.com/bundle/enterprise-v2019/page/wlm-api-supported-v4.html
servers:
  - url: https://{controlRoomUrl}/v4/wlm
    description: Automation Anywhere Control Room Workload Management v4
    variables:
      controlRoomUrl:
        default: your-control-room.automationanywhere.com
        description: Your Control Room hostname
tags:
  - name: Queues
    description: Create and manage work item queues and their members
  - name: WorkItemModels
    description: Create and retrieve work item data models defining queue schema
  - name: WorkItems
    description: Add, update, and manage individual work items within queues
security:
  - bearerAuth: []
  - xAuthorization: []
paths:
  /workitemmodels:
    post:
      operationId: createWorkItemModel
      summary: Create a work item model
      description: >-
        Creates a new work item model that defines the data schema for work
        items in associated queues. A work item model specifies the attribute
        names and types that each work item must contain, enabling structured
        data processing by bots.
      tags:
        - WorkItemModels
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkItemModel'
      responses:
        '200':
          description: Work item model created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkItemModel'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workitemmodels/{id}:
    get:
      operationId: getWorkItemModel
      summary: Get a work item model by ID
      description: >-
        Retrieves a specific work item model by its numeric identifier,
        including the full list of attributes defining the model's data schema.
      tags:
        - WorkItemModels
      parameters:
        - $ref: '#/components/parameters/ModelIdParam'
      responses:
        '200':
          description: Work item model details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkItemModel'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Work item model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /queues/{id}:
    get:
      operationId: getQueue
      summary: Get a queue by ID
      description: >-
        Retrieves detailed information about a specific work item queue,
        including its configuration, associated work item model, processing
        order, and current status.
      tags:
        - Queues
      parameters:
        - $ref: '#/components/parameters/QueueIdParam'
      responses:
        '200':
          description: Queue details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Queue'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Queue not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /queues/{id}/consumers:
    post:
      operationId: addQueueConsumer
      summary: Add a queue consumer
      description: >-
        Adds a role as a consumer of the specified queue. Consumer roles
        are assigned to bots that will process work items from the queue.
        Only users with queue management permissions can add consumers.
      tags:
        - Queues
      parameters:
        - $ref: '#/components/parameters/QueueIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueueConsumerRequest'
      responses:
        '200':
          description: Consumer added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueConsumer'
        '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: Queue not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /queues/{id}/members/{userId}:
    put:
      operationId: addOrUpdateQueueMember
      summary: Add or update a queue member
      description: >-
        Adds a user as a member of the specified queue or updates the
        existing membership configuration. Queue members are human users
        who can manage queue operations such as reviewing failed items.
      tags:
        - Queues
      parameters:
        - $ref: '#/components/parameters/QueueIdParam'
        - $ref: '#/components/parameters/UserIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueueMemberRequest'
      responses:
        '200':
          description: Queue member added or updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueMember'
        '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: Queue or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /queues/{id}/participants:
    post:
      operationId: addQueueParticipant
      summary: Add a queue participant
      description: >-
        Adds a participant to the specified queue. Participants can view
        queue status and work item data but have limited management
        permissions compared to queue owners or members.
      tags:
        - Queues
      parameters:
        - $ref: '#/components/parameters/QueueIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueueParticipantRequest'
      responses:
        '200':
          description: Participant added successfully
        '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: Queue not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /queues/{id}/workitems/{workItemId}:
    put:
      operationId: updateWorkItem
      summary: Update a work item
      description: >-
        Updates the status, result, or JSON data payload of an existing work
        item in the queue. Used by bots and administrators to mark work items
        as complete, failed, or deferred, and to store processing results.
      tags:
        - WorkItems
      parameters:
        - $ref: '#/components/parameters/QueueIdParam'
        - $ref: '#/components/parameters/WorkItemIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkItemRequest'
      responses:
        '200':
          description: Work item updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkItem'
        '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: Queue or work item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /queues/{id}/file:
    post:
      operationId: createWorkItemsFromFile
      summary: Create work items from a file
      description: >-
        Bulk-creates work items in a queue by uploading a CSV or Excel file.
        Each row in the file becomes a work item mapped to the queue's work
        item model attributes. This is the recommended approach for high-volume
        data ingestion into RPA queues.
      tags:
        - WorkItems
      parameters:
        - $ref: '#/components/parameters/QueueIdParam'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: CSV or Excel file containing work item data rows
      responses:
        '200':
          description: Work items created successfully from file
        '400':
          description: Bad request or invalid file format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Queue not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  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, passed as X-Authorization header
  parameters:
    QueueIdParam:
      name: id
      in: path
      required: true
      description: Unique numeric identifier of the queue
      schema:
        type: integer
        format: int64
    ModelIdParam:
      name: id
      in: path
      required: true
      description: Unique numeric identifier of the work item model
      schema:
        type: integer
        format: int64
    WorkItemIdParam:
      name: workItemId
      in: path
      required: true
      description: Unique numeric identifier of the work item
      schema:
        type: integer
        format: int64
    UserIdParam:
      name: userId
      in: path
      required: true
      description: Unique numeric identifier of the user
      schema:
        type: integer
        format: int64
  schemas:
    WorkItemModel:
      type: object
      description: >-
        Schema definition for work items in a queue, specifying the attributes
        (columns) and their data types that each work item must contain.
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the work item model
        name:
          type: string
          description: Name of the work item model
        attributes:
          type: array
          description: List of attribute definitions making up the work item schema
          items:
            $ref: '#/components/schemas/WorkItemAttribute'
        createdBy:
          type: integer
          format: int64
          description: ID of the user who created this model
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the model was created
        updatedBy:
          type: integer
          format: int64
          description: ID of the user who last modified this model
        updatedOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last modification
        version:
          type: integer
          description: Optimistic locking version number
        tenantId:
          type: integer
          format: int64
          description: Tenant identifier for multi-tenant deployments
        tenantUuid:
          type: string
          description: UUID of the tenant
    WorkItemAttribute:
      type: object
      description: A single named attribute in a work item model
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the attribute
        name:
          type: string
          description: Attribute name used as the column identifier in work items
        type:
          type: string
          description: Data type of the attribute value
          enum:
            - TEXT
            - NUMBER
            - DATE
            - BOOLEAN
        isRequired:
          type: boolean
          description: Whether this attribute must be provided when creating a work item
    Queue:
      type: object
      description: >-
        A work item queue that buffers data items for processing by bots.
        Each queue is linked to a work item model defining its schema.
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the queue
        name:
          type: string
          description: Human-readable name of the queue
        description:
          type: string
          description: Description of the queue's purpose
        reactivationThreshold:
          type: integer
          description: >-
            Percentage threshold of remaining work items below which the queue
            triggers reactivation of additional bot instances
        manualProcessingTime:
          type: integer
          description: Estimated manual processing time per work item for SLA calculations
        manualProcessingTimeUnit:
          type: string
          description: Time unit for manualProcessingTime (e.g., minutes, hours)
        disallowDuplicate:
          type: boolean
          description: Whether duplicate work items based on hash are rejected
        autoRetryLimit:
          type: integer
          description: Maximum number of times a failed work item is automatically retried
        status:
          type: string
          description: Current operational status of the queue
          enum:
            - ACTIVE
            - INACTIVE
        workItemModelId:
          type: integer
          format: int64
          description: ID of the work item model defining this queue's data schema
        workItemProcessingOrders:
          type: array
          description: Ordered list of field names defining work item processing priority
          items:
            type: string
        expiry:
          $ref: '#/components/schemas/QueueExpiry'
        createdBy:
          type: integer
          format: int64
          description: ID of the user who created this queue
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the queue was created
        updatedBy:
          type: integer
          format: int64
          description: ID of the user who last modified this queue
        updatedOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last modification
        version:
          type: integer
          description: Optimistic locking version number
    QueueExpiry:
      type: object
      description: Expiry configuration for work items in the queue
      properties:
        type:
          type: string
          description: Expiry type (e.g., DURATION, DATE)
        duration:
          type: integer
          description: Duration value before work items expire
        durationUnit:
          type: string
          description: Time unit for the duration (e.g., HOURS, DAYS)
    WorkItem:
      type: object
      description: A single unit of work in a queue, representing one data record to be processed by a bot
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the work item
        queueId:
          type: integer
          format: int64
          description: ID of the queue this work item belongs to
        json:
          type: object
          description: Key-value map of the work item's data payload matching the queue's work item model attributes
          additionalProperties: true
        status:
          type: string
          description: Current processing status of the work item
          enum:
            - NEW
            - IN_PROGRESS
            - FAILED
            - COMPLETE
            - DEFERRED
        result:
          type: string
          description: Processing result set by the bot upon completion
          enum:
            - SUCCESS
            - FAILURE
        col1:
          type: string
          description: Display column 1 value extracted from the work item data
        col2:
          type: string
          description: Display column 2 value extracted from the work item data
        col3:
          type: string
          description: Display column 3 value extracted from the work item data
        deviceId:
          type: integer
          format: int64
          description: ID of the device that processed this work item
        deviceUserId:
          type: integer
          format: int64
          description: ID of the user account under which the work item was processed
        automationId:
          type: string
          description: Deployment ID of the automation that processed this work item
        startTime:
          type: string
          format: date-time
          description: ISO 8601 timestamp when processing began
        endTime:
          type: string
          format: date-time
          description: ISO 8601 timestamp when processing completed
        comment:
          type: string
          description: Optional comment added during processing
        error:
          type: string
          description: Error message if the work item processing failed
        retryCount:
          type: integer
          description: Number of times this work item has been retried
        deferredUntil:
          type: string
          format: date-time
          description: ISO 8601 timestamp until which this work item is deferred
        createdBy:
          type: integer
          format: int64
          description: ID of the user who created this work item
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the work item was created
        version:
          type: integer
          description: Optimistic locking version number
    UpdateWorkItemRequest:
      type: object
      description: Payload to update a work item's status, result, or data
      required:
        - id
        - queueId
        - version
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the work item to update
        queueId:
          type: integer
          format: int64
          description: ID of the queue containing the work item
        version:
          type: integer
          description: Current optimistic locking version number (must match server value)
        status:
          type: string
          description: New processing status for the work item
          enum:
            - IN_PROGRESS
            - FAILED
            - COMPLETE
            - DEFERRED
        result:
          type: string
          description: Processing result to record on the work item
          enum:
            - SUCCESS
            - FAILURE
        json:
          type: object
          description: Updated data payload for the work item
          additionalProperties: true
    QueueConsumerRequest:
      type: object
      description: Request to add a role as a consumer of a queue
      properties:
        roleId:
          type: integer
          format: int64
          description: ID of the role to grant consumer access to the queue
    QueueConsumer:
      type: object
      description: A role with consumer access to a queue
      properties:
        roleId:
          type: integer
          format: int64
          description: ID of the consumer role
        roleName:
          type: string
          description: Name of the consumer role
    QueueMemberRequest:
      type: object
      description: Request to add or update a user as a queue member
      properties:
        role:
          type: string
          description: Queue membership role (OWNER, MEMBER, PARTICIPANT)
          enum:
            - OWNER
            - MEMBER
            - PARTICIPANT
    QueueMember:
      type: object
      description: A user with membership access to a queue
      properties:
        userId:
          type: integer
          format: int64
          description: ID of the queue member user
        role:
          type: string
          description: Membership role of the user in this queue
    QueueParticipantRequest:
      type: object
      description: Request to add a participant to a queue
      properties:
        userId:
          type: integer
          format: int64
          description: ID of the user to add as a participant
    Error:
      type: object
      description: Standard error response
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error description