openapi: 3.1.0
info:
  title: Automation Anywhere API Task Execution AccessDetails Credentials 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: Credentials
  description: Create, retrieve, update, delete, and search credentials
paths:
  /credentials:
    post:
      operationId: createCredential
      summary: Create a credential
      description: Creates a new credential in the Credential Vault. A credential consists of a name, optional description, and one or more typed attributes (such as username and password fields). Once created, credentials must be added to a Locker to be accessible by bots.
      tags:
      - Credentials
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialPost'
      responses:
        '200':
          description: Credential created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /credentials/list:
    post:
      operationId: listCredentials
      summary: Search credentials
      description: Searches for credentials where the authenticated user is the owner or has access through a Locker. Supports filtering, sorting, and pagination. Only credential metadata is returned; attribute values are not included in list responses.
      tags:
      - Credentials
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterRequest'
      responses:
        '200':
          description: Filtered list of credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialFilterResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /credentials/{id}:
    get:
      operationId: getCredential
      summary: Get a credential by ID
      description: Retrieves a specific credential by its numeric ID, including its attributes and current values if the caller has access. The consumed query parameter controls whether to return attribute values intended for bot consumption.
      tags:
      - Credentials
      parameters:
      - $ref: '#/components/parameters/CredentialIdParam'
      - $ref: '#/components/parameters/ConsumedParam'
      responses:
        '200':
          description: Credential details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Credential not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateCredential
      summary: Update a credential
      description: Updates an existing credential's name, description, or attributes. The caller must be the credential owner or have admin permissions. All attributes must be included in the request; omitted attributes will be removed.
      tags:
      - Credentials
      parameters:
      - $ref: '#/components/parameters/CredentialIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Credential'
      responses:
        '200':
          description: Credential updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
        '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: Credential not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteCredential
      summary: Delete a credential
      description: Permanently deletes a credential and all its associated attribute values from the Credential Vault. The credential must first be removed from any Lockers before it can be deleted.
      tags:
      - Credentials
      parameters:
      - $ref: '#/components/parameters/CredentialIdParam'
      responses:
        '200':
          description: Credential deleted successfully
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Credential not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /credentials/{id}/owner/{credentialOwnerId}:
    put:
      operationId: updateCredentialOwner
      summary: Update credential ownership
      description: Transfers ownership of a credential to another user. The new owner gains full administrative control over the credential including the ability to update, delete, and manage locker assignments.
      tags:
      - Credentials
      parameters:
      - $ref: '#/components/parameters/CredentialIdParam'
      - name: credentialOwnerId
        in: path
        required: true
        description: Numeric ID of the user who will become the new credential owner
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Credential ownership updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
        '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: Credential or new owner not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Credential:
      type: object
      description: A credential stored in the Credential Vault with named attributes
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the credential
        name:
          type: string
          description: Human-readable name of the credential
        description:
          type: string
          description: Optional description of the credential's purpose
        ownerId:
          type: integer
          format: int64
          description: User ID of the credential owner
        attributes:
          type: array
          description: List of attribute definitions associated with this credential
          items:
            $ref: '#/components/schemas/CredentialAttribute'
        createdBy:
          type: integer
          format: int64
          description: ID of the user who created this credential
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the credential was created
        updatedBy:
          type: integer
          format: int64
          description: ID of the user who last modified this credential
        updatedOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last modification
    PageInfo:
      type: object
      description: Pagination metadata in list responses
      properties:
        offset:
          type: integer
          description: Starting index of the returned results
        total:
          type: integer
          description: Total number of records available
        totalFilter:
          type: integer
          description: Total records after filter criteria applied
    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
    CredentialAttribute:
      type: object
      description: An attribute definition associated with a credential
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the attribute
        name:
          type: string
          description: Attribute name (e.g., username, password)
        description:
          type: string
          description: Description of what this attribute contains
        masked:
          type: boolean
          description: Whether this attribute's value should be masked in logs and UI
        userProvided:
          type: boolean
          description: Whether each user provides their own value for this attribute
    CredentialPost:
      type: object
      description: Payload to create a new credential
      required:
      - name
      properties:
        name:
          type: string
          description: Human-readable name for the new credential
        description:
          type: string
          description: Optional description of the credential's purpose
        attributes:
          type: array
          description: Attribute definitions for this credential
          items:
            $ref: '#/components/schemas/CredentialAttributePost'
    CredentialAttributePost:
      type: object
      description: Attribute definition for creating a new credential
      required:
      - name
      properties:
        name:
          type: string
          description: Attribute name
        description:
          type: string
          description: Description of the attribute
        masked:
          type: boolean
          description: Whether to mask this attribute's value
        userProvided:
          type: boolean
          description: Whether users provide their own values
    CredentialFilterResponse:
      type: object
      description: Paginated list of credentials matching search criteria
      properties:
        list:
          type: array
          description: Array of credential records
          items:
            $ref: '#/components/schemas/Credential'
        page:
          $ref: '#/components/schemas/PageInfo'
    Error:
      type: object
      description: Standard error response
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error description
    FilterRequest:
      type: object
      description: Generic filter, sort, and pagination request for list operations
      properties:
        filter:
          type: object
          description: Filter expression for narrowing results
        sort:
          type: array
          description: Sort criteria for the result set
          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'
  parameters:
    ConsumedParam:
      name: consumed
      in: query
      required: false
      description: Whether to return attribute values in bot-consumption format
      schema:
        type: boolean
    CredentialIdParam:
      name: id
      in: path
      required: true
      description: Unique numeric identifier of the credential
      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