openapi: 3.0.1
info:
  description: |
    The Emulation API facilitates the retrieval of user-agent strings for HTTP, pageload, and transaction tests. It also enables the retrieval and addition of emulated devices for pageload and transaction tests.

    To access Emulation API operations, the following permissions are required:

    * `Settings Tests Read` for read operations.
    * `Settings Tests Update` for write operations.
  title: Emulation API
  version: 7.0.34
servers:
- description: ThousandEyes API production URL
  url: https://api.thousandeyes.com/v7
security:
- BearerAuth: []
tags:
- name: Emulation
paths:
  /user-agents:
    get:
      description: Retrieves a list of user-agent strings.
      operationId: getUserAgents
      parameters:
      - description: A unique identifier associated with your account group. You can
          retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note
          that you must be assigned to the target account group. Specifying this parameter
          without being assigned to the target account group will result in an error
          response.
        in: query
        name: aid
        required: false
        schema:
          example: "1234"
          type: string
      responses:
        "200":
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/UserAgents'
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Insufficient permissions to query endpoint
        "404":
          content:
            application/problem+json:
              example:
                type: about:blank
                title: URI Resource Not Found
                status: 404
                detail: Details explaining if the 404 error is related to an invalid
                  URI or a wrong ID
                instance: /v7
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found
        "429":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Exhausted rate limit for the organization
        "500":
          content:
            application/problem+json:
              example:
                type: about:blank
                title: Internal server error
                status: 500
                detail: Optional detail about the internal error message.
                instance: /v7
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      summary: List user-agents
      tags:
      - Emulation
  /emulated-devices:
    get:
      description: Retrieves a list of emulated devices available for browser tests.
      operationId: getEmulatedDevices
      parameters:
      - description: |
          Optional query parameter that controls whether user-agent templates are included in the response.
          By default, user-agent templates are not included. To include them, add `?expand=user-agent` to the request.
        explode: false
        in: query
        name: expand
        required: false
        schema:
          example:
          - user-agent
          items:
            $ref: '#/components/schemas/ExpandEmulatedDeviceOptions'
          type: array
        style: form
      responses:
        "200":
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EmulatedDeviceResponses'
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Insufficient permissions to query endpoint
        "404":
          content:
            application/problem+json:
              example:
                type: about:blank
                title: URI Resource Not Found
                status: 404
                detail: Details explaining if the 404 error is related to an invalid
                  URI or a wrong ID
                instance: /v7
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found
        "429":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Exhausted rate limit for the organization
        "500":
          content:
            application/problem+json:
              example:
                type: about:blank
                title: Internal server error
                status: 500
                detail: Optional detail about the internal error message.
                instance: /v7
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      summary: List emulated devices
      tags:
      - Emulation
    post:
      description: Creates a new device for emulation.
      operationId: createEmulatedDevice
      parameters:
      - description: A unique identifier associated with your account group. You can
          retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note
          that you must be assigned to the target account group. Specifying this parameter
          without being assigned to the target account group will result in an error
          response.
        in: query
        name: aid
        required: false
        schema:
          example: "1234"
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmulatedDevice'
        required: true
      responses:
        "201":
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/EmulatedDeviceResponse'
          description: Created
        "401":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Insufficient permissions to query endpoint
        "404":
          content:
            application/problem+json:
              example:
                type: about:blank
                title: URI Resource Not Found
                status: 404
                detail: Details explaining if the 404 error is related to an invalid
                  URI or a wrong ID
                instance: /v7
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found
        "429":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Exhausted rate limit for the organization
        "500":
          content:
            application/problem+json:
              example:
                type: about:blank
                title: Internal server error
                status: 500
                detail: Optional detail about the internal error message.
                instance: /v7
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      summary: Create emulated device
      tags:
      - Emulation
