openapi: 3.0.3
info:
  title: Appium Server Actions Elements API
  description: The Appium Server API implements the W3C WebDriver protocol for mobile, web, desktop, and TV app automation. It provides endpoints for session management, element interaction, actions, screenshots, and Appium-specific device commands.
  version: 2.0.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: Appium Community
    url: https://discuss.appium.io/
  x-generated-from: documentation
servers:
- url: http://localhost:4723
  description: Local Appium server (default port)
tags:
- name: Elements
  description: Element discovery and interaction
paths:
  /session/{sessionId}/element:
    post:
      operationId: findElement
      summary: Appium Find Element
      description: Finds the first element matching a given locator strategy and selector.
      tags:
      - Elements
      parameters:
      - $ref: '#/components/parameters/SessionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FindElementRequest'
            examples:
              FindElementRequestExample:
                summary: Default findElement request
                x-microcks-default: true
                value:
                  using: accessibility id
                  value: Login Button
      responses:
        '200':
          description: Element found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ElementResponse'
              examples:
                FindElement200Example:
                  summary: Default findElement 200 response
                  x-microcks-default: true
                  value:
                    value:
                      ELEMENT: 1234567890
                      element-6066-11e4-a52e-4f735466cecf: 1234567890
        '404':
          description: Element not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /session/{sessionId}/elements:
    post:
      operationId: findElements
      summary: Appium Find Elements
      description: Finds all elements matching a given locator strategy and selector.
      tags:
      - Elements
      parameters:
      - $ref: '#/components/parameters/SessionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FindElementRequest'
      responses:
        '200':
          description: Elements found (may be empty array)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ElementsResponse'
              examples:
                FindElements200Example:
                  summary: Default findElements 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - ELEMENT: 1234567890
                      element-6066-11e4-a52e-4f735466cecf: 1234567890
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /session/{sessionId}/element/{elementId}/click:
    post:
      operationId: click
      summary: Appium Click Element
      description: Clicks on the specified element.
      tags:
      - Elements
      parameters:
      - $ref: '#/components/parameters/SessionId'
      - $ref: '#/components/parameters/ElementId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Element clicked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyValueResponse'
              examples:
                Click200Example:
                  summary: Default click 200 response
                  x-microcks-default: true
                  value:
                    value: null
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /session/{sessionId}/element/{elementId}/value:
    post:
      operationId: setValue
      summary: Appium Send Keys to Element
      description: Sends text input to the specified element.
      tags:
      - Elements
      parameters:
      - $ref: '#/components/parameters/SessionId'
      - $ref: '#/components/parameters/ElementId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - text
              properties:
                text:
                  type: string
                  description: Text to send to the element
                  example: Hello World
      responses:
        '200':
          description: Text sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyValueResponse'
              examples:
                SetValue200Example:
                  summary: Default setValue 200 response
                  x-microcks-default: true
                  value:
                    value: null
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /session/{sessionId}/element/{elementId}/text:
    get:
      operationId: getText
      summary: Appium Get Element Text
      description: Returns the visible text of the specified element.
      tags:
      - Elements
      parameters:
      - $ref: '#/components/parameters/SessionId'
      - $ref: '#/components/parameters/ElementId'
      responses:
        '200':
          description: Element text returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StringValueResponse'
              examples:
                GetText200Example:
                  summary: Default getText 200 response
                  x-microcks-default: true
                  value:
                    value: Login
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /session/{sessionId}/source:
    get:
      operationId: getPageSource
      summary: Appium Get Page Source
      description: Returns the XML source of the current app screen or browser page.
      tags:
      - Elements
      parameters:
      - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: Page source returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StringValueResponse'
              examples:
                GetPageSource200Example:
                  summary: Default getPageSource 200 response
                  x-microcks-default: true
                  value:
                    value: <hierarchy rotation="0"><android.widget.FrameLayout /></hierarchy>
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ElementsResponse:
      title: ElementsResponse
      description: Multiple elements returned from a find operation
      type: object
      properties:
        value:
          type: array
          items:
            type: object
            properties:
              ELEMENT:
                type: string
                example: '1234567890'
              element-6066-11e4-a52e-4f735466cecf:
                type: string
                example: '1234567890'
    EmptyValueResponse:
      title: EmptyValueResponse
      description: Standard response with null value
      type: object
      properties:
        value:
          nullable: true
          description: Always null for commands that have no return value
    ErrorResponse:
      title: ErrorResponse
      description: WebDriver error response
      type: object
      properties:
        value:
          type: object
          properties:
            error:
              type: string
              description: Error code
              example: no such element
            message:
              type: string
              description: Human-readable error message
              example: An element could not be located on the page using the given search parameters.
            stacktrace:
              type: string
              description: Stack trace for debugging
    StringValueResponse:
      title: StringValueResponse
      description: Standard response with a string value
      type: object
      properties:
        value:
          type: string
          description: The returned string value
    FindElementRequest:
      title: FindElementRequest
      description: Request to find an element using a locator strategy
      type: object
      required:
      - using
      - value
      properties:
        using:
          type: string
          description: The element locator strategy
          enum:
          - accessibility id
          - id
          - xpath
          - class name
          - name
          - css selector
          - link text
          - partial link text
          - -android uiautomator
          - -android datamatcher
          - -ios predicate string
          - -ios class chain
          example: accessibility id
        value:
          type: string
          description: The selector value for the locator strategy
          example: Login Button
    ElementResponse:
      title: ElementResponse
      description: Single element returned from a find operation
      type: object
      properties:
        value:
          type: object
          description: Element reference object
          properties:
            ELEMENT:
              type: string
              description: Legacy element identifier
              example: '1234567890'
            element-6066-11e4-a52e-4f735466cecf:
              type: string
              description: W3C element identifier
              example: '1234567890'
  parameters:
    SessionId:
      name: sessionId
      in: path
      required: true
      description: The unique session identifier
      schema:
        type: string
      example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    ElementId:
      name: elementId
      in: path
      required: true
      description: The unique element identifier within the session
      schema:
        type: string
      example: '1234567890'