Instana Action 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 Action 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: Action Catalog
paths:
  /api/automation/actions:
    get:
      description: Get all automation actions. When using personal access tokens, the user must have at least `Viewer` access for Automation and the actions returned are also filtered based on the access set in `Limited access` permission settings.
      operationId: getActions
      responses:
        '200':
          content:
            application/json:
              example:
              - id: d473c1b0-0740-4d08-95fe-31e5d0a9faff
                name: Hello World
                description: Simple script action for testing
                type: SCRIPT
                fields:
                - name: subtype
                  description: script subtype
                  encoding: base64
                  value: YmFzaA==
                  secured: false
                - name: script_ssh
                  description: script content
                  encoding: base64
                  value: ZWNobyBoZWxsbyB3b3JsZA==
                  secured: false
                - name: timeout
                  description: timeout of the action execution in seconds
                  encoding: ascii
                  value: ''
                  secured: false
                inputParameters: []
                tags:
                - Test
                createdAt: 1694442511.129923
                modifiedAt: 1703191040.321448
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Action'
          description: Automation actions are returned.
        '403':
          description: Automation feature is not enabled or Insufficient permissions.
        '500':
          description: Failed to retrieve the automation actions.
      security:
      - ApiKeyAuth:
        - Default
      summary: Get all automation actions
      tags:
      - Action Catalog
      x-ibm-ahub-byok: true
  /api/automation/actions/{id}:
    get:
      description: Get an automation action by ID specified in the request path. When using personal access tokens, the user must have at least `Viewer` access for Automation and the actions returned are also filtered based on the access set in `Limited access` permission settings.
      operationId: getActionByID
      parameters:
      - description: Automation action ID
        example: d473c1b0-0740-4d08-95fe-31e5d0a9faff
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                id: d473c1b0-0740-4d08-95fe-31e5d0a9faff
                name: Hello World
                description: Simple script action for testing
                type: SCRIPT
                fields:
                - name: subtype
                  description: script subtype
                  encoding: base64
                  value: YmFzaA==
                  secured: false
                - name: script_ssh
                  description: script content
                  encoding: base64
                  value: ZWNobyBoZWxsbyB3b3JsZA==
                  secured: false
                - name: timeout
                  description: timeout of the action execution in seconds
                  encoding: ascii
                  value: ''
                  secured: false
                inputParameters: []
                tags:
                - Test
                createdAt: 1694442511.129923
                modifiedAt: 1703191040.321448
              schema:
                $ref: '#/components/schemas/Action'
          description: Automation action is returned.
        '403':
          description: Automation feature is not enabled or Insufficient permissions.
        '404':
          description: Automation action not found.
      security:
      - ApiKeyAuth:
        - Default
      summary: Get an automation action by ID
      tags:
      - Action Catalog
      x-ibm-ahub-byok: true
  /api/automation/ai/action/match:
    get:
      description: Get automation actions that match based on application ID or snapshot ID within a specified time window.
      operationId: getActionMatchesByIdAndTimeWindow
      parameters:
      - in: query
        name: applicationId
        schema:
          type: string
      - in: query
        name: snapshotId
        schema:
          type: string
      - in: query
        name: to
        schema:
          type: integer
          format: int64
      - in: query
        name: windowSize
        schema:
          type: integer
          format: int64
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ActionMatch'
          description: The automation actions that match are returned.
        '400':
          description: Either applicationId or snapshotId must be provided, but not both.
        '403':
          description: Automation feature is not enabled or Insufficient permissions.
        '500':
          description: Failed to retrieve the matching automation actions.
      security:
      - ApiKeyAuth:
        - Default
      summary: Get action matches by application ID or snapshot ID
      tags:
      - Action Catalog
      x-ibm-ahub-byok: true
    post:
      description: Get automation actions that match the incident or issue data in the request body.
      operationId: getActionMatches
      parameters:
      - in: query
        name: targetSnapshotId
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              name: CPU spends significant time waiting for input/output
              description: Checks whether the system spends significant time waiting for input/output.
            schema:
              $ref: '#/components/schemas/ActionSearchSpace'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
              - score: 0.12087341955930318
                action:
                  id: d473c1b0-0740-4d08-95fe-31e5d0a9faff
                  name: Hello World
                  description: Simple script action for testing
                  type: SCRIPT
                  fields:
                  - name: subtype
                    description: script subtype
                    encoding: base64
                    value: YmFzaA==
                    secured: false
                  - name: script_ssh
                    description: script content
                    encoding: base64
                    value: ZWNobyBoZWxsbyB3b3JsZA==
                    secured: false
                  - name: timeout
                    description: timeout of the action execution in seconds
                    encoding: ascii
                    value: ''
                    secured: false
                  inputParameters: []
                  tags:
                  - sample
                  createdAt: 1694442511.129923
                  modifiedAt: 1703191040.321448
                color: low
                confidence: low
                aiEngine: NLP
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ActionMatch'
          description: The automation actions that match the incident are returned.
        '403':
          description: Automation feature is not enabled or Insufficient permissions.
        '500':
          description: Failed to retrieve the matching automation actions.
      security:
      - ApiKeyAuth:
        - Default
      summary: Get automation actions that match the incidents or issues
      tags:
      - Action Catalog
      x-ibm-ahub-byok: true
  /api/automation/parameters/dynamic:
    put:
      operationId: resolve
      requestBody:
        content:
          application/json:
            example:
              eventId: 7UPTIakhR3uVaMnSQuG3TA
              timestamp: 1710168530000
              parameters:
              - name: Application name
                tagName: application.name
            schema:
              $ref: '#/components/schemas/GetDynamicParameterValues'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                eventId: 7UPTIakhR3uVaMnSQuG3TA
                timestamp: 1710168530000
                parameters:
                - name: Application name
                  tagName: application.name
                  resolvedValue: '["Demo Application"]'
              schema:
                $ref: '#/components/schemas/GetDynamicParameterValues'
          description: OK
        '500':
          description: Internal server error
      security:
      - ApiKeyAuth:
        - canRunAutomationActions
      summary: Resolve dynamic parameter values
      tags:
      - Action Catalog
      x-ibm-ahub-byok: true
  /api/automation/parameters/dynamic/catalog:
    get:
      operationId: getDynamicParametersTagCatalog
      responses:
        '200':
          content:
            application/json:
              example:
                tagTree:
                - label: Application
                  description: null
                  icon: null
                  children:
                  - label: Name
                    icon: lib_application
                    tagName: application.name
                    queryable: true
                    type: TAG
                  type: LEVEL
                  queryable: false
                tags:
                - name: application.name
                  label: Name
                  type: STRING_SET
                  description: null
                  canApplyToSource: true
                  canApplyToDestination: true
                  idTag: false
              schema:
                $ref: '#/components/schemas/TagCatalog'
          description: OK
        '500':
          description: Internal server error
      security:
      - ApiKeyAuth:
        - Default
      summary: Get tag catalog for dynamic parameters
      tags:
      - Action Catalog
      x-ibm-ahub-byok: true
