openapi: 3.1.0
info:
  title: Seismic Analytics Content Analytics API
  description: API for accessing analytics and reporting data on content usage, user engagement, and sales effectiveness within the Seismic platform. Provides insights into how content is being used, which materials are most effective, and how teams are engaging with sales enablement resources.
  version: 2.0.0
  termsOfService: https://seismic.com/terms-of-service/
  contact:
    name: Seismic Support
    url: https://seismic.com/support/
    email: support@seismic.com
  license:
    name: Proprietary
    url: https://seismic.com/terms-of-service/
servers:
- url: https://api.seismic.com/integration/v2
  description: Seismic API v2 Production
security:
- bearerAuth: []
tags:
- name: Content Analytics
  description: Analytics on content usage, views, and engagement.
paths:
  /analytics/content:
    get:
      operationId: getContentAnalytics
      summary: Get Content Analytics
      description: Retrieves analytics data for content items, including views, downloads, shares, and engagement metrics.
      tags:
      - Content Analytics
      parameters:
      - name: contentId
        in: query
        description: Filter analytics for a specific content item.
        schema:
          type: string
      - name: contentProfileId
        in: query
        description: Filter analytics by content profile.
        schema:
          type: string
      - name: folderId
        in: query
        description: Filter analytics by folder.
        schema:
          type: string
      - name: startDate
        in: query
        description: Start date for the analytics period (ISO 8601 format).
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: End date for the analytics period (ISO 8601 format).
        schema:
          type: string
          format: date
      - name: granularity
        in: query
        description: Time granularity for the analytics data.
        schema:
          type: string
          enum:
          - daily
          - weekly
          - monthly
          default: daily
      - name: sortBy
        in: query
        description: Metric to sort results by.
        schema:
          type: string
          enum:
          - views
          - downloads
          - shares
          - engagement
      - name: sortOrder
        in: query
        description: Sort order direction.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: offset
        in: query
        description: Number of items to skip for pagination.
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: Maximum number of items to return.
        schema:
          type: integer
          default: 25
          maximum: 100
      responses:
        '200':
          description: Content analytics data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContentAnalytics'
                  totalCount:
                    type: integer
                  period:
                    type: object
                    properties:
                      startDate:
                        type: string
                        format: date
                      endDate:
                        type: string
                        format: date
                  summary:
                    $ref: '#/components/schemas/ContentAnalyticsSummary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /analytics/content/{contentId}:
    get:
      operationId: getContentItemAnalytics
      summary: Get Analytics for a Content Item
      description: Retrieves detailed analytics data for a specific content item, including time-series data on views, downloads, and engagement.
      tags:
      - Content Analytics
      parameters:
      - name: contentId
        in: path
        required: true
        description: Unique identifier of the content item.
        schema:
          type: string
      - name: startDate
        in: query
        description: Start date for the analytics period.
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: End date for the analytics period.
        schema:
          type: string
          format: date
      - name: granularity
        in: query
        description: Time granularity for time-series data.
        schema:
          type: string
          enum:
          - daily
          - weekly
          - monthly
          default: daily
      responses:
        '200':
          description: Detailed content analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentAnalyticsDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /analytics/content/top:
    get:
      operationId: getTopContent
      summary: Get Top-performing Content
      description: Retrieves a ranked list of the top-performing content items based on engagement, views, or other metrics.
      tags:
      - Content Analytics
      parameters:
      - name: metric
        in: query
        description: Metric to rank content by.
        required: true
        schema:
          type: string
          enum:
          - views
          - downloads
          - shares
          - engagement
          - completionRate
      - name: startDate
        in: query
        description: Start date for the analytics period.
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: End date for the analytics period.
        schema:
          type: string
          format: date
      - name: limit
        in: query
        description: Number of top content items to return.
        schema:
          type: integer
          default: 10
          maximum: 50
      responses:
        '200':
          description: Top-performing content items.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContentAnalytics'
                  metric:
                    type: string
                  period:
                    type: object
                    properties:
                      startDate:
                        type: string
                        format: date
                      endDate:
                        type: string
                        format: date
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    Forbidden:
      description: Forbidden. The authenticated user does not have permission to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too many requests. Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Retry-After:
          description: Number of seconds to wait before making another request.
          schema:
            type: integer
    Unauthorized:
      description: Unauthorized. Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request. The request was invalid or cannot be processed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found. The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ContentAnalyticsDetail:
      type: object
      properties:
        contentId:
          type: string
          description: ID of the content item.
        contentName:
          type: string
          description: Name of the content item.
        summary:
          $ref: '#/components/schemas/ContentAnalytics'
        timeSeries:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              views:
                type: integer
              downloads:
                type: integer
              shares:
                type: integer
              engagementScore:
                type: number
                format: float
          description: Time-series analytics data points.
        viewerBreakdown:
          type: array
          items:
            type: object
            properties:
              userId:
                type: string
              userName:
                type: string
              views:
                type: integer
              lastViewedAt:
                type: string
                format: date-time
          description: Breakdown of viewers for this content item.
    ContentAnalyticsSummary:
      type: object
      properties:
        totalViews:
          type: integer
          description: Total views across all content.
        totalDownloads:
          type: integer
          description: Total downloads across all content.
        totalShares:
          type: integer
          description: Total shares across all content.
        averageEngagementScore:
          type: number
          format: float
          description: Average engagement score across all content.
        activeContentCount:
          type: integer
          description: Number of content items with at least one view.
    ContentAnalytics:
      type: object
      properties:
        contentId:
          type: string
          description: ID of the content item.
        contentName:
          type: string
          description: Name of the content item.
        views:
          type: integer
          description: Total number of views.
        uniqueViews:
          type: integer
          description: Number of unique viewers.
        downloads:
          type: integer
          description: Total number of downloads.
        shares:
          type: integer
          description: Total number of shares.
        engagementScore:
          type: number
          format: float
          description: Calculated engagement score (0-100).
        averageViewDuration:
          type: number
          format: float
          description: Average view duration in seconds.
        completionRate:
          type: number
          format: float
          description: Percentage of content viewed on average (0-100).
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code.
            message:
              type: string
              description: Human-readable error message.
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer Token. Obtain tokens through the Seismic authentication flow. See https://developer.seismic.com/seismicsoftware/docs/authentication