Adobe Suite Annotations API

openapi: 3.2.0
info:
  description: "The endpoints described here are routed through analytics.adobe.io. In order to use these endpoints you must create an oAuth client that is subscribed to access the Adobe Analytics Reporting API. \n\n To view the API References for non-core Analytics 2.0 APIs, select the **API Reference** drop-down menu at the top of the page. \n\n Note: Adobe may add optional request and response members (name/value pairs) to existing API objects at any time and without notice or changes in versioning. Adobe recommends that you refer to the API documentation of any third-party tool you integrate with our APIs so that such additions are ignored in processing if not understood. If implemented properly, such additions are non-breaking changes for your implementation. Adobe will not remove parameters or add required parameters without first providing standard notification through release notes."
  title: Adobe Analytics Annotations API
  version: '2.0'
servers:
- url: https://analytics.adobe.io/api
tags:
- name: Annotations
paths:
  /{globalCompanyId}/annotations:
    get:
      tags:
      - Annotations
      summary: Retrieve all annotations.
      description: ''
      operationId: getAnnotations_1
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: expansion
        in: query
        description: Comma-delimited list of additional annotation metadata fields to include on response.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - name
            - description
            - dateRange
            - color
            - applyToAllReports
            - scope
            - createdDate
            - modifiedDate
            - modifiedById
            - owner
            - companyId
            - rsid
            - approved
            - favorite
            - shares
            - sharesFullName
            - tags
            - usageSummary
            - usageSummaryWithRelevancyScore
            - ownerFullName
            - reportSuiteName
      - name: includeType
        in: query
        description: Include additional annotations not owned by user. The "all" option takes precedence over "shared"
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - all
            - shared
      - name: locale
        in: query
        description: Locale
        required: false
        schema:
          type: string
          default: en_US
      - name: filterByIds
        in: query
        required: false
        schema:
          type: string
      - name: filterByModifiedAfter
        in: query
        description: Filter list to only include annotations modified since this date (ISO8601 format)
        required: false
        schema:
          type: string
      - name: filterByDateRange
        in: query
        description: Filter list to only include annotations in the specified date range with format yyyy-MM-dd'T'HH:mm:ss/yyyy-MM-dd'T'hh:MM:ss
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results per page
        required: false
        schema:
          type: integer
          default: 10
      - name: page
        in: query
        description: Page number (base 0 - first page is "0")
        required: false
        schema:
          type: integer
          default: 0
      - name: sortDirection
        in: query
        description: Sort direction (ASC or DESC
        required: false
        schema:
          type: integer
          default: ASC
      - name: sortProperty
        in: query
        description: Property to sort by (name, modified_date, id is currently allowed)
        required: false
        schema:
          type: string
          default: id
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsAnnotation'
    post:
      tags:
      - Annotations
      summary: Create new annotation
      description: ''
      operationId: createAnnotation_1
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: expansion
        in: query
        description: Comma-delimited list of additional annotation metadata fields to include on response.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - name
            - description
            - dateRange
            - color
            - applyToAllReports
            - scope
            - createdDate
            - modifiedDate
            - modifiedById
            - owner
            - companyId
            - rsid
            - approved
            - favorite
            - shares
            - sharesFullName
            - tags
            - usageSummary
            - usageSummaryWithRelevancyScore
            - ownerFullName
            - reportSuiteName
      - name: locale
        in: query
        description: Locale
        required: false
        schema:
          type: string
          default: en_US
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsAnnotation'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsAnnotation'
        description: JSON-formatted Object containing date range keys/value pairs to be updated.
  /{globalCompanyId}/annotations/{id}:
    get:
      tags:
      - Annotations
      summary: Get existing annotation
      description: ''
      operationId: getAnnotation_1
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: expansion
        in: query
        description: Comma-delimited list of additional annotation metadata fields to include on response.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - name
            - description
            - dateRange
            - color
            - applyToAllReports
            - scope
            - createdDate
            - modifiedDate
            - modifiedById
            - owner
            - companyId
            - rsid
            - approved
            - favorite
            - shares
            - sharesFullName
            - tags
            - usageSummary
            - usageSummaryWithRelevancyScore
            - ownerFullName
            - reportSuiteName
      - name: id
        in: path
        description: Annotation ID to retrieve
        required: true
        schema:
          type: string
      - name: locale
        in: query
        description: Locale
        required: false
        schema:
          type: string
          default: en_US
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsAnnotation'
    put:
      tags:
      - Annotations
      summary: Update existing annotation
      description: ''
      operationId: updateAnnotation_1
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: expansion
        in: query
        description: Comma-delimited list of additional annotation metadata fields to include on response.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - name
            - description
            - dateRange
            - color
            - applyToAllReports
            - scope
            - createdDate
            - modifiedDate
            - modifiedById
            - owner
            - companyId
            - rsid
            - approved
            - favorite
            - shares
            - sharesFullName
            - tags
            - usageSummary
            - usageSummaryWithRelevancyScore
            - ownerFullName
            - reportSuiteName
      - name: id
        in: path
        description: Annotation ID to update
        required: true
        schema:
          type: string
      - name: locale
        in: query
        description: Locale
        required: false
        schema:
          type: string
          default: en_US
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsAnnotation'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsAnnotation'
        description: JSON-formatted Object containing date range keys/value pairs to be updated.
    delete:
      tags:
      - Annotations
      summary: Delete existing annotation
      description: ''
      operationId: deleteAnnotation_1
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: id
        in: path
        description: Annotation ID to update
        required: true
        schema:
          type: string
      - name: locale
        in: query
        description: Locale
        required: false
        schema:
          type: string
          default: en_US
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
components:
  parameters:
    authorization:
      name: Authorization
      in: header
      description: The access token copied from your AA API client integration, prefixed with "Bearer ".
      required: true
      schema:
        type: string
    x-api-key:
      name: x-api-key
      in: header
      description: The API key copied from your AA API client integration. For more information on how to obtain this value, see [Getting started with the Analytics API](https://developer.adobe.com/analytics-apis/docs/2.0/guides/).
      required: true
      schema:
        type: string
  schemas:
    DeleteResponse:
      type: object
      properties:
        result:
          type: string
        message:
          type: string
    AnnotationScope:
      type: object
      properties:
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/ScopeMetric'
        filters:
          type: array
          items:
            $ref: '#/components/schemas/ScopeFilter'
    Owner:
      type: object
      required:
      - id
      properties:
        id:
          type: integer
          format: int32
          description: the login id of the owner
        name:
          type: string
          description: the friendly full login name of the owner, included when the expansion parameter ownerFullName is true
        login:
          type: string
          description: the friendly full login name of the owner, included when the expansion parameter ownerFullName is true
    ScopeMetric:
      type: object
      properties:
        id:
          type: string
        componentType:
          type: string
    ScopeFilter:
      type: object
      properties:
        id:
          type: string
        operator:
          type: string
        dimensionType:
          type: string
        terms:
          type: array
          items:
            type: string
        componentType:
          type: string
    AnalyticsAnnotation:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        dateRange:
          type: string
        color:
          type: string
          enum:
          - STANDARD1
          - STANDARD2
          - STANDARD3
          - STANDARD4
          - STANDARD5
          - STANDARD6
          - STANDARD7
          - STANDARD8
          - STANDARD9
        applyToAllReports:
          type: boolean
        scope:
          $ref: '#/components/schemas/AnnotationScope'
        createdDate:
          type: string
          format: date-time
        modifiedDate:
          type: string
          format: date-time
        modifiedById:
          type: string
        tags:
          type: array
          items:
            type: object
            additionalProperties:
              type: object
        shares:
          type: array
          items:
            type: object
            additionalProperties:
              type: object
        approved:
          type: boolean
        favorite:
          type: boolean
        usageSummary:
          type: object
          additionalProperties:
            type: object
        systemUserOwned:
          type: boolean
        owner:
          $ref: '#/components/schemas/Owner'
        companyId:
          type: integer
          format: int32
        reportSuiteName:
          type: string
        rsid:
          type: string