openapi: 3.0.1
security:
- BearerAuth: []
servers:
- description: ThousandEyes API production URL
  url: https://api.thousandeyes.com/v7
info:
  version: 7.0.100
  title: Administrative API
  description: "Manage users, accounts, and account groups in the ThousandEyes platform using the Administrative API.\nThis\
    \ API provides the following operations to manage your organization: \n\n  * `/account-groups`: Account groups are used\
    \ to divide an organization into different sections. These operations can be used to create, retrieve, update and delete\
    \ account groups.\n  * `/users`: Create, retrieve, update and delete users within an organization. \n  * `/roles`: Create,\
    \ retrieve and update roles for the current user. \n  * `/permissions`: Retrieve all assignable permissions. Used in the\
    \ context of modifying roles. \n  * `/audit-user-events`: Retrieve all activity log events.\n\n  For more information\
    \ about the administrative models, see [Account Management](https://docs.thousandeyes.com/product-documentation/user-management)."
  x-provenance:
    method: harvested
    authored_by: Cisco ThousandEyes
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    provider_published: true
    source_host: pubhub.devnetcloud.com
    note: 27 OpenAPI 3.0 documents (26 per-area plus a unified 326-operation document) served anonymously from Cisco's DevNet
      CDN. api.thousandeyes.com itself 401s every path, so the contract is public while the API host is gated.
  x-evidence:
  - type: source
    url: https://pubhub.devnetcloud.com/media/000-v7-apis/docs/reference/
  - type: source
    url: https://developer.cisco.com/docs/thousandeyes/
externalDocs:
  description: Find out more about the administrative models
  url: https://docs.thousandeyes.com/product-documentation/user-management
tags:
- name: Account Groups
  description: Account group CRUD operations
- name: Users
  description: User CRUD operations
- name: Roles
  description: Role CRUD operations
- name: Permissions
  description: Permission GET operation
- name: User Events
  description: User events GET operation