components:
  parameters:
    ExpandEmulatedDevice:
      description: |
        Optional query parameter that controls whether user-agent templates are included in the response.
        By default, user-agent templates are not included. To include them, add `?expand=user-agent` to the request.
      explode: false
      in: query
      name: expand
      required: false
      schema:
        example:
        - user-agent
        items:
          $ref: '#/components/schemas/ExpandEmulatedDeviceOptions'
        type: array
      style: form
    AccountGroupId:
      description: A unique identifier associated with your account group. You can
        retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note that
        you must be assigned to the target account group. Specifying this parameter
        without being assigned to the target account group will result in an error
        response.
      in: query
      name: aid
      required: false
      schema:
        example: "1234"
        type: string
  responses:
    "401":
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
      description: Unauthorized
    "403":
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Insufficient permissions to query endpoint
    "404":
      content:
        application/problem+json:
          example:
            type: about:blank
            title: URI Resource Not Found
            status: 404
            detail: Details explaining if the 404 error is related to an invalid URI
              or a wrong ID
            instance: /v7
          schema:
            $ref: '#/components/schemas/Error'
      description: Not found
    "429":
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Exhausted rate limit for the organization
    "500":
      content:
        application/problem+json:
          example:
            type: about:blank
            title: Internal server error
            status: 500
            detail: Optional detail about the internal error message.
            instance: /v7
          schema:
            $ref: '#/components/schemas/Error'
      description: Internal server error
  schemas:
    UserAgents:
      properties:
        userAgents:
          items:
            $ref: '#/components/schemas/UserAgent'
          type: array
        _links:
          $ref: '#/components/schemas/SelfLinks'
      type: object
    UserAgent:
      properties:
        browser:
          description: The name of the web browser.
          example: Firefox
          type: string
        os:
          description: The operating system for the user-agent HTTP header.
          example: Windows
          type: string
        value:
          description: The text of the user-agent header.
          example: "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36\
            \ (KHTML, like Gecko) Chrome/118.0.5993.70 Mobile Safari/537.36"
          type: string
      type: object
    EmulatedDevice:
      properties:
        category:
          $ref: '#/components/schemas/EmulatedDeviceCategory'
        width:
          description: The width of the display of the emulated device.
          example: 1024
          maximum: 9999
          minimum: 50
          type: integer
        height:
          description: The height of the display of the emulated device.
          example: 768
          maximum: 9999
          minimum: 50
          type: integer
      required:
      - category
      - height
      - width
      type: object
    EmulatedDeviceResponses:
      properties:
        emulatedDevices:
          items:
            $ref: '#/components/schemas/EmulatedDeviceResponse'
          type: array
        _links:
          $ref: '#/components/schemas/SelfLinks'
      type: object
    EmulatedDeviceResponse:
      allOf:
      - $ref: '#/components/schemas/EmulatedDevice'
      - properties:
          name:
            description: The device name
            example: iPad Pro 12.9-in
            type: string
          codeName:
            description: A code corresponding to the device name.
            example: IPAD_PRO_12_9
            type: string
          id:
            description: ID of the emulated device.
            example: "11"
            type: string
          availableUserAgents:
            description: A list of user-agent strings for this emulated device.
            example:
            - "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36\
              \ (KHTML, like Gecko) Chrome/118.0.5993.70 Mobile Safari/537.36"
            - "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like\
              \ Gecko) Chrome/118.0.5993.70 Safari/537.36"
            items:
              type: string
            type: array
          defaultUserAgentTemplate:
            description: The default user-agent template to use for this device.
            example: Mozilla/5.0 (Android 4.4; Tablet; rv:70.0) Gecko/70.0 Firefox/70.0
            type: string
        type: object
    ExpandEmulatedDeviceOptions:
      enum:
      - user-agent
      type: string
    EmulatedDeviceCategory:
      description: The type of device being emulated.
      enum:
      - desktop
      - laptop
      - phone
      - tablet
      example: desktop
      type: string
    UnauthorizedError:
      properties:
        error:
          example: invalid_token
          type: string
        error_description:
          example: Invalid access token
          type: string
      type: object
    Error:
      properties:
        type:
          description: "A URI reference that identifies the problem type. When this\
            \ member is not present, its value is assumed to be \"about:blank\"."
          type: string
        title:
          description: "A short, human-readable summary of the problem type."
          type: string
        status:
          description: The HTTP status code generated by the origin server for this
            occurrence of the problem.
          type: integer
        detail:
          description: A human-readable explanation specific to this occurrence of
            the problem.
          type: string
        instance:
          description: A URI reference that identifies the specific occurrence of
            the problem.
          type: string
      type: object
    SelfLinks:
      description: A links object containing the self link.
      properties:
        self:
          $ref: '#/components/schemas/Link'
      readOnly: true
      type: object
    Link:
      description: A hyperlink from the containing resource to a URI.
      properties:
        href:
          description: "Its value is either a URI [RFC3986] or a URI template [RFC6570]."
          example: https://api.thousandeyes.com/v7/link/to/resource/id
          type: string
        templated:
          description: Should be true when the link object's "href" property is a
            URI template.
          type: boolean
        type:
          description: Used as a hint to indicate the media type expected when dereferencing
            the target resource.
          type: string
        deprecation:
          description: Its presence indicates that the link is to be deprecated at
            a future date. Its value is a URL that should provide further information
            about the deprecation.
          type: string
        name:
          description: Its value may be used as a secondary key for selecting link
            objects that share the same relation type.
          type: string
        profile:
          description: A URI that hints about the profile of the target resource.
          type: string
        title:
          description: Intended for labelling the link with a human-readable identifier
          type: string
        hreflang:
          description: Indicates the language of the target resource
          type: string
      required:
      - href
      type: object
  securitySchemes:
    BearerAuth:
      description: Bearer authentication token
      scheme: bearer
      type: http
