openapi: 3.2.0
info:
  title: Sensei Machine Learning Insights API
  description: "Sensei Machine Learning API provides a mechanism for data scientists to organize and manage ML services from algorithm onboarding through experimentation and to service deployment.\n\nRelated documentation:\n  * [Data Science Workspace documentation](http://www.adobe.com/go/data-science-overview-en)\n  \nVisualize API calls with Postman (a free, third-party software):\n  * [Sensei Machine Learning API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Sensei%20Machine%20Learning%20API.postman_collection.json)\n  * [Video guide for creating the Postman environment](https://video.tv.adobe.com/v/28832)\n  * [Steps for importing environments and collections in Postman](https://learning.getpostman.com/docs/postman/collection_runs/using_environments_in_collection_runs/)\n\n\n**API paths**: \n  * PLATFORM Gateway URL: https://<span>platform.adobe.io/ \n  * Base path for this API: /data/sensei\n  * Example of a complete path: https://<span>platform.adobe.io/data/sensei/engines\n\n**Required headers**:\n  * All calls require the headers `Authorization`, `x-gw-ims-org-id`, and `x-api-key`. For more information on how to obtain these values, see the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).\n  * All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require the header `x-sandbox-name` whose value is the all-lowercase name of the sandbox the operation will take place in (for example, \"prod\"). See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.\n  * All requests with a payload in the request body (such as POST, PUT, and PATCH calls) must include the header `Content-Type` with a value of `application/json`. \n  \n**API error handling**: \n  - Refer to the Experience Platform API troubleshooting guide for [FAQs](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#faq), [API status codes](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#api-status-codes), and [request header errors](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#request-header-errors)."
  version: '1.0'
servers:
- url: //{environment}.adobe.io/data/sensei
  variables:
    environment:
      default: platform
      enum:
      - platform
      - platform-stage
tags:
- name: Insights
  description: Insights contain metrics which are used to empower a data scientist to evaluate and choose optimal ML Models by displaying relevant evaluation metrics.
