ThousandEyes Endpoint Agent Labels API

openapi: 3.2.0
info:
  version: 7.0.100
  title: ThousandEyes Endpoint Agent Labels API
  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/
servers:
- description: ThousandEyes API production URL
  url: https://api.thousandeyes.com/v7
tags:
- name: Endpoint Agent Labels
  x-displayName: Endpoint Agent Labels
paths:
  /endpoint/labels:
    get:
      summary: List labels
      description: Returns a list of labels.
      operationId: getEndpointLabels
      parameters:
      - $ref: '#/components/parameters/Endpoint_Agent_Labels_API_PaginationMax'
      - $ref: '#/components/parameters/Endpoint_Agent_Labels_API_PaginationCursor'
      - $ref: '#/components/parameters/Endpoint_Agent_Labels_API_ExpandLabel'
      - $ref: '#/components/parameters/Endpoint_Agent_Labels_API_AccountGroupId'
      tags:
      - Endpoint Agent Labels
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Endpoint_Agent_Labels_API_Labels'
        '401':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_401'
        '403':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_403'
        '429':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_429'
      security:
      - Endpoint_Agent_Labels_API_BearerAuth: []
    post:
      summary: Create label
      description: Creates a new label.
      operationId: createEndpointLabel
      tags:
      - Endpoint Agent Labels
      parameters:
      - $ref: '#/components/parameters/Endpoint_Agent_Labels_API_AccountGroupId'
      requestBody:
        description: Label settings
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Endpoint_Agent_Labels_API_LabelRequest'
      responses:
        '201':
          description: created
          headers:
            Location:
              $ref: '#/components/headers/Endpoint_Agent_Labels_API_Location'
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Endpoint_Agent_Labels_API_LabelResponse'
        '400':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_400'
        '401':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_401'
        '403':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_403'
        '429':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_429'
      security:
      - Endpoint_Agent_Labels_API_BearerAuth: []
  /endpoint/labels/{id}:
    parameters:
    - $ref: '#/components/parameters/Endpoint_Agent_Labels_API_LabelIdPath'
    get:
      summary: Retrieve label
      tags:
      - Endpoint Agent Labels
      description: Returns a single label using its ID.
      operationId: getEndpointLabel
      parameters:
      - $ref: '#/components/parameters/Endpoint_Agent_Labels_API_ExpandLabel'
      - $ref: '#/components/parameters/Endpoint_Agent_Labels_API_AccountGroupId'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Endpoint_Agent_Labels_API_LabelResponse'
        '401':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_401'
        '403':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_403'
        '404':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_404'
        '429':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_429'
      security:
      - Endpoint_Agent_Labels_API_BearerAuth: []
    patch:
      summary: Update label
      tags:
      - Endpoint Agent Labels
      description: Updates a label using its ID.
      parameters:
      - $ref: '#/components/parameters/Endpoint_Agent_Labels_API_AccountGroupId'
      requestBody:
        description: Fields to change on the agent
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Endpoint_Agent_Labels_API_Label'
      operationId: updateEndpointLabel
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Endpoint_Agent_Labels_API_LabelResponse'
        '400':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_400'
        '401':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_401'
        '403':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_403'
        '404':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_404'
        '429':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_429'
      security:
      - Endpoint_Agent_Labels_API_BearerAuth: []
    delete:
      summary: Delete label
      tags:
      - Endpoint Agent Labels
      parameters:
      - $ref: '#/components/parameters/Endpoint_Agent_Labels_API_AccountGroupId'
      description: Deletes the label from your account.
      operationId: deleteEndpointLabel
      responses:
        '204':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_204'
        '401':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_401'
        '403':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_403'
        '404':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_404'
        '429':
          $ref: '#/components/responses/Endpoint_Agent_Labels_API_429'
      security:
      - Endpoint_Agent_Labels_API_BearerAuth: []
