Mavrck Instance Level API

openapi: 3.2.0
info:
  title: Later Influence™ Instance Level API
  description: '# Description

    The Reporting API enables deep analysis and reporting of marketing campaigns, social media performance, and influencer effectiveness.'
  version: 1.2.1
  contact:
    name: Developer
    url: https://help-influence.later.com/hc/en-us
    email: urvash.chheda@later.com
  termsOfService: https://later.com/terms/
servers:
- url: https://api.mavrck.co
security:
- JWT: []
tags:
- name: Instance Level
paths:
  /v1/reporting/instances:
    get:
      description: Get all instances accessible by the provided API credentials
      operationId: getAllowedInstances
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ReportingApiResponseDto'
                - properties:
                    data:
                      $ref: '#/components/schemas/InstancesResponseDto'
                    meta:
                      example: null
      summary: Get allowed instances
      tags:
      - Instance Level
      x-summary-source: derived
  /v1/reporting/instance/details:
    get:
      description: Get details for associated instance available for the provided API credentials. If the credentials have access to multiple instances, the first one will be returned, consider using `GET /instances/details` to get details for all instances.
      operationId: getInfoAboutInstanceAndCampaigns
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ReportingApiResponseDto'
                - properties:
                    data:
                      $ref: '#/components/schemas/InstanceDetailsResponseDto'
                    meta:
                      example: null
      summary: Get info about instance and campaigns
      tags:
      - Instance Level
      x-summary-source: derived
  /v1/reporting/instances/details:
    get:
      description: Get details for all the associated instances available for the provided API credentials
      operationId: getInfoAboutMultipleInstancesAndCampaigns
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ReportingApiResponseDto'
                - properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/InstanceDetailsResponseDto'
                    meta:
                      example: null
      summary: Get info about multiple instances and campaigns
      tags:
      - Instance Level
      x-summary-source: derived
  /v1/reporting/instance/performance:
    get:
      description: Get instance performance details.
      operationId: getInstancePerformance
      parameters:
      - name: startDate
        required: true
        in: query
        description: Start date for the report, YYYY-MM-dd format
        schema:
          format: date-time
          type: string
      - name: endDate
        required: true
        in: query
        description: End date for the report, YYYY-MM-dd format
        schema:
          format: date-time
          type: string
      - name: instanceIds
        required: false
        in: query
        description: A list of instance ids. If not provided, all instances associated with the API credentials will be considered.
        schema:
          type: array
          items:
            type: string
      - name: campaignIds
        required: false
        in: query
        description: A list of campaign ids (max 50 items)
        schema:
          type: array
          items:
            type: number
      - name: reportingGroupIds
        required: false
        in: query
        description: A list of reporting group ids
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ReportingApiResponseDto'
                - properties:
                    data:
                      $ref: '#/components/schemas/InstancePerformanceResponseDto'
                    meta:
                      example: null
      summary: Get instance performance
      tags:
      - Instance Level
      x-summary-source: derived
  /v1/reporting/instance/performance-over-time:
    get:
      description: Get instance performance details over time.
      operationId: getPerformanceOverTime
      parameters:
      - name: startDate
        required: true
        in: query
        description: Start date for the report, YYYY-MM-dd format
        schema:
          format: date-time
          type: string
      - name: endDate
        required: true
        in: query
        description: End date for the report, YYYY-MM-dd format
        schema:
          format: date-time
          type: string
      - name: instanceIds
        required: false
        in: query
        description: A list of instance ids. If not provided, all instances associated with the API credentials will be considered.
        schema:
          type: array
          items:
            type: string
      - name: campaignIds
        required: false
        in: query
        description: A list of campaign ids (max 50 items)
        schema:
          type: array
          items:
            type: number
      - name: reportingGroupIds
        required: false
        in: query
        description: A list of reporting group ids
        schema:
          type: array
          items:
            type: string
      - name: pageSize
        required: false
        in: query
        description: Number of items per page
        schema:
          default: 50
          type: number
      - name: pageNumber
        required: false
        in: query
        description: The page you would like to get data for
        schema:
          default: 1
          type: number
      - name: granularity
        required: false
        in: query
        schema:
          default: month
          type: string
          enum:
          - year
          - quarter
          - month
          - week
          - day
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ReportingApiGranularResponseDto'
                - properties:
                    data:
                      type: array
                      items:
                        type: object
                        properties:
                          metrics:
                            $ref: '#/components/schemas/InstancePerformanceOverTimeMetricsDto'
                          date:
                            $ref: '#/components/schemas/PerformanceOverTimeDateDto'
      summary: Get performance over time
      tags:
      - Instance Level
      x-summary-source: derived