paths:
  /insights:
    get:
      tags:
      - Insights
      summary: List all insights
      description: Lists all insights for all experiment runs
      operationId: retrieveInsights
      parameters:
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer " (for example, `Bearer {ACCESS_TOKEN}`). For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      - name: start
        in: query
        description: Start value for pagination. Indicates the starting index for the items to return.
        schema:
          type: string
      - name: limit
        in: query
        description: Limit value for pagination. Indicates the requested number of items to return. The service may return a different number of items than requested.
        schema:
          maximum: 100
          minimum: 0
          type: integer
          format: int32
          default: 25
      - name: orderby
        in: query
        description: Sort order for pagination. Indicates the fields and direction to use for sorting in priority order.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
          default: '["-updated"]'
      - name: property
        in: query
        description: Property matching expression for filtering paginated results. Indicates the comparison expression that items must match in order to be returned.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          x-summary: Success
          description: List of insights
          content:
            application/vnd.adobe.platform.sensei+json;profile=insightListing.v1.json:
              schema:
                $ref: '#/components/schemas/InsightListing'
        '400':
          x-summary: Bad request
          description: Bad Request. The request is malformed.
          content: {}
        '401':
          x-summary: Unauthorized
          description: Unauthorized. The request has not been applied because it lacks valid authentication credentials for the target resource.
          content: {}
        '403':
          x-summary: Forbidden
          description: Forbidden. That combination of arguments is not allowed.
          content: {}
        '406':
          x-summary: Not acceptable
          description: Not Acceptable. Unacceptable content type. The caller sent an <b>Accept</b> header for a content type which does not exist on the server
          content: {}
        '500':
          x-summary: Internal server error
          description: There was an internal server error. Try the request again in a few minutes, and contact Adobe Support if the problem persists.
          content: {}
        '502':
          x-summary: Bad gateway
          description: Bad Gateway. This is an indicator that the search back-end did not send a valid response.
          content: {}
        503:
          x-summary: Service unavailable
          description: Service Unavailable. This is an indicator of a potential server overload.
          content: {}
        504:
          x-summary: Gateway timeout
          description: Gateway Timeout. This is an indicator that the search back-end did not complete a response within an allowed time period.
          content: {}
    post:
      tags:
      - Insights
      summary: Create a new Model insight
      description: Creates a new Model insight
      operationId: createInsights
      parameters:
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer " (for example, `Bearer {ACCESS_TOKEN}`). For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      - name: Content-Type
        in: header
        description: application/vnd.adobe.platform.sensei+json;profile=mlInstance.v1.json
        required: true
        schema:
          type: string
      requestBody:
        description: Insight object that needs to be added
        content:
          application/vnd.adobe.platform.sensei+json;profile=insight.v1.json:
            schema:
              $ref: '#/components/schemas/Insight'
        required: true
      responses:
        201:
          x-summary: Success
          description: Creation successful
          headers:
            Location:
              description: URL indicating the location of the created Engine resource
              schema:
                type: string
          content:
            application/vnd.adobe.platform.sensei+json;profile=insight.v1.json:
              schema:
                $ref: '#/components/schemas/Insight'
        '400':
          x-summary: Bad request
          description: Bad Request. The request is malformed.
          content: {}
        '401':
          x-summary: Unauthorized
          description: Unauthorized. The request has not been applied because it lacks valid authentication credentials for the target resource.
          content: {}
        '403':
          x-summary: Forbidden
          description: Forbidden. That combination of arguments is not allowed.
          content: {}
        '406':
          x-summary: Not acceptable
          description: Not Acceptable. Unacceptable content type. The caller sent an <b>Accept</b> header for a content type which does not exist on the server
          content: {}
        415:
          x-summary: Unsupported media type
          description: Unsupported Media Type. The server refuses to accept the request because the payload format is in an unsupported format.
          content: {}
        422:
          x-summary: Unprocessable entity
          description: Unprocessable Entity. Client sent a correct request that contained invalid values for one or more parameters.
          content: {}
        '500':
          x-summary: Internal server error
          description: There was an internal server error. Try the request again in a few minutes, and contact Adobe Support if the problem persists.
          content: {}
        '502':
          x-summary: Bad gateway
          description: Bad Gateway. This is an indicator that the search back-end did not send a valid response.
          content: {}
        503:
          x-summary: Service unavailable
          description: Service Unavailable. This is an indicator of a potential server overload.
          content: {}
        504:
          x-summary: Gateway timeout
          description: Gateway Timeout. This is an indicator that the search back-end did not complete a response within an allowed time period.
          content: {}
      x-codegen-request-body-name: insight
  /insights/{insightId}:
    get:
      tags:
      - Insights
      summary: Retrieve an insight
      description: Retrieves a specific insight
      operationId: retrieveInsight
      parameters:
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer " (for example, `Bearer {ACCESS_TOKEN}`). For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      - name: insightId
        in: path
        description: The identifier of the Sensei Insight
        required: true
        schema:
          type: string
      responses:
        '200':
          x-summary: Success
          description: Insight object
          content:
            application/vnd.adobe.platform.sensei+json;profile=insight.v1.json:
              schema:
                $ref: '#/components/schemas/Insight'
        '400':
          x-summary: Bad request
          description: Bad Request. The request is malformed.
          content: {}
        '401':
          x-summary: Unauthorized
          description: Unauthorized. The request has not been applied because it lacks valid authentication credentials for the target resource.
          content: {}
        '403':
          x-summary: Forbidden
          description: Forbidden. That combination of arguments is not allowed.
          content: {}
        404:
          x-summary: Not found
          description: The resource the client is looking for isn't there.
          content: {}
        '406':
          x-summary: Not acceptable
          description: Not Acceptable. Unacceptable content type. The caller sent an <b>Accept</b> header for a content type which does not exist on the server
          content: {}
        '500':
          x-summary: Internal server error
          description: There was an internal server error. Try the request again in a few minutes, and contact Adobe Support if the problem persists.
          content: {}
        '502':
          x-summary: Bad gateway
          description: Bad Gateway. This is an indicator that the search back-end did not send a valid response.
          content: {}
        503:
          x-summary: Service unavailable
          description: Service Unavailable. This is an indicator of a potential server overload.
          content: {}
        504:
          x-summary: Gateway timeout
          description: Gateway Timeout. This is an indicator that the search back-end did not complete a response within an allowed time period.
          content: {}
  /insights/metrics:
    get:
      tags:
      - Insights
      summary: List default metrics for algorithms
      description: Lists all default metrics available for algorithms
      operationId: retrieveMetrics
      parameters:
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer " (for example, `Bearer {ACCESS_TOKEN}`). For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the documentation covering making API calls in the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      - name: algorithm
        in: query
        description: The identifier of the algorithm type
        schema:
          type: string
      responses:
        '200':
          x-summary: Success
          description: List of metrics
          content:
            application/vnd.adobe.platform.sensei+json;profile=defaultMetricsListing.v1.json:
              schema:
                $ref: '#/components/schemas/DefaultMetricsListing'
        '400':
          x-summary: Bad request
          description: Bad Request. The request is malformed.
          content: {}
        '401':
          x-summary: Unauthorized
          description: Unauthorized. The request has not been applied because it lacks valid authentication credentials for the target resource.
          content: {}
        '403':
          x-summary: Forbidden
          description: Forbidden. That combination of arguments is not allowed.
          content: {}
        '406':
          x-summary: Not acceptable
          description: Not Acceptable. Unacceptable content type. The caller sent an <b>Accept</b> header for a content type which does not exist on the server
          content: {}
        '500':
          x-summary: Internal server error
          description: There was an internal server error. Try the request again in a few minutes, and contact Adobe Support if the problem persists.
          content: {}
        '502':
          x-summary: Bad gateway
          description: Bad Gateway. This is an indicator that the search back-end did not send a valid response.
          content: {}
        503:
          x-summary: Service unavailable
          description: Service Unavailable. This is an indicator of a potential server overload.
          content: {}
        504:
          x-summary: Gateway timeout
          description: Gateway Timeout. This is an indicator that the search back-end did not complete a response within an allowed time period.
          content: {}