components:
  responses:
    Endpoint_Agent_Labels_API_400:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Endpoint_Agent_Labels_API_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
    Endpoint_Agent_Labels_API_401:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Endpoint_Agent_Labels_API_UnauthorizedError'
    Endpoint_Agent_Labels_API_204:
      description: No content
    Endpoint_Agent_Labels_API_403:
      description: Insufficient permissions to query endpoint
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Endpoint_Agent_Labels_API_Error'
    Endpoint_Agent_Labels_API_404:
      description: Not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Endpoint_Agent_Labels_API_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
    Endpoint_Agent_Labels_API_429:
      description: Exhausted rate limit for the organization
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Endpoint_Agent_Labels_API_Error'
  parameters:
    Endpoint_Agent_Labels_API_LabelIdPath:
      name: id
      in: path
      required: true
      description: The unique identifier of the label to operate on.
      schema:
        $ref: '#/components/schemas/Endpoint_Agent_Labels_API_LabelId'
    Endpoint_Agent_Labels_API_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
    Endpoint_Agent_Labels_API_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'
    Endpoint_Agent_Labels_API_PaginationMax:
      name: max
      in: query
      description: (Optional) Maximum number of objects to return.
      schema:
        type: integer
        example: 5
    Endpoint_Agent_Labels_API_ExpandLabel:
      name: expand
      in: query
      description: This parameter is optional and determines whether to include additional details in the response. To specify multiple expansions, you can either separate the values with commas or specify the parameter multiple times.
      required: false
      style: form
      explode: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/Endpoint_Agent_Labels_API_ExpandLabelOptions'
      example:
      - filters
  schemas:
    Endpoint_Agent_Labels_API_PaginationNextAndSelfLink:
      type: object
      description: A links object containing a related link for forward pagination.
      properties:
        next:
          $ref: '#/components/schemas/Endpoint_Agent_Labels_API_Link'
        self:
          $ref: '#/components/schemas/Endpoint_Agent_Labels_API_Link'
    Endpoint_Agent_Labels_API_ValidationError:
      type: object
      allOf:
      - $ref: '#/components/schemas/Endpoint_Agent_Labels_API_Error'
      - type: object
        properties:
          errors:
            type:
            - array
            - 'null'
            description: (Optional) When multiple errors occur, the details for each error are listed.
            items:
              $ref: '#/components/schemas/Endpoint_Agent_Labels_API_ValidationErrorItem'
    Endpoint_Agent_Labels_API_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.
    Endpoint_Agent_Labels_API_LabelFilterMode:
      type: string
      description: 'Type of matching to be applied for the values:


        * `in`: The value on the agent must match one of the list of values provided.

        * `not-in`: The value on the agent must not match any of the list of values provided.

        '
      enum:
      - in
      - not-in
    Endpoint_Agent_Labels_API_ExpandLabelOptions:
      type: string
      enum:
      - filters
    Endpoint_Agent_Labels_API_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
    Endpoint_Agent_Labels_API_LabelResponse:
      allOf:
      - $ref: '#/components/schemas/Endpoint_Agent_Labels_API_Label'
      - type: object
        properties:
          _links:
            $ref: '#/components/schemas/Endpoint_Agent_Labels_API_SelfLinks'
    Endpoint_Agent_Labels_API_UnauthorizedError:
      type: object
      properties:
        error:
          type: string
          example: invalid_token
        error_description:
          type: string
          example: Invalid access token
    Endpoint_Agent_Labels_API_LabelId:
      type: string
      readOnly: true
      description: Label identifier.
      example: abc-123-def
    Endpoint_Agent_Labels_API_FilterType:
      type: string
      description: Type of filter - the data that will be used to filter.
      example: vpn-client-network
      enum:
      - agent-id
      - public-network
      - local-network
      - connection
      - gateway
      - platform
      - agent-type
      - vpn-vendor
      - vpn-gateway-address
      - vpn-client-network
      - vpn-client-address
      - ip-address-family
      - ssid
      - bssid
      - hostname
      - username
      - asn
    Endpoint_Agent_Labels_API_Label:
      description: A label definition.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Endpoint_Agent_Labels_API_LabelId'
        name:
          description: The label name.
          type: string
          readOnly: false
          example: Head office meeting rooms
        color:
          description: UI color
          type: string
          readOnly: false
          example: '#ff3333'
        matchType:
          $ref: '#/components/schemas/Endpoint_Agent_Labels_API_MatchType'
        filters:
          description: The filters combined using the matchType to determine the label's match.
          type: array
          readOnly: false
          items:
            $ref: '#/components/schemas/Endpoint_Agent_Labels_API_Filter'
    Endpoint_Agent_Labels_API_Labels:
      description: A list of Labels.
      type: object
      properties:
        labels:
          x-paginated-items: true
          type: array
          items:
            $ref: '#/components/schemas/Endpoint_Agent_Labels_API_LabelResponse'
        _links:
          $ref: '#/components/schemas/Endpoint_Agent_Labels_API_PaginationNextAndSelfLink'
    Endpoint_Agent_Labels_API_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.
    Endpoint_Agent_Labels_API_Filter:
      type: object
      properties:
        key:
          $ref: '#/components/schemas/Endpoint_Agent_Labels_API_FilterType'
        values:
          type: array
          example:
          - 10.1.1.0/24
          - 192.168.1.0/24
          items:
            type: string
            description: "Value depends on the key, and may change in the future.\n\n* `agent-id`: The agent identifiers.\n* `gateway`: The gateway IP to match.\n* `ssid`: A wildcard match on the SSID. Supports `*` for any characters and `?` for any single character.\n* `user-name`: A wildcard match on the users that use the agent. Supports `*` for any characters and `?` for any single character.\n* `hostname`: A wildcard match on the host name - supports `*` for any characters\nand `?` for any single character\n* `bssid`: BSSID for the wifi, lower case, with colons.\n* `platform`: Currently supports `Mac`, `Windows`, and `Linux`.\n* `asn`: Integer AS Number.\n* `public-network`: Network for agent's public IP in CIDR format, or IP for single IP. e.g. `192.45.32.0/22`.\n* `local-network`: Network for agent's local IP in CIDR format, or IP for single IP. e.g. `10.100.64.0/20`.\n* `connection`: Type of connection `Ethernet` or `Wireless`.\n* `agent-type`: Type of agent `endpoint`, `endpoint-pulse` or `endpoint-csc`.\n* `ip-address-family`: `ipv4` or `ipv6`.\n* `vpn-vendor`: Vendor of the VPN software. \n    Examples include: \n    \n    * `cisco-anyconnect`\n    * `palo-alto-globalprotect`\n    * `ivanti-connect-secure`\n    * `zscaler-internet-access`\n    * `f5-big-ip`\n* `vpn-gateway-address`: Server-side VPN connection IP address.\n* `vpn-client-network`: Network for the VPN client IP in CIDR format. For example, `10.100.32.128/25`.\n* `vpn-client-address`: The VPN client IP. For example, `10.100.32.165`.\n"
            example: 10.1.1.0/24
        mode:
          $ref: '#/components/schemas/Endpoint_Agent_Labels_API_LabelFilterMode'
    Endpoint_Agent_Labels_API_SelfLinks:
      type: object
      description: A links object containing the self link.
      readOnly: true
      properties:
        self:
          $ref: '#/components/schemas/Endpoint_Agent_Labels_API_Link'
    Endpoint_Agent_Labels_API_MatchType:
      description: 'Specifies how the filters are combined for matching this label.


        * `and`: All filters must be matched.

        * `or`: Any of the filters should match.

        '
      type: string
      readOnly: false
      enum:
      - and
      - or
      example: and
    Endpoint_Agent_Labels_API_LabelRequest:
      allOf:
      - required:
        - name
        - matchType
        - filters
      - $ref: '#/components/schemas/Endpoint_Agent_Labels_API_Label'
  headers:
    Endpoint_Agent_Labels_API_Location:
      schema:
        type: string
        format: uri
        example: https://api.thousandeyes.com/v7/link/to/resource/id
      description: The absolute path to created resource.
  securitySchemes:
    Tests_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Test_Results_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Instant_Tests_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    ThousandEyes_for_OpenTelemetry_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Test_Snapshots_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Usage_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Templates_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    BGP_Monitors_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Internet_Insights_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Tags_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Integrations_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Event_Detection_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Endpoint_Tests_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Endpoint_Test_Results_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Endpoint_Agent_Labels_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Endpoint_Instant_Scheduled_Tests_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Endpoint_Agents_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Emulation_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Dashboards_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Credentials_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Cloud_Insights_Integrations_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Autonomous_Systems_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    API_Token_Management_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Alerts_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Agents_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
    Administrative_API_BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