components:
  schemas:
    PolicyRunnable:
      type: object
      description: Runnable associated with the policy. It can be a `workflow` or `action`. Currently only supports `action`.
      properties:
        id:
          type: string
          description: Action identifier.
        runConfiguration:
          $ref: '#/components/schemas/RunConfiguration'
        type:
          type: string
          description: Type of runnable. Supported value is `action`.
          enum:
          - action
          - workflow
      required:
      - id
      - runConfiguration
      - type
    Action:
      type: object
      description: Automation action definition. When this is used in policy creation request, only `id` should be specified.
      properties:
        createdAt:
          type: string
          format: date-time
          description: Action created time.
        description:
          type: string
          description: Action description.
          maxLength: 512
          minLength: 0
        fields:
          type: array
          description: List of fields that describe an action.
          items:
            $ref: '#/components/schemas/Field'
        id:
          type: string
          description: Action identifier.
          maxLength: 128
          minLength: 1
        inputParameters:
          type: array
          description: List of inputs to the action.
          items:
            $ref: '#/components/schemas/Parameter'
        metadata:
          $ref: '#/components/schemas/MetaData'
        modifiedAt:
          type: string
          format: date-time
          description: Action modified time.
        name:
          type: string
          description: Action name.
          maxLength: 128
          minLength: 1
        tags:
          type: array
          description: List of tags added to the action.
          items:
            type: string
            description: List of tags added to the action.
        type:
          type: string
          description: 'Action type can be one of the following values:  SCRIPT, HTTP, ANSIBLE, EXTERNAL, GITHUB, GITLAB, JIRA, MANUAL, DOC_LINK'
          enum:
          - SCRIPT
          - HTTP
          - ANSIBLE
          - EXTERNAL
          - GITHUB
          - GITLAB
          - JIRA
          - MANUAL
          - DOC_LINK
          maxLength: 128
          minLength: 0
      required:
      - createdAt
      - id
      - modifiedAt
      - name
      - type
    RunConfiguration:
      type: object
      description: Action run configuration.
      properties:
        actions:
          type: array
          description: List of action configurations.
          items:
            $ref: '#/components/schemas/ActionConfiguration'
      required:
      - actions
    ActionMatch:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/Action'
        aiEngine:
          type: string
          enum:
          - POLICY
          - EVENT_SIMILARITY
          - NLP
          - SUCCESS_RATE
          - TURBONOMIC
          - WATSONX
        confidence:
          type: string
        policy:
          $ref: '#/components/schemas/Policy'
        score:
          type: number
          format: double
      required:
      - aiEngine
      - confidence
      - score
    GetDynamicParameterValues:
      type: object
      properties:
        eventId:
          type: string
          description: Event identifier
        parameters:
          type: array
          description: List of dynamic parameters
          items:
            $ref: '#/components/schemas/DynamicParameter'
        timestamp:
          type: integer
          format: int64
          description: The start of the timestamp expressed in Unix epoch time in milliseconds.
      required:
      - eventId
      - parameters
      - timestamp
    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
    Field:
      type: object
      description: List of fields that describe an action.
      properties:
        description:
          type: string
        encoding:
          type: string
        name:
          type: string
        secured:
          type: boolean
        value:
          type: string
      required:
      - encoding
      - name
      - value
    TypeConfiguration:
      type: object
      description: List of configurations that contains the list of actions to run and the mode (automatic or manual) in which the policy is run.
      properties:
        condition:
          $ref: '#/components/schemas/Condition'
        name:
          type: string
          description: The policy type determines how a policy is run. Value must be one of the enum values. Value `manual` means the policy is run manually when an event is raised. Value `automatic` means policy is run automatically when an event is raised.
          enum:
          - automatic
          - manual
        runnable:
          $ref: '#/components/schemas/PolicyRunnable'
      required:
      - name
      - runnable
    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.
    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
    MetaData:
      type: object
      description: Action metadata.
      properties:
        ai:
          type: array
          description: List of metadata for AI originated actions.
          items:
            type: object
            additionalProperties:
              type: object
              description: List of metadata for AI originated actions.
            description: List of metadata for AI originated actions.
        aiOriginated:
          type: boolean
          description: AI originated action flag. Value is `true` if action is AI generated `false` otherwise.
        builtIn:
          type: boolean
          description: Built-in out of the box action flag. Value is `true` if built-in action `false` otherwise.
        readOnly:
          type: boolean
          description: Read only action flag. Value is `true` if read only `false` otherwise.
        sensorImported:
          type: boolean
          description: Sensor imported action flag. Value is `true` if action is imported from sensor `false` otherwise.
    DynamicParameter:
      type: object
      description: List of dynamic parameters
      properties:
        key:
          type: string
          description: Parameter key
        name:
          type: string
          description: Parameter name
        resolvedValue:
          type: string
          description: Parameter value after resolution
        tagName:
          type: string
          description: 'The name of the tag. Eg: `call.name`'
    Parameter:
      type: object
      description: List of inputs to the action.
      properties:
        description:
          type: string
          description: Parameter description.
        hidden:
          type: boolean
          description: Is parameter hidden or not.
        label:
          type: string
          description: Parameter label.
        name:
          type: string
          description: Parameter name.
        required:
          type: boolean
          description: Is parameter required or not.
        secured:
          type: boolean
          description: Is parameter secured or not.
        type:
          type: string
          description: Parameter type. Valid values are `static`, `dynamic`, or `vault`. Default value is `static`
        value:
          type: string
          description: Parameter value.
      required:
      - label
      - name
      - type
    Condition:
      type: object
      description: This applies to only `automatic` policy type. A Dynamic Focus Query that selects a list of entities on which the policy is run.
      properties:
        query:
          type: string
          description: Dynamic Focus Query string that selects a list of entities on which the policy is run.
    ActionSearchSpace:
      type: object
      properties:
        description:
          type: string
          description: The description of an incident or issue.
        entityType:
          type: string
          description: The entity type associated with the incident or issue.
        eventId:
          type: string
          description: The event identifier associated with the incident or issue.
        name:
          type: string
          description: The name of an incident or issue.
      required:
      - name
    Trigger:
      type: object
      description: The trigger is the Instana event or Smart Alert that defines the initial conditions that must be met for the policy to apply on the actions in `typeConfiguration`.
      properties:
        description:
          type: string
          description: A description for the trigger.
        id:
          type: string
          description: Trigger (Instana event or Smart Alert) identifier.
        name:
          type: string
          description: A name of the trigger (name of Instana event or Smart Alert).
        scheduling:
          $ref: '#/components/schemas/PolicyScheduling'
        type:
          type: string
          description: Instana event type, Smart Alert type, or 'schedule'. The type must be one of the enum values.
          enum:
          - customEvent
          - builtinEvent
          - applicationSmartAlert
          - globalApplicationSmartAlert
          - websiteSmartAlert
          - infraSmartAlert
          - mobileAppSmartAlert
          - syntheticsSmartAlert
          - logSmartAlert
          - sloSmartAlert
          - schedule
      required:
      - type
    ParameterValue:
      type: object
      description: List of action input parameters.
      properties:
        name:
          type: string
          description: Parameter name.
        value:
          type: string
          description: Parameter value.
      required:
      - name
      - value
    Policy:
      type: object
      properties:
        description:
          type: string
          description: Policy description.
          maxLength: 512
          minLength: 0
        id:
          type: string
          description: Policy identifier.
          maxLength: 128
          minLength: 1
          readOnly: true
        name:
          type: string
          description: Policy name.
          maxLength: 128
          minLength: 1
        tags:
          type: array
          description: A list of policy tags.
          items:
            type: string
            description: A list of policy tags.
        trigger:
          $ref: '#/components/schemas/Trigger'
        typeConfigurations:
          type: array
          description: List of configurations that contains the list of actions to run and the mode (automatic or manual) in which the policy is run.
          items:
            $ref: '#/components/schemas/TypeConfiguration'
      required:
      - id
      - name
      - trigger
      - typeConfigurations
    ActionConfiguration:
      type: object
      description: List of action configurations.
      properties:
        action:
          $ref: '#/components/schemas/Action'
        agentId:
          type: string
          description: Identifier of the agent host on which to run the action.
        inputParameterValues:
          type: array
          description: List of action input parameters.
          items:
            $ref: '#/components/schemas/ParameterValue'
      required:
      - action
    PolicyScheduling:
      type: object
      description: Scheduling information for a scheduled policy.
      properties:
        recurrentRule:
          type: string
          description: 'Recurrent Rule defines how the policy recurs, using iCalendar RRULE format (e.g., `FREQ=DAILY;INTERVAL=1`).It supports fields like FREQ, INTERVAL, BYDAY. Refer to RFC 5545: https://datatracker.ietf.org/doc/html/rfc5545#section-3.3.10'
        startTime:
          type: string
          format: date-time
          description: The time to run the policy action in milliseconds since epoch (UTC) (e.g., `1706713140000`).
      required:
      - startTime
  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