automation-anywhere Files API

openapi: 3.1.0
info:
  title: Automation Anywhere API Task Execution AccessDetails Files 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: Files
  description: Manage individual bot files and their dependencies in the repository
paths:
  /file/list:
    post:
      operationId: listFiles
      summary: List files in the repository
      description: Retrieves a paginated, filterable list of bots, folders, and files stored in the repository. Supports filtering by name, path, type, and modification date. Returns metadata for each file including ID, name, path, size, version, and permissions. Used to discover and locate bot files programmatically.
      tags:
      - Files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterRequest'
      responses:
        '200':
          description: Paginated list of files and folders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /files/{fileid}/content:
    get:
      operationId: downloadFile
      summary: Download file contents
      description: Downloads the binary content of a specific file from the repository by its numeric file ID. Returns the file as a binary stream suitable for saving locally or processing programmatically. Requires view or download permission on the file.
      tags:
      - Files
      parameters:
      - $ref: '#/components/parameters/FileIdParam'
      responses:
        '200':
          description: File binary content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: File not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /files/{fileid}/dependencies:
    get:
      operationId: getFileDependencies
      summary: View file dependencies
      description: Retrieves the list of files that the specified bot depends on, including shared automation components, templates, and other bots referenced within the automation workflow. Useful for understanding the full dependency tree before exporting or migrating a bot.
      tags:
      - Files
      parameters:
      - $ref: '#/components/parameters/FileIdParam'
      responses:
        '200':
          description: List of file dependencies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileDependencyResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: File not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /files/{fileid}/dependencies/{workspaceId}:
    put:
      operationId: updateFileDependencies
      summary: Update manual file dependencies
      description: Updates the manually specified dependency list for a bot file within a given workspace. Used when automatic dependency detection is insufficient and dependencies must be declared explicitly.
      tags:
      - Files
      parameters:
      - $ref: '#/components/parameters/FileIdParam'
      - $ref: '#/components/parameters/WorkspaceIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DependencyUpdateRequest'
      responses:
        '200':
          description: Dependencies updated 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: File not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /files/{fileid}/parents:
    get:
      operationId: getFileParents
      summary: Get file parent folders
      description: Retrieves the immediate parent folder(s) of the specified file in the repository hierarchy. Returns the folder path and ID needed to navigate the repository structure.
      tags:
      - Files
      parameters:
      - $ref: '#/components/parameters/FileIdParam'
      responses:
        '200':
          description: Parent folder information for the file
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileParentsResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: File not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /files/{id}:
    delete:
      operationId: deleteFile
      summary: Delete a file
      description: Permanently deletes a file from the repository. The file must not have active automations running against it. Deleted files cannot be recovered from the API; use with caution.
      tags:
      - Files
      parameters:
      - $ref: '#/components/parameters/FileDeleteIdParam'
      responses:
        '200':
          description: File deleted successfully
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: File not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /files/packagesVersionUpdate:
    post:
      operationId: updatePackageVersions
      summary: Update package versions
      description: Executes a bulk package version update across one or more bot files, updating the referenced package versions to the latest available in the Control Room. Used during platform upgrades to ensure bots reference current package versions.
      tags:
      - Files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PackageVersionUpdateRequest'
      responses:
        '200':
          description: Package version update initiated 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'
  /files/version/assignLabel:
    post:
      operationId: assignVersionLabel
      summary: Assign production label to bot version
      description: Assigns the production label to a specific version of a bot file, marking it as the designated production-ready version. This label is used by deployment processes to identify which version of a bot should be deployed in production environments.
      tags:
      - Files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignLabelRequest'
      responses:
        '200':
          description: Production label assigned 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: File or version not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /recover:
    post:
      operationId: recoverBots
      summary: Recover bots from deleted user repository
      description: Recovers bots from the private workspace of a deleted user and moves them to a specified folder in the public workspace. Used by administrators to preserve automation assets when user accounts are removed from the Control Room.
      tags:
      - Files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecoverRequest'
      responses:
        '200':
          description: Bots recovered 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'
