openapi: 3.2.0
info:
  title: Ad Buyer Agent Bookings API
  description: Automated advertising buyer agent using CrewAI and IAB OpenDirect 2.1. Orchestrates budget allocation, inventory research, recommendation consolidation, and deal booking against seller agent APIs.
  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: Bookings
  description: Campaign booking workflow lifecycle
paths:
  /bookings:
    post:
      tags:
      - Bookings
      summary: Create Booking
      description: 'Start a new booking workflow.


        Creates a background job that runs the full booking flow:

        1. Budget allocation

        2. Inventory research

        3. Recommendation consolidation

        4. (Optional) Automatic approval


        Use GET /bookings/{job_id} to check status.'
      operationId: create_booking_bookings_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Bookings
      summary: List Bookings
      description: List all booking jobs.
      operationId: list_bookings_bookings_get
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Bookings Bookings Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /bookings/{job_id}:
    get:
      tags:
      - Bookings
      summary: Get Booking Status
      description: Get status of a booking workflow.
      operationId: get_booking_status_bookings__job_id__get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingStatus'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /bookings/{job_id}/approve:
    post:
      tags:
      - Bookings
      summary: Approve Recommendations
      description: 'Approve specific recommendations for booking.


        Call this endpoint after the job reaches ''awaiting_approval'' status.

        Pass the product IDs you want to approve for booking.'
      operationId: approve_recommendations_bookings__job_id__approve_post
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApprovalRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Approve Recommendations Bookings  Job Id  Approve Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /bookings/{job_id}/approve-all:
    post:
      tags:
      - Bookings
      summary: Approve All Recommendations
      description: Approve all recommendations for booking.
      operationId: approve_all_recommendations_bookings__job_id__approve_all_post
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Approve All Recommendations Bookings  Job Id  Approve All Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CampaignBrief:
      properties:
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
        objectives:
          items:
            type: string
          type: array
          minItems: 1
          title: Objectives
        budget:
          type: number
          exclusiveMinimum: 0.0
          title: Budget
        start_date:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          title: Start Date
        end_date:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          title: End Date
        target_audience:
          additionalProperties: true
          type: object
          title: Target Audience
        kpis:
          additionalProperties: true
          type: object
          title: Kpis
        channels:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Channels
      type: object
      required:
      - name
      - objectives
      - budget
      - start_date
      - end_date
      - target_audience
      title: CampaignBrief
      description: Campaign brief for booking.
    BookingResponse:
      properties:
        job_id:
          type: string
          title: Job Id
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
      type: object
      required:
      - job_id
      - status
      - message
      title: BookingResponse
      description: Response from booking creation.
    BookingStatus:
      properties:
        job_id:
          type: string
          title: Job Id
        status:
          type: string
          title: Status
        progress:
          type: number
          title: Progress
        budget_allocations:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Budget Allocations
        recommendations:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Recommendations
        booked_lines:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Booked Lines
        errors:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Errors
        created_at:
          type: string
          title: Created At
        updated_at:
          type: string
          title: Updated At
      type: object
      required:
      - job_id
      - status
      - progress
      - created_at
      - updated_at
      title: BookingStatus
      description: Status of a booking job.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BookingRequest:
      properties:
        brief:
          $ref: '#/components/schemas/CampaignBrief'
        auto_approve:
          type: boolean
          title: Auto Approve
          description: Automatically approve all recommendations
          default: false
      type: object
      required:
      - brief
      title: BookingRequest
      description: Request to start a booking workflow.
    ApprovalRequest:
      properties:
        approved_product_ids:
          items:
            type: string
          type: array
          title: Approved Product Ids
      type: object
      required:
      - approved_product_ids
      title: ApprovalRequest
      description: Request to approve recommendations.
    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