externalDocs:
  description: Find out more about ThousandEyes
  url: https://developer.thousandeyes.com/
x-tagGroups:
- name: Tests API
  tags:
  - Tests
  - Agent to Server Tests
  - Agent to Agent Tests
  - BGP Tests
  - DNS Server Tests
  - DNS Trace Tests
  - DNSSEC Tests
  - HTTP Server Tests
  - Page Load Tests
  - Web Transaction Tests
  - API Tests
  - FTP Server Tests
  - SIP Server Tests
  - Voice Tests
  - Path Visualization Interface Groups
- name: Test Results API
  tags:
  - Network Test Results
  - Web HTTP Server Test Results
  - Web Page Load Test Results
  - Web Transactions Test Results
  - API Test Results
  - Web FTP Server Test Results
  - DNS Trace Test Results
  - DNS Server Test Results
  - DNSSEC Test Results
  - Voice SIP Server Test Results
  - Voice RTP Server Test Results
  - Network BGP Test Results
- name: Instant Tests API
  tags:
  - Instant Tests
  - Agent to Agent Instant Tests
  - Agent to Server Instant Tests
  - DNS Server Instant Tests
  - DNS Trace Instant Tests
  - DNSSEC Instant Tests
  - HTTP Server Instant Tests
  - HTTP Page Load Instant Tests
  - Web Transaction Instant Tests
  - API Instant Tests
  - FTP Server Instant Tests
  - SIP Server Instant Tests
  - Voice Instant Tests
