Instana Infrastructure Catalog API

openapi: 3.2.0
info:
  contact:
    email: support@instana.com
    name: © Instana
    url: http://instana.com
  termsOfService: https://www.instana.com/terms-of-use/
  title: Instana REST API documentation Infrastructure Catalog API
  version: 1.307.1417
  x-ibm-ahub-try: true
  x-logo:
    altText: instana logo
    backgroundColor: '#FAFBFC'
    url: header-logo.svg
  description: Searching for answers and best pratices?
servers:
- description: Instana Backend
  url: https://{unit}-{tenant}.instana.io
  variables:
    tenant:
      default: tenant
      description: Customer tenant unit
    unit:
      default: unit
      description: Customer tenant name
- description: Instana Self-Hosted Backend
  url: https://{domain}
  variables:
    domain:
      default: example.com
      description: Customer Self-Hosted domain
tags:
- name: Infrastructure Catalog
  description: The endpoints of this group retrieve all available resources to query infrastructure metrics.
paths:
  /api/infrastructure-monitoring/catalog/metrics/{plugin}:
    get:
      operationId: getInfrastructureCatalogMetrics
      parameters:
      - in: path
        name: plugin
        required: true
        schema:
          type: string
      - in: query
        name: filter
        schema:
          type: string
      - in: query
        name: label
        schema:
          type: string
      - in: query
        name: limit
        schema:
          type: integer
          format: int32
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MetricInstance'
          description: OK
      security:
      - ApiKeyAuth:
        - Default
      summary: Get metric catalog
      tags:
      - Infrastructure Catalog
      x-ibm-ahub-byok: true
      description: 'This endpoint retrieves all available metric definitions of the requested plugin.


        ### Path Parameters:


        **plugin** The plugin id from available plugins


        ### Optional Parameters:


        **filter** You can restrict the returned metric definitions by passing a filter.


        * `custom` to retrieve custom metric definitions only.

        * `builtin` to retrieve built-in metric definitions only.'
  /api/infrastructure-monitoring/catalog/payloads/{pluginId}:
    get:
      operationId: getAvailablePayloadKeysByPluginId
      parameters:
      - description: plugin id
        example: db2Database
        in: path
        name: pluginId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetPayloadKeysResult'
          description: OK
          links:
            payload for snapshot:
              operationId: getPluginPayload
              parameters:
                payloadKey: $response.body#/[*]
      security:
      - ApiKeyAuth:
        - Default
      summary: Get payload keys for plugin
      tags:
      - Infrastructure Catalog
      x-ibm-ahub-byok: true
  /api/infrastructure-monitoring/catalog/plugins:
    get:
      operationId: getInfrastructureCatalogPlugins
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PluginResult'
          description: OK
      security:
      - ApiKeyAuth:
        - Default
      summary: Get plugin catalog
      tags:
      - Infrastructure Catalog
      x-ibm-ahub-byok: true
      description: This endpoint retrieves all available plugin ids for your monitored system.
  /api/infrastructure-monitoring/catalog/plugins-with-custom-metrics:
    get:
      operationId: getInfrastructureCatalogPluginsWithCustomMetrics
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PluginResult'
          description: OK
      security:
      - ApiKeyAuth:
        - Default
      summary: Get all plugins with custom metrics catalog
      tags:
      - Infrastructure Catalog
      x-ibm-ahub-byok: true
  /api/infrastructure-monitoring/catalog/search:
    get:
      operationId: getInfrastructureCatalogSearchFields
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SearchFieldResult'
          description: OK
      security:
      - ApiKeyAuth:
        - Default
      summary: get search field catalog
      tags:
      - Infrastructure Catalog
      x-ibm-ahub-byok: true
      description: 'This endpoint retrieves all available search keywords for dynamic focus queries.


        These search fields can be accessed via lucene queries. Each field belongs to a context, e.g. to entity, trace or event data.

        Some fields contain a set of possible fixed values, in this case a deviant value is invalid.


        ```

        ?query={keyword}:{value}

        ```'
  /api/infrastructure-monitoring/catalog/tags:
    get:
      description: This endpoint retrieves the tag catalog.
      operationId: getTagCatalogAll
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagCatalog'
          description: OK
      security:
      - ApiKeyAuth:
        - Default
      summary: Get available tags
      tags:
      - Infrastructure Catalog
      x-ibm-ahub-byok: true
  /api/infrastructure-monitoring/catalog/tags/{plugin}:
    get:
      description: This endpoint retrieves the tag catalog filtered by plugin.
      operationId: getTagCatalog
      parameters:
      - description: plugin
        example: host
        in: path
        name: plugin
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagCatalog'
          description: OK
      security:
      - ApiKeyAuth:
        - Default
      summary: Get available tags for a particular plugin
      tags:
      - Infrastructure Catalog
      x-ibm-ahub-byok: true