paths:
  /account-groups:
    get:
      tags:
      - Account Groups
      summary: List account groups
      operationId: getAccountGroups
      description: Retrieves a list of account groups available to the current user.
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/AccountGroups'
            application/json:
              schema:
                $ref: '#/components/schemas/AccountGroups'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    post:
      tags:
      - Account Groups
      summary: Create account group
      operationId: createAccountGroup
      description: 'Creates a new account group. This operation requires the `Edit all account groups` permission.


        **Note:** Any user assigned to `All Account Groups` is automatically assigned to the new account group.'
      parameters:
      - $ref: '#/components/parameters/ExpandAccountGroup'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountGroupRequest'
        required: true
      responses:
        '201':
          description: Created
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/CreatedAccountGroup'
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedAccountGroup'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /account-groups/{id}:
    get:
      tags:
      - Account Groups
      summary: Retrieve account group
      operationId: getAccountGroup
      description: Retrieves detailed information about an account group using its ID.  This operation requires the `View
        all account groups settings` permission.
      parameters:
      - $ref: '#/components/parameters/AccountGroupIdPath'
      - $ref: '#/components/parameters/ExpandAccountGroup'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/AccountGroupDetail'
            application/json:
              schema:
                $ref: '#/components/schemas/AccountGroupDetail'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    put:
      tags:
      - Account Groups
      summary: Update account group
      operationId: updateAccountGroup
      description: Updates an account group using its ID. You can modify the account group’s name or the list of agents assigned
        to the account group.
      parameters:
      - $ref: '#/components/parameters/AccountGroupIdPath'
      - $ref: '#/components/parameters/ExpandAccountGroup'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountGroupRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/AccountGroupDetail'
            application/json:
              schema:
                $ref: '#/components/schemas/AccountGroupDetail'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    delete:
      tags:
      - Account Groups
      summary: Delete account group
      operationId: deleteAccountGroup
      description: "Deletes an account group using its ID. This operation requires the following permissions:\n\n  * Assign\
        \ management permissions\n  * Delete account\n  * Edit all account groups"
      parameters:
      - $ref: '#/components/parameters/AccountGroupIdPath'
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /users:
    get:
      tags:
      - Users
      summary: List users
      operationId: getUsers
      description: Retrieves a list of users in the organization the account group ID belongs to. This operation requires
        the `API Access` and `View all users` permissions. See [Account Context](https://developer.thousandeyes.com/v7/#/accountcontext)
        for more information on changing the account group context.
      parameters:
      - $ref: '#/components/parameters/AccountGroupId'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Users'
            application/json:
              schema:
                $ref: '#/components/schemas/Users'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    post:
      tags:
      - Users
      summary: Create user
      operationId: createUser
      description: "Creates a new user.\n\nThe following applies when creating a user: \n* If the user is already a member\
        \ of another ThousandEyes customer organization, the user must set their own login account group. \n* Any update that\
        \ includes `accountGroupRoles` is a replace-based update and not a delta-based update."
      parameters:
      - $ref: '#/components/parameters/AccountGroupId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequest'
        required: true
      responses:
        '201':
          description: Created
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/CreatedUser'
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedUser'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /users/{id}:
    get:
      tags:
      - Users
      summary: Retrieve user
      operationId: getUser
      description: Retrieves detailed information about a user. This operation requires the `API Access` and `View All Users`
        permissions.
      parameters:
      - $ref: '#/components/parameters/UserIdPath'
      - $ref: '#/components/parameters/AccountGroupId'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/UserDetail'
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    put:
      tags:
      - Users
      summary: Update user
      operationId: updateUser
      description: "Updates a user using the user ID. You can update the user name, email address, account group assignments,\
        \ or roles. This operation requires the `Edit users in all account groups` or `Edit users` permission. \n\nWhen updating\
        \ a user, the following applies:\n* When updating a user's email address, the user must confirm the username change\
        \ before they can subsequently log in or perform API operations.\n* Any update that includes `accountGroupRoles` is\
        \ a replace-based update and not a delta-based update."
      parameters:
      - $ref: '#/components/parameters/UserIdPath'
      - $ref: '#/components/parameters/AccountGroupId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/UserDetail'
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    delete:
      tags:
      - Users
      summary: Delete user
      operationId: deleteUser
      description: Deletes a user using the user ID. This operation requires the `Edit users in all account groups` or `Edit
        users` permission.
      parameters:
      - $ref: '#/components/parameters/UserIdPath'
      - $ref: '#/components/parameters/AccountGroupId'
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /users/current:
    get:
      tags:
      - Users
      summary: Retrieve current user
      operationId: getCurrentUser
      description: Retrieves detailed information about the current user.
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/UserDetail'
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /roles:
    get:
      tags:
      - Roles
      summary: List roles
      operationId: getRoles
      description: Retrieves a list of defined roles visible to the current user.
      parameters:
      - $ref: '#/components/parameters/AccountGroupId'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Roles'
            application/json:
              schema:
                $ref: '#/components/schemas/Roles'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    post:
      tags:
      - Roles
      summary: Create role
      operationId: createRole
      description: Creates a new role.
      parameters:
      - $ref: '#/components/parameters/AccountGroupId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleRequestBody'
        required: true
      responses:
        '201':
          description: Created
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/RoleDetail'
            application/json:
              schema:
                $ref: '#/components/schemas/RoleDetail'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /roles/{id}:
    get:
      tags:
      - Roles
      summary: Retrieve role
      operationId: getRole
      description: Returns detailed information about a role using its ID.
      parameters:
      - $ref: '#/components/parameters/RoleId'
      - $ref: '#/components/parameters/AccountGroupId'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/RoleDetail'
            application/json:
              schema:
                $ref: '#/components/schemas/RoleDetail'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    put:
      tags:
      - Roles
      summary: Update role
      operationId: updateRole
      description: "Updates a user-defined role using its ID.\n\nWhen updating a role, the following applies: \n* The full\
        \ list of permissions must be sent, This operation does not support delta-based grant or revoking of permissions.\
        \ \n* Permission definitions and details can be obtained from the Permissions operation."
      parameters:
      - $ref: '#/components/parameters/RoleId'
      - $ref: '#/components/parameters/AccountGroupId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleRequestBody'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/RoleDetail'
            application/json:
              schema:
                $ref: '#/components/schemas/RoleDetail'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    delete:
      tags:
      - Roles
      summary: Delete role
      operationId: deleteRole
      description: Deletes a role using its ID. The user needs appropriate permissions to successfully call this operation.
      parameters:
      - $ref: '#/components/parameters/RoleId'
      - $ref: '#/components/parameters/AccountGroupId'
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /audit-user-events:
    get:
      tags:
      - User Events
      summary: List activity log events
      operationId: getUserEvents
      description: "Returns a list of activity log events in the current account group. \n\nIf `useAllPermittedAids=true`\
        \ query parameter is passed and the user has permission `View activity log for all users in account group` the logs\
        \ returned include events across all the account groups they belong to.\n\nFor more information about changing the\
        \ account group context, see [Account Context](https://developer.thousandeyes.com/v7/#/accountcontext)."
      parameters:
      - $ref: '#/components/parameters/AccountGroupId'
      - $ref: '#/components/parameters/UseAllPermittedAids'
      - $ref: '#/components/parameters/Window'
      - $ref: '#/components/parameters/StartDateParameter'
      - $ref: '#/components/parameters/EndDateParameter'
      - $ref: '#/components/parameters/PaginationCursor'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/AuditUserEvents'
            application/json:
              schema:
                $ref: '#/components/schemas/AuditUserEvents'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /permissions:
    get:
      tags:
      - Permissions
      summary: List assignable permissions
      operationId: getPermissions
      description: Users must be in a role assigned management permissions to access this operation. Users without management
        permissions who attempt to access this operation receive an HTTP/403 response code.
      parameters:
      - $ref: '#/components/parameters/AccountGroupId'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Permissions'
            application/json:
              schema:
                $ref: '#/components/schemas/Permissions'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
  parameters:
    RoleId:
      name: id
      description: The ID of the desired role.
      required: true
      in: path
      schema:
        type: string
        example: '23'
    ExpandAccountGroup:
      name: expand
      in: query
      style: form
      explode: false
      description: Optional parameter that specifies whether or not account group related resources should be expanded. By
        default, no expansion takes place if the query parameter is not passed. For example, to expand the `users` resource,
        pass the `?expand=user` query.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/ExpandAccountGroupOptions'
        example:
        - user
    AccountGroupIdPath:
      name: id
      description: Identifier for the account group.
      required: true
      in: path
      schema:
        type: string
        example: '1234'
    AccountGroupId:
      name: aid
      in: query
      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.
      required: false
      schema:
        type: string
        example: '1234'
    UserIdPath:
      name: id
      description: Identifier for the user.
      required: true
      in: path
      schema:
        type: string
        example: '1234'
    UseAllPermittedAids:
      name: useAllPermittedAids
      in: query
      required: false
      description: Set to `true` to load data from all accounts the user has access to.
      schema:
        type: boolean
        example: false
        default: false
    Window:
      name: window
      in: query
      description: 'A dynamic time interval up to the current time of the request. Specify the interval as a number followed
        by an optional type: `s` for seconds (default if no type is specified), `m` for minutes, `h` for hours, `d` for days,
        and `w` for weeks.

        For a precise date range, use `startDate` and `endDate`.'
      schema:
        type: string
        pattern: ^\d+(?:[smhdw]{1})?$
        example: 12h
    StartDateParameter:
      name: startDate
      in: query
      description: Use with the `endDate` parameter. Include the complete time (hours, minutes, and seconds) in UTC time zone,
        following the ISO 8601 date-time format. See the example for reference. Please note that this parameter can't be used
        with `window`.
      schema:
        type: string
        format: date-time
        example: '2022-07-17T22:00:54Z'
    EndDateParameter:
      name: endDate
      in: query
      description: Defaults to current time the request is made. Use with the `startDate` parameter. Include the complete
        time (hours, minutes, and seconds) in UTC time zone, following the ISO 8601 date-time format. See the example for
        reference. Please note that this parameter can't be used with `window`.
      schema:
        type: string
        format: date-time
        example: '2022-07-18T22:00:54Z'
    PaginationCursor:
      name: cursor
      in: query
      example: null
      description: (Optional) Opaque cursor used for pagination. Clients should use `next` value from `_links` instead of
        this parameter.
      schema:
        type: string
        example: null
  schemas:
    ExpandAccountGroupOptions:
      type: string
      enum:
      - user
      - agent
    AccountGroupToken:
      type: string
      description: The account group token is an alphanumeric string used to bind an Enterprise Agent to a specific account
        group. This token is not a password that must be kept secret. You can retrieve your `AccountGroupToken` from the `/account-groups/{id}`
        endpoint.
      example: 6j052y4vfgyuhefghue
    AccountGroupInfo:
      allOf:
      - $ref: '#/components/schemas/AccountGroup'
      - type: object
        properties:
          isCurrentAccountGroup:
            type: boolean
            description: Indicates whether the requested aid is the context of the current account.
            example: true
          isDefaultAccountGroup:
            type: boolean
            description: Indicates whether the aid is the default one for the requesting user.
            example: true
          organizationName:
            type: string
            description: (Optional) The name of the organization associated with the account group.
          orgId:
            type: string
            description: (Optional) The ID for the organization associated with the account group.
            example: '12345'
    CreatedAccountGroup:
      allOf:
      - $ref: '#/components/schemas/AccountGroupInfo'
      - type: object
        properties:
          users:
            type: array
            items:
              $ref: '#/components/schemas/UserAccountGroup'
          _links:
            $ref: '#/components/schemas/SelfLinks'
    AccountGroupDetail:
      allOf:
      - $ref: '#/components/schemas/CreatedAccountGroup'
      - type: object
        properties:
          agents:
            type: array
            items:
              $ref: '#/components/schemas/EnterpriseAgent'
          accountToken:
            $ref: '#/components/schemas/AccountGroupToken'
            type: string
    AccountGroupRequest:
      type: object
      properties:
        accountGroupName:
          type: string
          description: The name of the account group
          example: My testing account group
        agents:
          type: array
          description: To grant access to enterprise agents, specify the agent list. Note that this is not an additive list
            - the full list must be specified if changing access to agents.
          items:
            type: string
          example:
          - '105'
          - '719'
      required:
      - accountGroupName
    AccountGroups:
      type: object
      properties:
        accountGroups:
          type: array
          items:
            $ref: '#/components/schemas/AccountGroupInfo'
        _links:
          $ref: '#/components/schemas/SelfLinks'
    AccountGroupRole:
      type: object
      properties:
        accountGroup:
          $ref: '#/components/schemas/AccountGroup'
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
    UserAccountGroupRole:
      type: object
      properties:
        accountGroupId:
          type: string
          description: Unique ID of the account group.
          example: '315'
        roleIds:
          type: array
          description: Unique role IDs.
          items:
            type: string
            description: Unique role ID.
            example: '57'
          example:
          - '57'
          - '1140'
    UserRequest:
      type: object
      properties:
        name:
          type: string
          description: User's display name.
          example: User X
        email:
          type: string
          description: User's email address.
          format: email
          example: userx@thousandeyes.com
        loginAccountGroupId:
          type: string
          description: Unique ID of the login account group.
          example: '691'
        accountGroupRoles:
          type: array
          items:
            $ref: '#/components/schemas/UserAccountGroupRole'
        allAccountGroupRoleIds:
          type: array
          description: Unique IDs representing the roles.
          items:
            type: string
            description: Unique role ID.
            example: '57'
          example:
          - '57'
          - '1140'
    User:
      type: object
      properties:
        name:
          type: string
          description: User's display name.
          example: User X
        email:
          type: string
          description: User's email address.
          format: email
          example: userx@thousandeyes.com
        uid:
          type: string
          description: Unique ID of the user.
          example: '245'
        dateRegistered:
          type: string
          description: UTC date the user registered their account (ISO date-time format).
          format: date-time
          example: '2020-07-17T22:00:54Z'
        loginAccountGroup:
          $ref: '#/components/schemas/AccountGroup'
    ExtendedUser:
      allOf:
      - $ref: '#/components/schemas/User'
      - type: object
        properties:
          lastLogin:
            type: string
            description: UTC last login of the user (ISO date-time format).
            format: date-time
            example: '2022-07-17T22:00:54Z'
    Users:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/ExtendedUser'
        _links:
          $ref: '#/components/schemas/SelfLinks'
    CreatedUser:
      allOf:
      - $ref: '#/components/schemas/User'
      - type: object
        properties:
          loginAccountGroup:
            $ref: '#/components/schemas/AccountGroup'
          accountGroupRoles:
            type: array
            items:
              $ref: '#/components/schemas/AccountGroupRole'
          allAccountGroupRoles:
            type: array
            items:
              $ref: '#/components/schemas/Role'
          _links:
            $ref: '#/components/schemas/SelfLinks'
    UserDetail:
      allOf:
      - $ref: '#/components/schemas/ExtendedUser'
      - type: object
        properties:
          loginAccountGroup:
            $ref: '#/components/schemas/AccountGroup'
          accountGroupRoles:
            type: array
            items:
              $ref: '#/components/schemas/AccountGroupRole'
          allAccountGroupRoles:
            type: array
            items:
              $ref: '#/components/schemas/Role'
          _links:
            $ref: '#/components/schemas/SelfLinks'
    UserAccountGroup:
      type: object
      properties:
        name:
          type: string
          description: User's display name.
          example: User X
        email:
          type: string
          description: User's email address.
          format: email
          example: userx@thousandeyes.com
        uid:
          type: string
          description: Unique ID representing the user.
          example: '235'
        lastLogin:
          type: string
          description: User's UTC last login date (ISO date-time format).
          format: date-time
          example: '2022-07-17T22:00:54Z'
        dateRegistered:
          type: string
          description: User's UTC registration date (ISO date-time format).
          format: date-time
          example: '2022-07-17T22:00:54Z'
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
    BaseRole:
      type: object
      properties:
        name:
          type: string
          description: Name of the role.
          example: Organization Admin
        roleId:
          type: string
          description: Unique ID representing the role.
          example: '35'
        isBuiltin:
          type: boolean
          description: Flag indicating if the role is built-in (Account Admin, Organization Admin, Regular User).
    Role:
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseRole'
      - properties:
          hasManagementPermissions:
            type: boolean
            description: Flag indicating whether the user has management permissions.
    Permission:
      type: object
      properties:
        label:
          type: string
          description: Label corresponding to the permission.
          example: View reports
        permissionId:
          type: string
          description: Unique ID representing the permission.
          example: '56'
        isManagementPermission:
          description: Flag indicating whether the permission is classified as a management permission.
          type: boolean
        permission:
          type: string
          description: Permission name
          example: REPORT_SNAPSHOTS_READ
    PermissionsCollection:
      type: array
      items:
        $ref: '#/components/schemas/Permission'
      example:
      - label: View reports
        permissionId: '1'
        isManagementPermission: true
        permission: REPORT_READ
      - label: View snapshots
        permissionId: '51'
        isManagementPermission: false
        permission: REPORT_SNAPSHOTS_READ
    Permissions:
      type: object
      properties:
        permissions:
          $ref: '#/components/schemas/PermissionsCollection'
        _links:
          $ref: '#/components/schemas/SelfLinks'
    RoleDetail:
      allOf:
      - $ref: '#/components/schemas/BaseRole'
      - type: object
        properties:
          permissions:
            $ref: '#/components/schemas/PermissionsCollection'
          _links:
            $ref: '#/components/schemas/SelfLinks'
    Roles:
      type: object
      properties:
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
        _links:
          $ref: '#/components/schemas/SelfLinks'
    RoleRequestBody:
      type: object
      properties:
        name:
          type: string
          description: Name of the role.
          example: Organization Admin
        permissions:
          type: array
          description: Contains list of test permission IDs (get `permissionId` from `/permissions` operation)
          items:
            type: string
          example:
          - '56'
          - '315'
    UserEvent:
      type: object
      properties:
        aid:
          $ref: '#/components/schemas/AccountGroupId'
        accountGroupName:
          type: string
          description: Account group name
          example: Account A
        date:
          type: string
          description: UTC event date (ISO date-time format).
          format: date-time
          example: '2020-07-17T22:00:54Z'
        event:
          type: string
          description: Event type.
          example: Login failed.
        ipAddress:
          type: string
          description: Source IP address of the user.
          example: 99.128.0.0/11
        uid:
          type: string
          description: Unique id representing the user.
          example: '245'
        user:
          type: string
          description: The name and email address of the user.
          example: API Sandbox User (noreply@thousandeyes.com)
        resources:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
    Resource:
      type: object
      properties:
        type:
          type: string
          description: Type of resource affected. Can be “testName”, “reportTitle”, “userDisplayName”, “alertRuleName”, etc.
        name:
          type: string
          description: Name of the affected resource.
    AuditUserEvents:
      type: object
      properties:
        auditEvents:
          x-paginated-items: true
          type: array
          items:
            $ref: '#/components/schemas/UserEvent'
          example:
          - accountGroupName: API Sandbox
            aid: '1234'
            date: '2020-07-17T21:54:54Z'
            event: Report created.
            ipAddress: 99.128.0.0/11
            uid: '1234'
            user: API Sandbox User (noreply@thousandeyes.com)
            resources:
            - name: My New report
              type: reportTitle
            - name: Other Report
              type: testName
          - accountGroupName: API Sandbox
            aid: '1234'
            date: '2020-07-17T22:00:54Z'
            event: Login failed.
            ipAddress: 99.128.0.0/11
            uid: '1234'
            user: API Sandbox User (noreply@thousandeyes.com)
        startDate:
          $ref: '#/components/schemas/StartDate'
        endDate:
          $ref: '#/components/schemas/EndDate'
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    Error:
      type: object
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type. When this member is not present, its value is assumed
            to be "about:blank".
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.
    ValidationErrorItem:
      type: object
      properties:
        code:
          type: string
          description: (Optional) A unique error type/code that can be referenced in the documentation for further details.
        field:
          type: string
          description: Identifies the field that triggered this particular error.
        message:
          type: string
          description: A short, human-readable summary of the error.
    ValidationError:
      type: object
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        properties:
          errors:
            nullable: true
            type: array
            description: (Optional) When multiple errors occur, the details for each error are listed.
            items:
              $ref: '#/components/schemas/ValidationErrorItem'
    UnauthorizedError:
      type: object
      properties:
        error:
          type: string
          example: invalid_token
        error_description:
          type: string
          example: Invalid access token
    AccountGroupId:
      type: string
      description: A unique identifier associated with your account group. You can retrieve your `AccountGroupId` from the
        `/account-groups` endpoint.
      example: '1234'
    AccountGroup:
      type: object
      properties:
        aid:
          $ref: '#/components/schemas/AccountGroupId'
        accountGroupName:
          type: string
          description: Account group name
          example: Account A
    Link:
      type: object
      description: A hyperlink from the containing resource to a URI.
      required:
      - href
      properties:
        href:
          type: string
          description: Its value is either a URI [RFC3986] or a URI template [RFC6570].
          example: https://api.thousandeyes.com/v7/link/to/resource/id
        templated:
          type: boolean
          description: Should be true when the link object's "href" property is a URI template.
        type:
          type: string
          description: Used as a hint to indicate the media type expected when dereferencing the target resource.
        deprecation:
          type: string
          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.
        name:
          type: string
          description: Its value may be used as a secondary key for selecting link objects that share the same relation type.
        profile:
          type: string
          description: A URI that hints about the profile of the target resource.
        title:
          type: string
          description: Intended for labelling the link with a human-readable identifier
        hreflang:
          type: string
          description: Indicates the language of the target resource
    SelfLinks:
      type: object
      description: A links object containing the self link.
      readOnly: true
      properties:
        self:
          $ref: '#/components/schemas/Link'
    CloudEnterpriseAgentType:
      type: string
      description: Type of the agent.
      enum:
      - cloud
      - enterprise-cluster
      - enterprise
      example: enterprise-cluster
      readOnly: true
    AgentBase:
      type: object
      properties:
        ipAddresses:
          type: array
          description: Array of private IP addresses.
          readOnly: true
          items:
            type: string
          example:
          - 99.139.65.220
          - 9bbd:8a0a:a257:5876:288b:6cb2:3f36:64ce
        publicIpAddresses:
          type: array
          description: Array of public IP addresses.
          readOnly: true
          items:
            type: string
          example:
          - 192.168.1.78
          - f9b2:3a21:f25c:d300:03f4:586d:f8d6:4e1c
        network:
          type: string
          description: Network (including ASN) of agent’s public IP.
          example: AT&T Services, Inc. (AS 7018)
          readOnly: true
    Coordinates:
      type: object
      description: Geographic coordinates for agent location.
      properties:
        latitude:
          type: number
          format: double
          description: The latitude of the agent location in decimal degrees
          example: 37.77493
          readOnly: true
        longitude:
          type: number
          format: double
          description: The longitude of the agent location in decimal degrees
          example: -122.41942
          readOnly: true
    NetworkProviderType:
      type: string
      description: Classification of the agent's network provider.
      enum:
      - unknown
      - isp
      - cdn
      - stub
      - cloud-provider
      - carrier
      example: isp
      readOnly: true
    NetworkProviderInfo:
      type: object
      description: Information about the network provider that owns the agent's public IP prefix.
      readOnly: true
      properties:
        asn:
          type: integer
          format: int64
          description: Autonomous System Number (ASN) announcing the agent's public IP prefix.
          example: 7018
          readOnly: true
        name:
          type: string
          description: Name of the network provider organization.
          example: AT&T Services, Inc.
          readOnly: true
        type:
          $ref: '#/components/schemas/NetworkProviderType'
    SimpleAgent:
      type: object
      allOf:
      - $ref: '#/components/schemas/AgentBase'
      - type: object
        properties:
          agentId:
            type: string
            description: Unique ID of the agent.
            example: '281474976710706'
            readOnly: true
          agentName:
            type: string
            description: Name of the agent.
            example: thousandeyes-stg-va-254
          location:
            type: string
            description: Location of the agent.
            example: San Francisco Bay Area
            readOnly: true
          countryId:
            type: string
            description: 2-digit ISO country code
            example: US
            readOnly: true
          coordinates:
            $ref: '#/components/schemas/Coordinates'
          networkProviderInfo:
            allOf:
            - $ref: '#/components/schemas/NetworkProviderInfo'
            readOnly: true
            example:
              asn: 7018
              name: AT&T Services, Inc.
              type: isp
          enabled:
            type: boolean
            description: Flag indicating if the agent is enabled.
            example: true
          verifySslCertificates:
            type: boolean
            description: Flag indicating if has normal SSL operations or  if instead it's set to ignore SSL errors on browserbot-based
              tests.
            example: true
            readOnly: true
          prefix:
            type: string
            description: Prefix containing agents public IP address.
            example: 99.128.0.0/11
            readOnly: true
    AgentResponse:
      allOf:
      - required:
        - agentType
        properties:
          agentType:
            $ref: '#/components/schemas/CloudEnterpriseAgentType'
      - $ref: '#/components/schemas/SimpleAgent'
    TestIds:
      type: array
      description: List of test IDs assigned to the agent.
      items:
        type: integer
        format: int64
      readOnly: true
      example:
      - 281474976710706
    TestInterval:
      type: integer
      enum:
      - 60
      - 120
      - 300
      - 600
      - 900
      - 1800
      - 3600
      description: Interval between test runs in seconds.
      default: 60
      example: 60
    Enabled:
      type: boolean
      description: Test is enabled.
      example: true
      default: true
    TestCreatedBy:
      type: string
      description: User that created the test.
      example: user@user.com
      readOnly: true
    TestCreatedDate:
      type: string
      format: date-time
      description: UTC created date (ISO date-time format).
      example: '2022-07-17T22:00:54Z'
      readOnly: true
    TestType:
      type: string
      enum:
      - api
      - agent-to-agent
      - agent-to-server
      - bgp
      - http-server
      - page-load
      - web-transactions
      - ftp-server
      - dns-trace
      - dns-server
      - dnssec
      - sip-server
      - voice
      description: This is a read only value, as test type is implicit in the test creation url.
      readOnly: true
      example: agent-to-server
    TestSelfLink:
      allOf:
      - $ref: '#/components/schemas/Link'
      - description: Reference to the test.
        example:
          href: https://api.thousandeyes.com/v7/tests/{type}/281474976710706
    TestResults:
      type: array
      description: Reference to the test results.
      items:
        $ref: '#/components/schemas/Link'
      example:
      - href: https://api.thousandeyes.com/v7/test-results/281474976710706/network
      - href: https://api.thousandeyes.com/v7/test-results/281474976710706/path-vis
    TestLinks:
      type: object
      description: A list of links that can be accessed to get more information
      properties:
        self:
          $ref: '#/components/schemas/TestSelfLink'
        testResults:
          $ref: '#/components/schemas/TestResults'
      readOnly: true
    SimpleTest:
      description: Each test includes additional fields depending on its `type`. Refer `/tests/{type}` endpoint to know the
        set of fields returned by a given `type`.
      additionalProperties: true
      type: object
      properties:
        interval:
          $ref: '#/components/schemas/TestInterval'
        alertsEnabled:
          type: boolean
          description: Indicates if alerts are enabled.
          example: true
        enabled:
          $ref: '#/components/schemas/Enabled'
        createdBy:
          $ref: '#/components/schemas/TestCreatedBy'
        createdDate:
          $ref: '#/components/schemas/TestCreatedDate'
        description:
          type: string
          description: A description of the test.
          example: ThousandEyes Test
        liveShare:
          type: boolean
          description: Indicates if the test is shared with the account group.
          example: false
          readOnly: true
        modifiedBy:
          type: string
          description: User that modified the test.
          example: user@user.com
          readOnly: true
        modifiedDate:
          type: string
          format: date-time
          description: UTC last modification date (ISO date-time format).
          readOnly: true
          example: '2022-07-17T22:00:54Z'
        savedEvent:
          type: boolean
          description: 'Indicates if the test is a saved event.


            **Note**: **Saved Events** are now called **Private Snapshots** in the user interface. This change does not affect
            API.

            '
          readOnly: true
        testId:
          type: string
          description: Each test is assigned an unique ID; this is used to access test information and results from other
            endpoints.
          readOnly: true
          example: '281474976710706'
        testName:
          type: string
          description: The name of the test. Test name must be unique.
          example: ThousandEyes Test
        type:
          $ref: '#/components/schemas/TestType'
        _links:
          $ref: '#/components/schemas/TestLinks'
    ErrorDetailCode:
      type: string
      description: Code for the agent error.
      enum:
      - agent-version-outdated
      - browserbot-version-outdated
      - appliance-version-outdated
      - clock-offset
      - os-end-of-installation-support
      - os-end-of-support
      - os-end-of-life
      - nat-traversal-error
      example: agent-version-outdated
      readOnly: true
    ErrorDetail:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorDetailCode'
        description:
          type: string
          description: Description for the agent error.
          example: 'Agent Version 0.1.1 (latest: 1.0.0)'
          readOnly: true
    EnterpriseAgentState:
      type: string
      description: State of the agent.
      enum:
      - online
      - offline
      - disabled
      example: online
      readOnly: true
    EnterpriseAgentSerialNumber:
      type: string
      description: Serial number of an enterprise agent or cluster member device. This field is not available for Cloud Agents.
      example: FOC2218ABCD
      readOnly: true
    ClusterMember:
      allOf:
      - $ref: '#/components/schemas/AgentBase'
      - type: object
        properties:
          memberId:
            type: string
            description: Unique ID of the cluster member
            example: '10'
            readOnly: true
          name:
            type: string
            description: Name of the cluster member
            example: Cluster member name
            readOnly: true
          errorDetails:
            type: array
            description: If an enterprise agent or a cluster member presents at least one error, the errors will be shown
              as an array of entries in the errorDetails field (Enterprise Agents and Enterprise Cluster members only)
            items:
              $ref: '#/components/schemas/ErrorDetail'
            readOnly: true
          lastSeen:
            type: string
            description: UTC last seen date (ISO date-time format).
            format: date-time
            example: '2022-07-17T22:00:54Z'
            readOnly: true
          agentState:
            $ref: '#/components/schemas/EnterpriseAgentState'
          targetForTests:
            type: string
            format: ipv4
            description: Test target IP address.
            example: 1.1.1.1
          serialNumber:
            $ref: '#/components/schemas/EnterpriseAgentSerialNumber'
          utilization:
            type: integer
            description: Shows overall utilization percentage (online Enterprise Agents and Enterprise Clusters only).
            example: 25
            readOnly: true
    ClusterMembers:
      type: array
      description: If an enterprise agent is clustered, detailed information about each cluster member will be shown as array
        entries in the clusterMembers field. This field is not shown for Enterprise Agents in standalone mode, or for Cloud
        Agents.
      items:
        $ref: '#/components/schemas/ClusterMember'
      readOnly: true
    EnterpriseAgentIpv6Policy:
      type: string
      description: IP version policy, (Enterprise Agents and Enterprise Clusters only)
      enum:
      - force-ipv4
      - prefer-ipv6
      - force-ipv6
      example: force-ipv4
    InterfaceIpMapping:
      type: object
      properties:
        interfaceName:
          type: string
          description: Name of the mapping
          example: wlp4s0
          readOnly: true
        ipAddresses:
          type: array
          description: Array of ipAddress entries
          items:
            type: string
          example:
          - 73.252.207.219
          - 2601:646:300:3ae0::b977
          readOnly: true
    EnterpriseAgentData:
      type: object
      properties:
        testIds:
          $ref: '#/components/schemas/TestIds'
        tests:
          type: array
          description: List of tests. See `/tests` for more information.
          items:
            $ref: '#/components/schemas/SimpleTest'
        clusterMembers:
          $ref: '#/components/schemas/ClusterMembers'
        utilization:
          type: integer
          description: Shows overall utilization percentage (online Enterprise Agents and Enterprise Clusters only).
          example: 25
          readOnly: true
        accountGroups:
          type: array
          description: List of account groups. See /accounts-groups to pull a list of account IDs
          items:
            $ref: '#/components/schemas/AccountGroup'
        ipv6Policy:
          $ref: '#/components/schemas/EnterpriseAgentIpv6Policy'
        errorDetails:
          type: array
          description: If an enterprise agent or a cluster member presents at least one error, the errors will be shown as
            an array of entries in the errorDetails field (Enterprise Agents and Enterprise Cluster members only)
          items:
            $ref: '#/components/schemas/ErrorDetail'
          readOnly: true
        hostname:
          type: string
          description: Fully qualified domain name of the agent (Enterprise Agents only)
          example: thousandeyes.com
          readOnly: true
        lastSeen:
          type: string
          description: UTC last seen date (ISO date-time format).
          format: date-time
          example: '2022-07-17T22:00:54Z'
          readOnly: true
        agentState:
          $ref: '#/components/schemas/EnterpriseAgentState'
        keepBrowserCache:
          type: boolean
          description: Flag indicating if the agent retains cache.
          example: true
        createdDate:
          type: string
          description: UTC Agent creation date (ISO date-time format).
          format: date-time
          example: '2022-07-17T22:00:54Z'
          readOnly: true
        targetForTests:
          type: string
          format: ipv4
          description: Test target IP address.
          example: 1.1.1.1
        serialNumber:
          $ref: '#/components/schemas/EnterpriseAgentSerialNumber'
        localResolutionPrefixes:
          type: array
          description: To perform rDNS lookups for public IP ranges, this field represents the public IP ranges. The range
            must be in CIDR notation; for example, 10.1.1.0/24. Maximum of 5 prefixes allowed (Enterprise Agents and Enterprise
            Agent clusters only).
          items:
            type: string
            example: 10.2.3.3/24
        interfaceIpMapping:
          type: array
          items:
            $ref: '#/components/schemas/InterfaceIpMapping'
          readOnly: true
    EnterpriseAgent:
      allOf:
      - $ref: '#/components/schemas/AgentResponse'
      - $ref: '#/components/schemas/EnterpriseAgentData'
    StartDate:
      type: string
      format: date-time
      example: '2022-07-17T22:00:54Z'
      description: (Optional) When passing `window` or `startDate` parameter,  the client will also receive the `startDate`
        field indicating the UTC start date of the data's time range being retrieved  (ISO date-time format).
      readOnly: true
    EndDate:
      type: string
      format: date-time
      example: '2022-07-18T22:00:54Z'
      description: (Optional) When passing `window` or `endDate` parameter,  the client will also receive the `endDate` field
        indicating the UTC end date of the data's time range being retrieved  (ISO date-time format).
      readOnly: true
    PaginationLinks:
      type: object
      description: A links object containing pagination related link(s).
      properties:
        previous:
          $ref: '#/components/schemas/Link'
        next:
          $ref: '#/components/schemas/Link'
        self:
          $ref: '#/components/schemas/Link'
  responses:
    '204':
      description: No content
    '400':
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ValidationError'
          example:
            type: about:blank
            title: Request validation failed. There are invalid or missing fields
            status: 400
            detail: Your request object contains invalid fields.
            instance: /v7
            errors:
            - code: AM-5432
              field: firstName
              message: firstName cannot have fancy characters
            - code: DASH-5622
              field: password
              message: Password cannot be blank
    '401':
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
    '403':
      description: Insufficient permissions to query endpoint
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    '404':
      description: Not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          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
    '429':
      description: Exhausted rate limit for the organization
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    '500':
      description: Internal server error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: about:blank
            title: Internal server error
            status: 500
            detail: Optional detail about the internal error message.
            instance: /v7
  headers:
    Location:
      schema:
        type: string
        format: uri
        example: https://api.thousandeyes.com/v7/link/to/resource/id
      description: The absolute path to created resource.