- name: ThousandEyes for OpenTelemetry API
  tags:
  - Streaming
- name: Test Snapshots API
  tags:
  - Test Snapshots
- name: Usage API
  tags:
  - Usage
  - Quotas
- name: Templates API
  tags:
  - Templates
- name: BGP Monitors API
  tags:
  - BGP monitors
- name: Internet Insights API
  tags:
  - Internet Insights Catalog Providers
  - Internet Insights Outages
- name: Tags API
  tags:
  - Tags
  - Tag Assignment
- name: Integrations API
  tags:
  - Credential Vault Operations
  - Operation Connectors
  - CyberArk Conjur Connectors
  - Webhook Operations
  - Generic Connectors
  - Panorama Connectors
- name: Event Detection API
  tags:
  - Events
- name: Endpoint Tests API
  tags:
  - Endpoint Scheduled Tests
  - Agent to Server Endpoint Scheduled Tests
  - HTTP Server Endpoint Scheduled Tests
  - Agent To Server Endpoint Dynamic Tests
  - Endpoint Real User Tests
- name: Endpoint Test Results API
  tags:
  - Network Endpoint Scheduled Test Results
  - HTTP Server Endpoint Scheduled Test Results
  - Network Dynamic Endpoint Test Results
  - Real User Endpoint Test Results
  - Local Network Endpoint Test Results
- name: Endpoint Agent Labels API
  tags:
  - Endpoint Agent Labels
- name: Endpoint Instant Scheduled Tests API
  tags:
  - Agent to Server Endpoint Instant Scheduled Tests
  - HTTP Server Endpoint Instant Scheduled Tests
  - Run Endpoint Instant Scheduled Tests
- name: Endpoint Agents API
  tags:
  - Endpoint Agents
  - Endpoint Agent Log Items
  - Endpoint Proxies
  - Endpoint Agents Transfer
- name: Emulation API
  tags:
  - Emulation
- name: Dashboards API
  tags:
  - Dashboards
  - Dashboard Snapshots
  - Dashboards Filters
- name: Credentials API
  tags:
  - Credentials
- name: Cloud Insights Integrations API
  tags:
  - Cloud Insights Integrations
  - Cloud Insights Integration Policy Settings
- name: Autonomous Systems API
  tags:
  - Autonomous Systems
  - Autonomous System Prefixes
- name: API Token Management API
  tags:
  - API Token
- name: Alerts API
  tags:
  - Alerts
  - Alert Rules
  - Alert Suppression Windows
- name: Agents API
  tags:
  - Cloud and Enterprise Agents
  - Local Problems
  - Enterprise Agent Cluster
  - Cloud and Enterprise Agent Notification Rules
  - Agent Proxies
  - Tests Assignment on Agents
- name: Administrative API
  tags:
  - Account Groups
  - Users
  - Roles
  - Permissions
  - User Events