openapi: 3.1.0
info:
  title: PTV API - pmp-deals
  description: PTV API authoritative source of truth for PTV data.
  version: '1.0'
  contact:
    name: MNTN Platform
    url: https://api.mountain.com
    email: support@mountain.com
  license:
    name: Proprietary
servers:
- url: https://api.mountain.com/ptv
  description: MNTN Performance TV API gateway
tags:
- name: pmp-deals
  description: Private marketplace deal reads and lifecycle.
paths:
  /api/v1/deals:
    get:
      operationId: pmp.deals.list
      parameters:
      - name: page
        required: false
        in: query
        description: 1-based page number.
        schema:
          minimum: 1
          type: number
      - name: perPage
        required: false
        in: query
        description: Results per page (maximum 100).
        schema:
          minimum: 1
          maximum: 100
          type: number
      - name: partnerId
        required: false
        in: query
        description: Filter to a single partner.
        schema:
          maximum: 9007199254740991
          exclusiveMinimum: true
          type: integer
          minimum: 0
      - name: active
        required: false
        in: query
        description: Filter by active status.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: sortBy
        required: false
        in: query
        description: Field to sort by. Defaults to pmpDealId.
        schema:
          type: string
          enum:
          - pmpDealId
          - name
          - partnerDealId
          - partnershipDealType
          - floorPrice
          - active
          - pricingModel
          - startTime
          - endTime
          - createTime
          - updateTime
      - name: sortOrder
        required: false
        in: query
        description: Sort order. Defaults to desc.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: search
        required: false
        in: query
        description: Case-insensitive substring matched over name and partnerDealId (≤ 200 chars).
        schema:
          maxLength: 200
          type: string
      - name: partnerDealId
        required: false
        in: query
        description: Exact partner-assigned deal ID. Returns the single matching deal, or an empty list.
        schema:
          minLength: 1
          maxLength: 200
          type: string
      - name: partnershipDealType
        required: false
        in: query
        description: Filter deals by partnership deal type.
        schema:
          type: string
          enum:
          - EXCLUSIVE
          - SSP
          - PUB_DIRECT
      responses:
        default:
          description: Unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDealsResponseDto_Output'
      summary: List PMP deals
      tags:
      - pmp-deals
      x-hide-from-docs: true
    post:
      operationId: pmp.deals.create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDealBodyDto'
      responses:
        default:
          description: Unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DealResponseDto_Output'
      summary: Create a PMP deal
      tags:
      - pmp-deals
      x-hide-from-docs: true
  /api/v1/deals/bulk-deactivate:
    post:
      operationId: pmp.deals.bulkDeactivate
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealBulkDeactivateBodyDto'
      responses:
        default:
          description: Unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DealBulkDeactivateResultResponseDto_Output'
      summary: Bulk-deactivate PMP deals
      tags:
      - pmp-deals
      x-hide-from-docs: true
  /api/v1/deals/{pmpDealId}:
    get:
      operationId: pmp.deals.get
      parameters:
      - name: pmpDealId
        required: true
        in: path
        schema:
          type: number
      responses:
        default:
          description: Unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DealResponseDto_Output'
      summary: Get a PMP deal
      tags:
      - pmp-deals
      x-hide-from-docs: true
    patch:
      operationId: pmp.deals.update
      parameters:
      - name: pmpDealId
        required: true
        in: path
        schema:
          type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDealBodyDto'
      responses:
        default:
          description: Unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DealResponseDto_Output'
      summary: Update a PMP deal
      tags:
      - pmp-deals
      x-hide-from-docs: true
    delete:
      operationId: pmp.deals.delete
      parameters:
      - name: pmpDealId
        required: true
        in: path
        schema:
          type: number
      responses:
        '204':
          description: ''
      summary: Delete a PMP deal
      tags:
      - pmp-deals
      x-hide-from-docs: true
  /api/v1/deals/{pmpDealId}/deal-groups:
    get:
      operationId: pmp.deals.listGroups
      parameters:
      - name: pmpDealId
        required: true
        in: path
        schema:
          type: number
      responses:
        default:
          description: Unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DealGroupLinksListResponseDto_Output'
      summary: List deal groups a deal belongs to
      tags:
      - pmp-deals
      x-hide-from-docs: true
