openapi: 3.2.0
info:
  title: Ad Seller System Media Kit API
  description: IAB OpenDirect 2.1 compliant seller agent for programmatic advertising. Supports product discovery, tiered pricing, proposal evaluation, multi-round negotiation, deal execution, order management, and change requests.
  contact:
    name: IAB Tech Lab
    url: https://iabtechlab.com/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 1.0.0
tags:
- name: Media Kit
  description: Public media kit and package catalog
paths:
  /media-kit:
    get:
      tags:
      - Media Kit
      summary: Media Kit Overview
      description: Public media kit catalog overview.
      operationId: media_kit_overview_media_kit_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /media-kit/packages:
    get:
      tags:
      - Media Kit
      summary: List Media Kit Packages
      description: 'List packages with public view (price ranges, no exact pricing).


        Accepts the same audience-filter triple as `GET /packages` so public

        discovery callers can narrow by audience type without authenticating.'
      operationId: list_media_kit_packages_media_kit_packages_get
      parameters:
      - name: layer
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Layer
      - name: featured_only
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Featured Only
      - name: audience_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Audience Type
      - name: audience_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Audience Id
      - name: audience_taxonomy_version
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Audience Taxonomy Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /media-kit/packages/{package_id}:
    get:
      tags:
      - Media Kit
      summary: Get Media Kit Package
      description: Get a single package with public view.
      operationId: get_media_kit_package_media_kit_packages__package_id__get
      parameters:
      - name: package_id
        in: path
        required: true
        schema:
          type: string
          title: Package Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /media-kit/search:
    post:
      tags:
      - Media Kit
      summary: Search Media Kit
      description: 'Search packages by keyword. Authenticated buyers get richer results.


        Per proposal §5.7, the scoring corpus now includes

        `audience_capabilities.standard_segment_ids` +

        `audience_capabilities.contextual_segment_ids` alongside keywords/tags

        -- a query mentioning a known IAB segment ID ranks packages that

        declare it higher than packages that don''t.


        The optional `audience_filter` body field restricts results to packages

        that match its type/id/version triple, parallel to `GET /packages`.'
      operationId: search_media_kit_media_kit_search_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Api-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MediaKitSearchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    AudienceFilterModel:
      properties:
        audience_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Audience Type
        audience_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Audience Id
        taxonomy_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Taxonomy Version
      type: object
      title: AudienceFilterModel
      description: 'Optional audience filter sub-object on `POST /media-kit/search`.


        Mirrors the query-param triple on `GET /packages`: type + id + version.

        When present, search results are restricted to packages whose

        `audience_capabilities` match. See proposal §5.7.'
    MediaKitSearchRequest:
      properties:
        query:
          type: string
          title: Query
        buyer_tier:
          type: string
          title: Buyer Tier
          default: public
        agency_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agency Id
        advertiser_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Advertiser Id
        audience_filter:
          anyOf:
          - $ref: '#/components/schemas/AudienceFilterModel'
          - type: 'null'
      type: object
      required:
      - query
      title: MediaKitSearchRequest
      description: Request to search packages.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError