openapi: 3.0.1
info:
  description: |
    ThousandEyes for OpenTelemetry provides machine-to-machine integration between ThousandEyes and its customers. It allows you to export ThousandEyes telemetry data in OTel format, which is widely used in the industry. With ThousandEyes for OTel, you can leverage frameworks widely used in the observability domain - such as Splunk, Grafana, and Honeycomb - to capture and analyze ThousandEyes data. Any client that supports OTel can use ThousandEyes for OpenTelemetry.

    ThousandEyes for OTel is made up of the following components:

    * Data streaming APIs that you can use to configure and enable your ThousandEyes tests with OTel-compatible streams,
    in particular to configure how ThousandEyes telemetry data is exported to client integrations.
    * A set of streaming pipelines called _collectors_ that actively fetch ThousandEyes network test data, enrich the data with some additional
    detail, filter, and push the data to the customer-configured endpoints, depending on what you configure via the public APIs.
    * Third-party OTel collectors that receive, transform, filter, and export different metrics to client applications such as AppD, or any other OTel-capable client
    configuration.

    For more information about ThousandEyes for OpenTelemetry, see the [documentation](https://docs.thousandeyes.com/product-documentation/api/opentelemetry).
  title: ThousandEyes for OpenTelemetry API
  version: 7.0.34
servers:
- description: ThousandEyes API production URL
  url: https://api.thousandeyes.com/v7
security:
- BearerAuth: []
tags:
- description: Configure data streaming
  name: Streaming
paths:
  /stream:
    get:
      description: Retrieves a list of configured data streams.
      operationId: getStreams
      parameters:
      - description: A unique identifier associated with your account group. You can
          retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note
          that you must be assigned to the target account group. Specifying this parameter
          without being assigned to the target account group will result in an error
          response.
        in: query
        name: aid
        required: false
        schema:
          example: "1234"
          type: string
      - description: Optional filter on type of Stream; should match one of Stream
          `type` enum
        explode: true
        in: query
        name: type
        required: false
        schema:
          $ref: '#/components/schemas/StreamType'
        style: form
      responses:
        "200":
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/StreamCollection'
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "429":
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Internal Server Error
      summary: List data streams
      tags:
      - Streaming
    post:
      description: Creates a new data stream.
      operationId: createStream
      parameters:
      - description: A unique identifier associated with your account group. You can
          retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note
          that you must be assigned to the target account group. Specifying this parameter
          without being assigned to the target account group will result in an error
          response.
        in: query
        name: aid
        required: false
        schema:
          example: "1234"
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Stream'
        description: Stream to configure
      responses:
        "201":
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/CreateStreamResponse'
          description: item created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: Unauthorized
        "409":
          description: An existing item already exists
        "412":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiErrorIntegrationLimits'
          description: Reached limit on number of streams (maximum 5 data streams
            per account group)
        "500":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Internal Server Error
      summary: Create data stream
      tags:
      - Streaming
  /stream/{id}:
    delete:
      description: Deletes a configured data stream using its ID.
      operationId: deleteStream
      parameters:
      - description: ID of stream to query
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: string
        style: simple
      - description: A unique identifier associated with your account group. You can
          retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note
          that you must be assigned to the target account group. Specifying this parameter
          without being assigned to the target account group will result in an error
          response.
        in: query
        name: aid
        required: false
        schema:
          example: "1234"
          type: string
      responses:
        "204":
          description: No content
        "401":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "429":
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Internal Server Error
      summary: Delete a data stream
      tags:
      - Streaming
    get:
      description: Retrieves a configured data stream using its ID.
      operationId: getStream
      parameters:
      - description: ID of stream to query
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: string
        style: simple
      - description: A unique identifier associated with your account group. You can
          retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note
          that you must be assigned to the target account group. Specifying this parameter
          without being assigned to the target account group will result in an error
          response.
        in: query
        name: aid
        required: false
        schema:
          example: "1234"
          type: string
      - description: Optional filter on type of Stream; should match one of Stream
          `type` enum
        explode: true
        in: query
        name: type
        required: false
        schema:
          $ref: '#/components/schemas/StreamType'
        style: form
      responses:
        "200":
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/GetStreamResponse'
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "429":
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Internal Server Error
      summary: Retrieve data stream
      tags:
      - Streaming
    put:
      description: "Updates a configured data stream using its ID. The fields are\
        \ overwritten, not appended."
      operationId: updateStream
      parameters:
      - description: ID of stream to query
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: string
        style: simple
      - description: A unique identifier associated with your account group. You can
          retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note
          that you must be assigned to the target account group. Specifying this parameter
          without being assigned to the target account group will result in an error
          response.
        in: query
        name: aid
        required: false
        schema:
          example: "1234"
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutStream'
      responses:
        "200":
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/GetStreamResponse'
          description: Stream updated
        "204":
          description: No content
        "400":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "429":
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Internal Server Error
      summary: Update data stream
      tags:
      - Streaming
components:
  parameters:
    AccountGroupId:
      description: A unique identifier associated with your account group. You can
        retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note that
        you must be assigned to the target account group. Specifying this parameter
        without being assigned to the target account group will result in an error
        response.
      in: query
      name: aid
      required: false
      schema:
        example: "1234"
        type: string
  responses:
    "401":
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
      description: Unauthorized
    "204":
      description: No content
  schemas:
    StreamType:
      description: |-
        The type of data stream to configure.
        When using `splunk-hec`:
          - `endpointType` must be `http`.
          - `customHeaders` must contain just one element with the key `token` and the value of the *Splunk HEC Token*.
      enum:
      - opentelemetry
      - splunk-hec
      example: opentelemetry
      type: string
    DataModelVersion:
      default: v2
      description: |-
        The version of the data model used in the data stream.
        When using `v1`:
          - The `signal` cannot be `trace`.
      enum:
      - v1
      - v2
      example: v2
      type: string
    AuditOperation:
      properties:
        createdBy:
          description: ID of the user who created the integration
          example: 3962
          format: int64
          type: integer
        createdDate:
          description: Creation date of the integration
          example: 1679677853573
          format: int64
          type: integer
      type: object
    AuditOperationWithUpdate:
      allOf:
      - $ref: '#/components/schemas/AuditOperation'
      - properties:
          updatedBy:
            description: ID of the user who last updated the integration
            example: 3962
            format: int64
            nullable: true
            type: integer
          updatedDate:
            description: Date of the last update to the integration
            example: 1679677853573
            format: int64
            nullable: true
            type: integer
        type: object
    PutStream:
      properties:
        customHeaders:
          additionalProperties:
            type: string
          description: |-
            Custom headers.
            **Note**: When using the `splunk-hec` `type`, the `customHeaders` must contain just one element with the key `token` and the value of the *Splunk HEC Token*.
          example:
            Authorization: '*****'
            Content-Type: '*****'
          type: object
        streamEndpointUrl:
          description: |-
            The URL ThousandEyes sends data stream to.
            For a URL to be valid, it needs to: - Be syntactically correct. - Be reachable. - Use the HTTPS protocol. - When using the `grpc` endpointType, streamEndpointUrl cannot contain paths:
                - Valid . `grpc` - `https://example.com`
                - Invalid . `grpc` - `https://example.com/collector`.
                - Valid . `http` - `https://example.com/collector`.

            - When using the `http` endpointType, the operation must match the exact final full URL (including the path if there is one) to which the data will be sent. Examples below:
                - `https://api.honeycomb.io:443/v1/metrics`
                - `https://ingest.eu0.signalfx.com/v2/datapoint/otlp`
          example: https://api.thousandeyes.otel-collector
          type: string
        tagMatch:
          description: A collection of tags that determine what tests are included
            in the data stream. These tag values are also included as attributes in
            the data stream metrics.
          example:
          - key: keyA
            value: valueA
          - key: keyB
            value: valueB
          items:
            $ref: '#/components/schemas/TagMatch'
          type: array
        testMatch:
          description: A collection of tests to be included in the data stream.
          example:
          - id: "1234"
            domain: cea
          - id: "5678"
            domain: endpoint
          items:
            $ref: '#/components/schemas/TestMatch'
          type: array
        enabled:
          description: Flag to enable or disable the stream integration.
          example: true
          type: boolean
        filters:
          $ref: '#/components/schemas/Filters'
        exporterConfig:
          $ref: '#/components/schemas/ExporterConfig'
      type: object
    TagMatch:
      properties:
        key:
          description: The name of the tag key to match
          example: keyA
          type: string
        value:
          description: The value of the tag to match
          example: valueA
          type: string
      type: object
    TagMatchObjectType:
      deprecated: true
      description: The object type of tag
      enum:
      - test
      example: test
      type: string
    Filters:
      description: Provides the ability to filter data points based on the specified
        test types.
      properties:
        testTypes:
          $ref: '#/components/schemas/FiltersTestTypes'
      type: object
    FiltersTestTypes:
      description: Test types that can be used for filtering data points.
      properties:
        values:
          description: A list of test types to filter data points.
          example:
          - agent-to-server
          - bgp
          - http-server
          items:
            $ref: '#/components/schemas/TestType'
          type: array
      type: object
    FiltersTestTypesValues:
      description: A list of test types to filter data points.
      example:
      - agent-to-server
      - bgp
      - http-server
      items:
        $ref: '#/components/schemas/TestType'
      type: array
    TestMatch:
      properties:
        id:
          description: The ID of the test to match.
          example: "1234"
          type: string
        domain:
          $ref: '#/components/schemas/TestMatchDomain'
      type: object
    TestMatchDomain:
      description: |-
        The domain of the test to match.
         `cea` - Cloud and Enterprise Agent
         `endpoint` - Endpoint Agent
      enum:
      - cea
      - endpoint
      example: cea
      type: string
    ExporterConfig:
      description: Capability to set exporter configuration.
      properties:
        splunkHec:
          $ref: '#/components/schemas/ExporterConfigSplunkHec'
      type: object
    ExporterConfigSplunkHec:
      description: Splunk HEC configuration. This can only be configured when the
        `type` is `splunk-hec`.
      properties:
        token:
          description: The Splunk HEC `token`. This is a required field.
          example: d0a91307-be2f-4218-a9f8-71c02d98846b
          type: string
        source:
          default: ThousandEyesOTel
          description: The Splunk HEC `source`. This field is optional.
          example: ThousandEyesOTel
          type: string
        sourceType:
          default: ThousandEyesOTel
          description: The Splunk HEC `sourceType`. This field is optional.
          example: ThousandEyesOTel
          type: string
        index:
          description: The name of the Splunk HEC index where the event data will
            be stored.  This field is optional.
          example: thousandeyes_otel_events_index
          type: string
      type: object
    Stream:
      allOf:
      - properties:
          type:
            $ref: '#/components/schemas/StreamType'
          signal:
            $ref: '#/components/schemas/Signal'
          endpointType:
            $ref: '#/components/schemas/EndpointType'
          streamEndpointUrl:
            $ref: '#/components/schemas/StreamEndpointUrl'
          dataModelVersion:
            $ref: '#/components/schemas/DataModelVersion'
        type: object
      - $ref: '#/components/schemas/PutStream'
    Signal:
      default: metric
      description: |-
        The OpenTelemetry signal of the stream integration.
        When using `trace`:
          - `dataModelVersion` must be `v2`.
      enum:
      - metric
      - trace
      example: metric
      type: string
    EndpointType:
      default: grpc
      description: |-
        The type of connection used to send data to the endpoint.
        **Note**: When using the `splunk-hec` 'type', the `EndpointType` must be `http`.
      enum:
      - grpc
      - http
      example: grpc
      type: string
    StreamResponse:
      properties:
        id:
          description: The data stream ID
          example: 342ieu09
          readOnly: true
          type: string
        enabled:
          description: Flag to indicate if the stream integration is currently enabled.
          example: true
          readOnly: true
          type: boolean
        _links:
          $ref: '#/components/schemas/StreamLinks'
      type: object
    StreamEndpointUrl:
      description: |-
        The URL ThousandEyes sends data stream to.
        For a URL to be valid, it needs to: - Be syntactically correct. - Be reachable. - Use the HTTPS protocol. - When using the `grpc` endpointType, streamEndpointUrl cannot contain paths:
            - Valid . `grpc` - `https://example.com`
            - Invalid . `grpc` - `https://example.com/collector`.
            - Valid . `http` - `https://example.com/collector`.

        - When using the `http` endpointType, the operation must match the exact final full URL (including the path if there is one) to which the data will be sent. Examples below:
            - `https://api.honeycomb.io:443/v1/metrics`
            - `https://ingest.eu0.signalfx.com/v2/datapoint/otlp`
      example: https://api.thousandeyes.otel-collector
      type: string
    GetStreamResponse:
      allOf:
      - $ref: '#/components/schemas/StreamResponse'
      - $ref: '#/components/schemas/Stream'
      - properties:
          auditOperation:
            $ref: '#/components/schemas/AuditOperationWithUpdate'
        type: object
    CreateStreamResponse:
      allOf:
      - $ref: '#/components/schemas/StreamResponse'
      - $ref: '#/components/schemas/Stream'
      - properties:
          auditOperation:
            $ref: '#/components/schemas/AuditOperation'
        type: object
    StreamCollection:
      items:
        $ref: '#/components/schemas/GetStreamResponse'
      type: array
    BadRequestError:
      properties:
        timestamp:
          example: 1679677853573
          format: int64
          type: integer
        httpStatus:
          example: BAD_REQUEST
          type: string
        errors:
          items:
            example: "JSON parse error: invalid type"
            type: string
          type: array
        path:
          example: https://api.thousandeyes.com/v7/stream
          format: url
          type: string
      type: object
    ApiErrorIntegrationLimits:
      properties:
        timestamp:
          example: 1679677853573
          format: int64
          type: integer
        httpStatus:
          example: PRECONDITION_FAILED
          type: string
        errors:
          items:
            example: User cannot create more than 5 integrations
            type: string
          type: array
        path:
          example: https://api.thousandeyes.com/v7/stream
          format: url
          type: string
      type: object
    StreamSelfLink:
      properties:
        href:
          example: https://api.thousandeyes.com/v7/streams/575766da-9664-4e85-94fe-facbe1154799
          format: url
          type: string
      type: object
    StreamLinks:
      properties:
        self:
          $ref: '#/components/schemas/StreamSelfLink'
      readOnly: true
      type: object
    UnauthorizedError:
      properties:
        error:
          example: invalid_token
          type: string
        error_description:
          example: Invalid access token
          type: string
      type: object
    ApiError:
      properties:
        timestamp:
          example: 1679677853573
          format: int64
          type: integer
        status:
          example: 500
          type: integer
        errors:
          example: Internal Server Error
          type: string
        path:
          example: https://api.thousandeyes.com/v7/request/path
          format: url
          type: string
      type: object
    TestType:
      description: "This is a read only value, as test type is implicit in the test\
        \ creation url."
      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
      example: agent-to-server
      readOnly: true
      type: string
  securitySchemes:
    BearerAuth:
      description: Bearer authentication token
      scheme: bearer
      type: http