security:
- Bearer: []
- API Key: []
components:
  schemas:
    CreateDealBodyDto:
      type: object
      properties:
        partnerDealId:
          type: string
          minLength: 1
          description: Partner-assigned deal ID.
        floorPrice:
          description: Floor price in USD (≥ 0).
          type: number
          minimum: 0
        name:
          description: Deal name.
          type: string
          minLength: 1
        partnerId:
          type: integer
          exclusiveMinimum: true
          maximum: 9007199254740991
          description: Partner ID.
          minimum: 0
        startTime:
          description: Deal start time.
          type: string
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
        endTime:
          description: Deal end time.
          type: string
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
        active:
          type: boolean
          description: Whether the deal is active on create.
        dspPartnerId:
          type: integer
          exclusiveMinimum: true
          maximum: 9007199254740991
          description: DSP partner ID.
          minimum: 0
        pricingModel:
          type: string
          enum:
          - BIDDABLE
          - FIXED
          description: Pricing model.
        partnershipDealType:
          type: string
          enum:
          - EXCLUSIVE
          - SSP
          - PUB_DIRECT
          description: Partnership deal type.
        publisherId:
          description: Publisher ID; required for EXCLUSIVE deals.
          type: integer
          exclusiveMinimum: true
          maximum: 9007199254740991
          minimum: 0
        generateDealGroup:
          description: When true, PAPI also creates a matching deal group and links this deal to it.
          type: boolean
      required:
      - partnerDealId
      - partnerId
      - active
      - dspPartnerId
      - pricingModel
      - partnershipDealType
    DealBulkDeactivateResultResponseDto_Output:
      type: object
      properties:
        data:
          type: object
          properties:
            dealsUpdated:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: Rows matched by the update.
          required:
          - dealsUpdated
          additionalProperties: false
          description: Bulk deactivate result.
      required:
      - data
      additionalProperties: false
    DealGroupLinksListResponseDto_Output:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              pmpDealId:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: PMP deal ID.
              dealGroupId:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: Deal group ID.
              createTime:
                type: string
                description: Link creation timestamp (ISO8601).
              updateTime:
                type: string
                description: Link last update timestamp (ISO8601).
              createdBy:
                type:
                - integer
                - 'null'
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: User who created the link.
            required:
            - pmpDealId
            - dealGroupId
            - createTime
            - updateTime
            - createdBy
            additionalProperties: false
            description: A deal <-> deal-group membership link.
      required:
      - data
      additionalProperties: false
    UpdateDealBodyDto:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Deal name.
        floorPrice:
          type: number
          minimum: 0
          description: Floor price in USD (≥ 0).
        startTime:
          type: string
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
          description: Deal start time.
        endTime:
          type: string
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
          description: Deal end time.
        active:
          type: boolean
          description: Whether the deal is active.
        pricingModel:
          type: string
          enum:
          - BIDDABLE
          - FIXED
          description: Pricing model.
        partnershipDealType:
          type: string
          enum:
          - EXCLUSIVE
          - SSP
          - PUB_DIRECT
          description: Partnership deal type.
        dspPartnerId:
          type: integer
          exclusiveMinimum: true
          maximum: 9007199254740991
          description: DSP partner ID.
          minimum: 0
        publisherId:
          type: integer
          exclusiveMinimum: true
          maximum: 9007199254740991
          description: Publisher ID.
          minimum: 0
    DealBulkDeactivateBodyDto:
      type: object
      properties:
        pmpDealIds:
          minItems: 1
          maxItems: 1000
          type: array
          items:
            type: integer
            exclusiveMinimum: true
            maximum: 9007199254740991
            minimum: 0
          description: PMP deal IDs to deactivate (1–1000 per request).
      required:
      - pmpDealIds
    PaginatedDealsResponseDto_Output:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              pmpDealId:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: PMP deal ID.
              partnerDealId:
                type: string
                description: Partner-assigned deal ID.
              createdBy:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: User who created the deal.
              floorPrice:
                type:
                - number
                - 'null'
                description: Floor price (USD); null when unset.
              name:
                type:
                - string
                - 'null'
                description: Deal name; null when unset.
              partnerId:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: Partner ID.
              startTime:
                type:
                - string
                - 'null'
                description: Start time (ISO8601); null when unset.
              endTime:
                type:
                - string
                - 'null'
                description: End time (ISO8601); null when unset.
              active:
                type: boolean
                description: Whether the deal is currently active.
              createTime:
                type: string
                description: Creation timestamp (ISO8601).
              updateTime:
                type: string
                description: Last update timestamp (ISO8601).
              dspPartnerId:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: DSP partner ID.
              updatedBy:
                type:
                - integer
                - 'null'
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: User who last modified the deal.
              pricingModel:
                type: string
                enum:
                - BIDDABLE
                - FIXED
                description: Pricing model.
              partnershipDealType:
                type: string
                enum:
                - EXCLUSIVE
                - SSP
                - PUB_DIRECT
                description: Partnership deal type.
              publisherId:
                type:
                - integer
                - 'null'
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: Publisher ID; null when not exclusive.
              channelId:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: Channel ID.
              status:
                type: string
                enum:
                - active
                - inactive
                - scheduled
                - ended
                description: Status derived from active + start/end window.
              channelName:
                type: string
                description: Resolved channel name.
              dealGroups:
                type: array
                items:
                  type: object
                  properties:
                    dealGroupId:
                      type: integer
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                      description: Deal group ID.
                    name:
                      type: string
                      description: Deal group name.
                  required:
                  - dealGroupId
                  - name
                  additionalProperties: false
                description: Deal groups this deal belongs to; empty without deal-group read permission.
            required:
            - pmpDealId
            - partnerDealId
            - createdBy
            - floorPrice
            - name
            - partnerId
            - startTime
            - endTime
            - active
            - createTime
            - updateTime
            - dspPartnerId
            - updatedBy
            - pricingModel
            - partnershipDealType
            - publisherId
            - channelId
            - status
            - channelName
            - dealGroups
            additionalProperties: false
            description: A PMP deal.
        pagination:
          type: object
          properties:
            total:
              type: integer
              minimum: 0
              maximum: 9007199254740991
              description: Total rows available for this query.
            perPage:
              type: integer
              exclusiveMinimum: true
              maximum: 9007199254740991
              description: Maximum rows per page.
              minimum: 0
            page:
              default: 1
              description: Current 1-based page index.
              type: integer
              exclusiveMinimum: true
              maximum: 9007199254740991
              minimum: 0
            previousPageUrl:
              type:
              - string
              - 'null'
              description: URL for the previous page, or null when none.
            nextPageUrl:
              type:
              - string
              - 'null'
              description: URL for the next page, or null when none.
          required:
          - total
          - perPage
          - page
          - previousPageUrl
          - nextPageUrl
          additionalProperties: false
      required:
      - data
      - pagination
      additionalProperties: false
    DealResponseDto_Output:
      type: object
      properties:
        data:
          type: object
          properties:
            pmpDealId:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: PMP deal ID.
            partnerDealId:
              type: string
              description: Partner-assigned deal ID.
            createdBy:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: User who created the deal.
            floorPrice:
              type:
              - number
              - 'null'
              description: Floor price (USD); null when unset.
            name:
              type:
              - string
              - 'null'
              description: Deal name; null when unset.
            partnerId:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: Partner ID.
            startTime:
              type:
              - string
              - 'null'
              description: Start time (ISO8601); null when unset.
            endTime:
              type:
              - string
              - 'null'
              description: End time (ISO8601); null when unset.
            active:
              type: boolean
              description: Whether the deal is currently active.
            createTime:
              type: string
              description: Creation timestamp (ISO8601).
            updateTime:
              type: string
              description: Last update timestamp (ISO8601).
            dspPartnerId:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: DSP partner ID.
            updatedBy:
              type:
              - integer
              - 'null'
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: User who last modified the deal.
            pricingModel:
              type: string
              enum:
              - BIDDABLE
              - FIXED
              description: Pricing model.
            partnershipDealType:
              type: string
              enum:
              - EXCLUSIVE
              - SSP
              - PUB_DIRECT
              description: Partnership deal type.
            publisherId:
              type:
              - integer
              - 'null'
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: Publisher ID; null when not exclusive.
            channelId:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: Channel ID.
            status:
              type: string
              enum:
              - active
              - inactive
              - scheduled
              - ended
              description: Status derived from active + start/end window.
            channelName:
              type: string
              description: Resolved channel name.
            dealGroups:
              type: array
              items:
                type: object
                properties:
                  dealGroupId:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: Deal group ID.
                  name:
                    type: string
                    description: Deal group name.
                required:
                - dealGroupId
                - name
                additionalProperties: false
              description: Deal groups this deal belongs to; empty without deal-group read permission.
          required:
          - pmpDealId
          - partnerDealId
          - createdBy
          - floorPrice
          - name
          - partnerId
          - startTime
          - endTime
          - active
          - createTime
          - updateTime
          - dspPartnerId
          - updatedBy
          - pricingModel
          - partnershipDealType
          - publisherId
          - channelId
          - status
          - channelName
          - dealGroups
          additionalProperties: false
          description: A PMP deal.
      required:
      - data
      additionalProperties: false
  securitySchemes:
    Bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    API Key:
      type: apiKey
      in: header
      name: X-API-Key