components:
  schemas:
    LinkObject:
      required:
      - href
      type: object
      properties:
        href:
          type: string
          description: Either an URI (RFC3986) or an URI Template (RFC6570) in which case the linkObject SHOULD have a 'templated' attribute whose value is true
        templated:
          type: boolean
          description: True if the link href is templated, false otherwise which is also the default
          default: false
        type:
          type: string
          description: A hint to indicate the media type expected when dereferencing the target resource
        method:
          type: string
          description: The HTTP method to be applied when using this link. This should be a valid HTTP method name such as GET, PUT, POST, PATCH, DELETE where GET implies support for HEAD as well
          default: GET
        title:
          type: string
          description: A label with a human-readable identifier (as defined by RFC5988)
        hrefLang:
          type: string
          description: The language of the target resource (as defined by RFC5988)
    InsightListingLinks:
      allOf:
      - $ref: '#/components/schemas/PagingNavigationAttributes'
      - type: object
        properties:
          self:
            $ref: '#/components/schemas/LinkObject'
          createService:
            $ref: '#/components/schemas/LinkObject'
    InsightEvent:
      type: object
      properties:
        name:
          type: string
        eventValues:
          type: object
          additionalProperties:
            type: string
    DefaultMetrics:
      type: object
      properties:
        algorithm:
          type: string
        defaultMetrics:
          type: array
          items:
            type: string
    InsightListing:
      type: object
      properties:
        children:
          type: array
          items:
            $ref: '#/components/schemas/Insight'
        _page:
          $ref: '#/components/schemas/PagingInformationAttributes'
        _links:
          $ref: '#/components/schemas/InsightListingLinks'
    InsightMetricList:
      type: array
      items:
        $ref: '#/components/schemas/InsightMetric'
    PagingNavigationAttributes:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/LinkObject'
        page:
          $ref: '#/components/schemas/LinkObject'
    Insight:
      type: object
      properties:
        id:
          type: string
        context:
          $ref: '#/components/schemas/InsightContext'
        events:
          $ref: '#/components/schemas/InsightEvent'
        metrics:
          $ref: '#/components/schemas/InsightMetricList'
        created:
          type: string
          format: date-time
          readOnly: true
        updated:
          type: string
          format: date-time
          readOnly: true
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/LinkObject'
    InsightMetric:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
        valueType:
          type: string
    DefaultMetricsListing:
      type: object
      properties:
        children:
          type: array
          items:
            $ref: '#/components/schemas/DefaultMetrics'
    InsightContext:
      type: object
      properties:
        clientId:
          type: string
        notebookId:
          type: string
        experimentId:
          type: string
        engineId:
          type: string
        mlInstanceId:
          type: string
        experimentRunId:
          type: string
        modelId:
          type: string
        dataSetId:
          type: string
    PagingInformationAttributes:
      type: object
      properties:
        orderby:
          type: string
          readOnly: true
        property:
          type: string
          readOnly: true
        start:
          type: string
          readOnly: true
        totalCount:
          type: integer
          format: int64
          readOnly: true
        count:
          type: integer
          format: int64
          readOnly: true
        next:
          type: string
          readOnly: true
x-original-swagger-version: '2.0'