components:
  schemas:
    ReportingApiGranularResponseDto:
      type: object
      properties:
        data:
          type: object
          description: A data object containing a generic metrics object | array and a date object
          additionalProperties: true
        meta:
          type: object
          description: Metadata containing page information
          properties:
            page:
              type: number
              example: 1
            totalPages:
              type: number
              example: 10
      required:
      - data
      - meta
    InstanceDetailsResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the instance
          example: instance_123
        campaignsCount:
          type: number
          description: Number of campaigns associated with the instance
          example: 5
        influencersCount:
          type: number
          description: Number of influencers associated with the instance
          example: 10
        campaigns:
          description: List of campaigns associated with the instance
          example:
          - id: 49761
            title: demo campaign 1
            description: ''
            status: LIVE
            startDate: '2023-06-06T06:52:00.000Z'
          - id: 49762
            title: demo campaign 2
            description: null
            status: LIVE
            startDate: '2023-06-07T06:29:00.000Z'
          type: array
          items:
            $ref: '#/components/schemas/InstanceCampaignDto'
      required:
      - id
      - campaignsCount
      - influencersCount
      - campaigns
    InstancePerformanceResponseDto:
      type: object
      properties:
        engagements:
          type:
          - number
          - 'null'
          example: 1000
          description: Total number of engagements
        impressions:
          type:
          - number
          - 'null'
          example: 10000
          description: Total number of impressions
        engagementRate:
          type:
          - number
          - 'null'
          example: 0.1
          description: Engagement rate as a decimal
        postsCount:
          type:
          - number
          - 'null'
          example: 50
          description: Total number of posts
        valueGenerated:
          type:
          - number
          - 'null'
          example: 5000
          description: Total value generated
        returnOnInvestment:
          type:
          - number
          - 'null'
          example: 2.5
          description: Return on investment as a ratio
        estimatedContentCost:
          type:
          - number
          - 'null'
          example: 2000
          description: Is calculated based on how many posts received metrics in the selected time range vs the amount of money paid to the author(influencer)
        campaignsCost:
          type:
          - number
          - 'null'
          example: 3000
          description: Is calculated based on the paid amount to influencers participating in the selected campaigns
        conversionValue:
          type:
          - number
          - 'null'
          example: 7500
          description: Total tracking links conversion value
      required:
      - engagements
      - impressions
      - engagementRate
      - postsCount
      - valueGenerated
      - returnOnInvestment
      - estimatedContentCost
      - campaignsCost
      - conversionValue
    InstancesResponseDto:
      type: object
      properties:
        instanceIds:
          description: A list of instance ids the API credentials have access to
          example:
          - instance_123
          - instance_456
          type: array
          items:
            type: string
      required:
      - instanceIds
    ReportingApiResponseDto:
      type: object
      properties:
        data:
          type: object
          additionalProperties: false
        meta:
          type:
          - object
          - 'null'
          description: Metadata containing page information
          properties:
            page:
              type: number
              example: 1
            totalPages:
              type: number
              example: 10
      required:
      - data
      - meta
    InstanceCampaignDto:
      type: object
      properties:
        id:
          type: number
          description: Unique identifier for the campaign
          example: 1
        title:
          type:
          - string
          - 'null'
          description: Title of the campaign
          example: Summer Sale Campaign
        description:
          type:
          - string
          - 'null'
          description: Description of the campaign
          example: This campaign is focused on summer sales.
        status:
          type:
          - string
          - 'null'
          description: Status of the campaign
          example: active
        startDate:
          type:
          - string
          - 'null'
          description: Start date of the campaign
          format: date-time
          example: '2023-10-01T00:00:00Z'
      required:
      - id
      - title
      - description
      - status
      - startDate
    PerformanceOverTimeDateDto:
      type: object
      properties:
        year:
          type: number
          description: Year
          example: 2023
        quarter:
          type: number
          description: Quarter
          example: 4
        month:
          type: number
          description: Month
          example: 10
        week:
          type: number
          description: Week
          example: 42
        day:
          type: number
          description: Day
          example: 15
        fullDate:
          type: string
          description: ISO 8601 date format (YYYY-MM-DD)
          example: '2023-10-15'
      required:
      - year
    InstancePerformanceOverTimeMetricsDto:
      type: object
      properties:
        likes:
          type:
          - number
          - 'null'
          example: 100
          description: Number of likes
        comments:
          type:
          - number
          - 'null'
          example: 50
          description: Number of comments
        shares:
          type:
          - number
          - 'null'
          example: 25
          description: Number of shares
        clicks:
          type:
          - number
          - 'null'
          example: 200
          description: Number of clicks
        engagements:
          type:
          - number
          - 'null'
          example: 375
          description: Total number of engagements
        impressions:
          type:
          - number
          - 'null'
          example: 1000
          description: Number of impressions
        valueGenerated:
          type:
          - number
          - 'null'
          example: 500.5
          description: Value generated
        engagementRate:
          type:
          - number
          - 'null'
          example: 0.375
          description: Engagement rate
        cpe:
          type:
          - number
          - 'null'
          example: 1.33
          description: Cost per engagement
        cpm:
          type:
          - number
          - 'null'
          example: 5
          description: Cost per mille (thousand impressions)
      required:
      - likes
      - comments
      - shares
      - clicks
      - engagements
      - impressions
      - valueGenerated
      - engagementRate
      - cpe
      - cpm
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT obtained from the OAuth2 token endpoint