ThousandEyes Internet Insights Catalog Providers API

openapi: 3.2.0
info:
  title: Internet Insights Catalog Providers API
  version: 7.0.100
  description: '**Note:** All Internet Insights APIs are not available for ThousandEyes for Government instance.


    We are happy to announce the release of the Internet Insights API set. This limited release includes endpoints that:


    * Make our catalog provider and Internet outage data accessible to API users.

    * Provide access to advanced filtering, which is part of our next-generation API efforts to allow API users to fine-tune queries across all of our APIs in a consistent manner.


    Internet Insights provide visibility into core Internet infrastructure, including ISPs, DNS providers, IaaS, CDNs , and SaaS providers.

    It tracks the macro-level impact of Internet events on individual users and enterprise networks connecting at the edge of the Internet. These events include Outages, Routing hijacks and leaks, DDoS attacks, And political interference, among others.


    Future releases of the Internet Insights API set will further unlock access to core Internet Insights functionality, unlocking potential integrations to enrich customer process flows.


    For more information about Internet Insights, see the [Internet Insights](https://docs.thousandeyes.com/product-documentation/internet-insights).

    '
  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
security:
- BearerAuth: []
tags:
- name: Internet Insights Catalog Providers
paths:
  /internet-insights/catalog/providers/filter:
    post:
      tags:
      - Internet Insights Catalog Providers
      summary: List catalog providers
      description: 'Returns a list of catalog providers using the specified filters. Returns high-level information about each catalog provider. For more details about a specific provider, call the Get a catalog provider endpoint.


        <b>Note:</b> Support for pagination will be added in the future.

        '
      operationId: filterCatalogProviders
      parameters:
      - $ref: '#/components/parameters/AccountGroupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCatalogProviderFilter'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ApiCatalogProviderResponse'
        '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'
        '502':
          $ref: '#/components/responses/502'
        default:
          $ref: '#/components/responses/GeneralError'
  /internet-insights/catalog/providers/{providerId}:
    get:
      tags:
      - Internet Insights Catalog Providers
      summary: Retrieve a catalog provider
      description: 'Returns the details of a catalog provider.

        '
      operationId: getCatalogProvider
      parameters:
      - name: providerId
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 85602a0a-54a7-4e97-946e-67492ef1fa26
      - $ref: '#/components/parameters/AccountGroupId'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ApiCatalogProviderDetails'
        '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'
        '502':
          $ref: '#/components/responses/502'
        default:
          $ref: '#/components/responses/GeneralError'
components:
  schemas:
    ValidationError:
      type: object
      allOf:
      - $ref: '#/components/schemas/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/ValidationErrorItem'
    ProviderName:
      type: string
      description: The name of the catalog provider.
      example: Amazon Web Services
    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.
    ProviderLocation:
      type: object
      properties:
        location:
          type: string
          description: The location covered by the Provider.
          example: San Jose, US
        interfacesCount:
          type: integer
          description: The number of interfaces covered by the Provider at this location.
          example: 5
    ApiCatalogProviderResponse:
      type: object
      properties:
        providers:
          type: array
          description: List of catalog providers.
          items:
            $ref: '#/components/schemas/ApiCatalogProvider'
        _links:
          $ref: '#/components/schemas/SelfLinks'
    CatalogId:
      type: string
      format: uuid
      description: The catalog provider ID.
      example: 85602a0a-54a7-4e97-946e-67492ef1fa26
    ApiCatalogProviderDetails:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/CatalogId'
        providerName:
          $ref: '#/components/schemas/ProviderName'
        providerType:
          $ref: '#/components/schemas/ProviderType'
        region:
          $ref: '#/components/schemas/Region'
        dataType:
          $ref: '#/components/schemas/DataType'
        asns:
          uniqueItems: true
          type: array
          description: List of ASN's covered by the Provider.
          items:
            $ref: '#/components/schemas/ApiAsn'
        locations:
          uniqueItems: true
          type: array
          description: List of locations covered by the Provider.
          items:
            $ref: '#/components/schemas/ProviderLocation'
        _links:
          $ref: '#/components/schemas/SelfLinks'
    DataType:
      type: string
      description: The type of data produced by the provider.
      example: Application
    UnauthorizedError:
      type: object
      properties:
        error:
          type: string
          example: invalid_token
        error_description:
          type: string
          example: Invalid access token
    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
    ApiAsn:
      type: object
      properties:
        id:
          type: integer
          description: ASN (Autonomous Systems Number)
          example: 1
        name:
          type: string
          description: ASN (Autonomous Systems Number) name
          example: LVLT-1 - Level 3 Communications, Inc.
    Region:
      type: string
      description: The catalog provider region.
      example: North America
    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.
    ApiCatalogProviderFilter:
      description: 'Advanced filter query used to filter the response. The provider name, location, asn can be partial names. Can filter on: - Provider name - Provider type - Region - Location - ASN - included'
      type: object
      properties:
        providerName:
          type: string
          description: The name of the catalog provider.
          example: Amazon Web Services
        providerType:
          type: string
          description: The type of catalog provider.
          example: IAAS
        region:
          type: string
          description: The catalog provider region.
          example: North America
        location:
          type: string
          description: Location of the catalog provider.
          example: San Jose, US
        asn:
          type: string
          description: Name of the ASN (Autonomous Systems Number) covered by providers.
          example: Amazon.com, Inc.
        included:
          type: boolean
          description: Indicates whether the catalog provider is included in the licensed packages. true returns providers covered by licensed packages, false returns providers not covered by licensed packages.
          example: true
      example:
        providerName: Amazon Web Services
        providerType: IAAS
        region: North America
        location: San Jose, US
        asn: Amazon.com, Inc.
        included: true
    SelfLinks:
      type: object
      description: A links object containing the self link.
      readOnly: true
      properties:
        self:
          $ref: '#/components/schemas/Link'
    ProviderType:
      type: string
      description: The type of catalog provider.
      example: IAAS
    ApiCatalogProvider:
      type: object
      description: Catalog provider
      properties:
        id:
          $ref: '#/components/schemas/CatalogId'
        providerName:
          $ref: '#/components/schemas/ProviderName'
        providerType:
          $ref: '#/components/schemas/ProviderType'
        region:
          $ref: '#/components/schemas/Region'
        dataType:
          $ref: '#/components/schemas/DataType'
        asnsCount:
          type: integer
          description: The number of ASN's covered by the provider.
          example: 10
        countriesCount:
          type: integer
          description: The number of countries covered by the provider.
          example: 2
        locationsCount:
          type: integer
          description: The number of locations covered by the provider.
          example: 50
        interfacesCount:
          type: integer
          description: The number of interfaces covered by the provider.
          example: 15
        included:
          type: boolean
          description: Indicates whether the catalog provider is included in the licensed packages.
          example: true
        _links:
          $ref: '#/components/schemas/SelfLinks'
  responses:
    '502':
      description: Bad Gateway
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    GeneralError:
      description: An error occurred
    '429':
      description: Exhausted rate limit for the organization
      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
    '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
    '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
    '403':
      description: Insufficient permissions to query endpoint
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
  parameters:
    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'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token