components:
  schemas:
    GetPayloadKeysResult:
      type: object
      properties:
        payloadKeys:
          type: array
          description: Keys that can be used to retrieve plugin payloads.
          items:
            type: string
            description: Keys that can be used to retrieve plugin payloads.
    Tag:
      type: object
      description: 'List of queryable tags available in a tagTree. Eg: `call.erroneous`.

        Consider these tags as attributes of a tagTree. Eg: `Call` tagTree has have `Erroneous`, `Call name`, `Latency` etc as attributes.

        '
      properties:
        aliases:
          type: array
          description: 'List of other names that can refer to this tag

            '
          items:
            type: string
            description: 'List of other names that can refer to this tag

              '
          uniqueItems: true
        availability:
          type: array
          description: 'List of product areas this tag is available in

            '
          items:
            type: string
            description: 'List of product areas this tag is available in

              '
            enum:
            - INFRASTRUCTURE_METRICS
            - APPLICATION
            - WEBSITE
            - MOBILE_APP
            - EUM
            - EUM_IMPACTED_BEACON
            - EVENT
            - SLI
            - SLO
            - SLO_PREVIEW
            - USAGE
            - LOG
            - SYNTHETICS
            - SYNTHETICS_DETAIL
            - APDEX
            - BIZOPS
            - BUSINESS_METRICS
            - SUBTRACE
            - UNKNOWN
          uniqueItems: true
        canApplyToDestination:
          type: boolean
          description: 'Whether the tag is available for destination or not.

            If source and destination is false, it means the tag is independent of source and destination. Eg: of such tag is `call.http.path`.

            '
        canApplyToSource:
          type: boolean
          description: 'Whether the tag is available for source or not.

            If source and destination is false, it means the tag is independent of source and destination. Eg: of such tag is `call.http.path`.

            '
        description:
          type: string
          description: The description of the tag if it is provided.
        idTag:
          type: boolean
          description: 'Whether the Tag is a unique ID or not.

            Eg: `idTag` for `endpoint.id` is true but for `call.rpc.method` it is false.

            '
        label:
          type: string
          description: 'The name of the tag which is seen in the UI. Eg: `Call name`'
          maxLength: 256
          minLength: 0
        name:
          type: string
          description: 'The name of the tag. Eg: `call.name`'
        type:
          type: string
          description: 'The data type of the tag. Eg: `call.name` accepts `STRING` value.'
          enum:
          - BOOLEAN
          - STRING
          - NUMBER
          - STRING_SET
          - STRING_LIST
          - KEY_VALUE_PAIR
          - FLOAT_LIST
          - KEY_NUMBER_PAIR
      required:
      - name
      - type
    MetricInstance:
      type: object
      properties:
        custom:
          type: boolean
        description:
          type: string
        formatter:
          type: string
          description: '|

            * NUMBER: Generic number

            * BYTES: Number of bytes

            * KILO_BYTES: Number of kilobytes

            * MEGA_BYTES: Number of megabytes

            * PERCENTAGE: Percentage in scale [0,1]

            * PERCENTAGE_100: Percentage in scale [0,100]

            * PERCENTAGE_NO_CAPPING: Percentage in scale [0,1] but value could exceed 1 for example when metric is aggregated

            * PERCENTAGE_100_NO_CAPPING: Percentage in scale [0,100] but value could exceed 100 for example when metric is aggregated

            * LATENCY: Time in milliseconds, with value of 0 should not be considered a a strict 0, but considered as < 1ms

            * NANOS: Time in nanoseconds

            * MILLIS: Time in milliseconds

            * MICROS: Time in microseconds

            * SECONDS: Time in seconds

            * RATE: Number of occurrences per second

            * BYTE_RATE: Number of bytes per second

            * UNDEFINED: Metric value unit is not known

            '
          enum:
          - NUMBER
          - BYTES
          - KILO_BYTES
          - MEGA_BYTES
          - PERCENTAGE
          - PERCENTAGE_100
          - PERCENTAGE_NO_CAPPING
          - PERCENTAGE_100_NO_CAPPING
          - LATENCY
          - NANOS
          - MILLIS
          - MICROS
          - SECONDS
          - RATE
          - BYTE_RATE
          - UNDEFINED
        label:
          type: string
        metricId:
          type: string
        pluginId:
          type: string
      required:
      - description
      - formatter
      - label
      - metricId
      - pluginId
    PluginResult:
      type: object
      properties:
        label:
          type: string
          description: Plugin name
        plugin:
          type: string
          description: Plugin ID
    TagTreeLevel:
      type: object
      description: 'The name of the tag dataset (tagTree) which can contain one or more tags as its attributes or children. Eg: `Call`.

        Consider this as the root of the tree where it has tags as attributes or children.

        '
      properties:
        children:
          type: array
          description: Children tags of tagTree
          items:
            $ref: '#/components/schemas/TagTreeNode'
        description:
          type: string
          description: The description provided, if any.
          maxLength: 512
          minLength: 0
        icon:
          type: string
          description: 'Each tag has an Icon which can be seen on the drop down list in Unbounded Analytics.

            If there is an icon, there will be a string associated with it.

            Eg: For for all `TAG` under `Call` tagTreeNode, the `icon` value is `lib_application_call`.

            '
          maxLength: 128
          minLength: 0
        label:
          type: string
          description: 'The name of the tagTreeNode. Eg: `Commonly Used`, `Application`.'
          maxLength: 128
          minLength: 0
        queryable:
          type: boolean
        scoreBoost:
          type: integer
          format: int32
          description: 'By default it is `null` if it is not set explictily by IBM Instana.

            The purpose of this parameter is to rank the tagTree. For eg: some set of tags are frequently used.

            Tags under `Commonly used` is frequently used, so it will come up on top of the drop down list of `Query Builder` in `Unbounded Analytics`.

            Higher the scoreBoost, higher the ranking.

            '
        type:
          type: string
          description: Type would be either `LEVEL` or `TAG` depending on whether the tag has any child tags or not respectively.
      required:
      - children
      - label
    TagTreeNode:
      type: object
      description: Children tags of tagTree
      discriminator:
        mapping:
          LEVEL: '#/components/schemas/TagTreeLevel'
          TAG: '#/components/schemas/TagTreeTag'
        propertyName: type
      properties:
        icon:
          type: string
        label:
          type: string
        type:
          type: string
          description: Type would be either `LEVEL` or `TAG` depending on whether the tag has any child tags or not respectively.
    SearchFieldResult:
      type: object
      properties:
        context:
          type: string
          description: Field context
          enum:
          - entities
          - events
          - applications
          - services
          - endpoints
          - appdata_shared
          - default_field
          example: Entity data, trace data, even data
        description:
          type: string
          description: Description of the keyword
        fixedValues:
          type: array
          description: Fixed value associated to the keyword
          items:
            type: string
            description: Fixed value associated to the keyword
        keyword:
          type: string
          description: Retrieved keyword
        termType:
          type: string
          description: Term type
          enum:
          - string
          - long
          - double
          - bool
          - key_value
          - id
    TagCatalog:
      type: object
      properties:
        tagTree:
          type: array
          description: 'The name of the tag dataset (tagTree) which can contain one or more tags as its attributes or children. Eg: `Call`.

            Consider this as the root of the tree where it has tags as attributes or children.

            '
          items:
            $ref: '#/components/schemas/TagTreeLevel'
        tags:
          type: array
          description: 'List of queryable tags available in a tagTree. Eg: `call.erroneous`.

            Consider these tags as attributes of a tagTree. Eg: `Call` tagTree has have `Erroneous`, `Call name`, `Latency` etc as attributes.

            '
          items:
            $ref: '#/components/schemas/Tag'
      required:
      - tagTree
      - tags
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: authorization
      type: apiKey
      description: "## Example\n\n```bash\ncurl --request GET \\\n  --url https://test-instana.instana.io/api/application-monitoring/catalog/metrics \\\n  --header 'authorization: apiToken xxxxxxxxxxxxxxxx'\n```\n"