components:
  parameters:
    FileDeleteIdParam:
      name: id
      in: path
      required: true
      description: Unique numeric identifier of the file to delete
      schema:
        type: integer
        format: int64
    FileIdParam:
      name: fileid
      in: path
      required: true
      description: Unique numeric identifier of the file
      schema:
        type: integer
        format: int64
    WorkspaceIdParam:
      name: workspaceId
      in: path
      required: true
      description: Workspace identifier (PUBLIC or PRIVATE)
      schema:
        type: string
        enum:
        - PUBLIC
        - PRIVATE
  schemas:
    ObjectPermission:
      type: object
      description: Actions the current user can perform on a repository object
      properties:
        delete:
          type: boolean
          description: Whether the user can delete this object
        download:
          type: boolean
          description: Whether the user can download this object
        upload:
          type: boolean
          description: Whether the user can upload to this location
        run:
          type: boolean
          description: Whether the user can run this bot
        view:
          type: boolean
          description: Whether the user can view this object
        clone:
          type: boolean
          description: Whether the user can clone (copy) this object
    PageInfo:
      type: object
      description: Pagination metadata
      properties:
        offset:
          type: integer
          description: Starting index of returned results
        total:
          type: integer
          description: Total number of matching records
        totalFilter:
          type: integer
          description: Total records after filters applied
    RepositoryObject:
      type: object
      description: A file or folder in the Control Room repository
      properties:
        id:
          type: integer
          format: int64
          description: Unique numeric identifier of the repository object
        parentId:
          type: integer
          format: int64
          description: ID of the parent folder containing this object
        name:
          type: string
          description: Display name of the file or folder
        path:
          type: string
          description: Full repository path from the workspace root
        type:
          type: string
          description: Type of repository object
          enum:
          - FILE
          - FOLDER
          - BOT
        size:
          type: integer
          format: int64
          description: File size in bytes (0 for folders)
        version:
          type: integer
          description: Version number of the file (for versioned bot files)
        lastModifiedBy:
          type: string
          description: Username of the user who last modified this object
        lastModifiedOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last modification
        createdBy:
          type: string
          description: Username of the user who created this object
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the object was created
        workspaceType:
          type: string
          description: Workspace containing this object
          enum:
          - PUBLIC
          - PRIVATE
        permission:
          $ref: '#/components/schemas/ObjectPermission'
    PageRequest:
      type: object
      description: Pagination parameters
      properties:
        offset:
          type: integer
          description: Zero-based starting index
          minimum: 0
        length:
          type: integer
          description: Number of records per page
          minimum: 1
    PackageVersionUpdateRequest:
      type: object
      description: Payload to trigger package version updates on bot files
      properties:
        fileIds:
          type: array
          description: List of file IDs to update package versions for
          items:
            type: integer
            format: int64
            description: Numeric file ID
        packageName:
          type: string
          description: Name of the specific package to update (omit for all packages)
        targetVersion:
          type: string
          description: Target version to update to (omit to use latest available)
    DependencyUpdateRequest:
      type: object
      description: Payload to update manual dependencies for a file
      properties:
        dependencies:
          type: array
          description: List of file IDs to set as manual dependencies
          items:
            type: integer
            format: int64
            description: Numeric file ID of a dependency
    FileListResponse:
      type: object
      description: Paginated list of repository objects
      properties:
        list:
          type: array
          description: Array of repository object records
          items:
            $ref: '#/components/schemas/RepositoryObject'
        page:
          $ref: '#/components/schemas/PageInfo'
    FileParentsResponse:
      type: object
      description: Parent folder information for a repository object
      properties:
        parents:
          type: array
          description: List of parent folders in the hierarchy
          items:
            $ref: '#/components/schemas/RepositoryObject'
    Error:
      type: object
      description: Standard error response
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error description
    RecoverRequest:
      type: object
      description: Payload to recover bots from a deleted user's private workspace
      required:
      - userId
      properties:
        userId:
          type: integer
          format: int64
          description: Numeric ID of the deleted user whose bots should be recovered
        targetFolderId:
          type: integer
          format: int64
          description: Folder ID in the public workspace where recovered bots will be moved
    FileDependencyResponse:
      type: object
      description: Dependency information for a bot file
      properties:
        dependencies:
          type: array
          description: List of files this bot depends on
          items:
            $ref: '#/components/schemas/RepositoryObject'
    FilterRequest:
      type: object
      description: Generic filter and pagination request for list endpoints
      properties:
        filter:
          type: object
          description: Filter expression for narrowing results
        sort:
          type: array
          description: Sort criteria
          items:
            type: object
            properties:
              field:
                type: string
                description: Field to sort by
              direction:
                type: string
                enum:
                - asc
                - desc
                description: Sort direction
        page:
          $ref: '#/components/schemas/PageRequest'
    AssignLabelRequest:
      type: object
      description: Payload to assign the production label to a specific bot version
      required:
      - fileId
      - version
      properties:
        fileId:
          type: integer
          format: int64
          description: Numeric ID of the bot file
        version:
          type: integer
          description: Version number to assign the production label to
  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