x-tagGroups:
- name: Websites & Mobile Apps
  tags:
  - Website Metrics
  - Website Catalog
  - Website Analyze
  - Website Configuration
  - Mobile App Metrics
  - Mobile App Catalog
  - Mobile App Analyze
  - Mobile App Configuration
  - End User Monitoring
- name: Applications
  tags:
  - Application Metrics
  - Application Resources
  - Application Catalog
  - Application Analyze
  - Application Settings
  - Application Topology
  - Application Alert Configuration
  - Global Application Alert Configuration
- name: Infrastructure
  tags:
  - Infrastructure Analyze
  - Infrastructure Metrics
  - Infrastructure Resources
  - Infrastructure Catalog
  - Infrastructure Topology
- name: Logging
  tags:
  - Logging Analyze
- name: Synthetic Monitoring
  tags:
  - Synthetic Catalog
  - Synthetic Metrics
  - Synthetic Settings
  - Synthetic Test Playback Results
  - Synthetic Alert Configuration
- name: Logs
  tags:
  - Log Alert Configuration
- name: Events
  tags:
  - Events
  - Event Settings
- name: Automation
  tags:
  - Action Catalog
  - Action History
  - Policies
- name: Service Levels
  tags:
  - SLI Settings
  - SLI Report
  - Apdex Settings
  - Apdex Report
  - Service Levels Objective(SLO) Configurations
  - Service Levels Objective(SLO) Report
  - Service Levels Alert Configuration
  - SLO Correction Configurations
  - SLO Correction Windows
- name: AI Management
  tags:
  - AI Management
- name: Settings
  tags:
  - Custom Dashboards
  - User
  - Groups
  - Teams
  - Roles
  - Audit Log
  - API Token
  - Maintenance Configuration
  - Synthetic Calls
  - Session Settings
  - Automation Settings
  - Authentication
- name: Open Beta Features
  tags:
  - Infrastructure Analyze
- name: Closed Beta Features
  tags:
  - Infrastructure Alert Configuration
- name: Instana
  tags:
  - Releases
  - Host Agent
  - Health
  - Usage