openapi: 3.1.0
info:
  title: PodDrop API
  version: "1.0.0"
  description: |
    Two-sided marketplace for host-read podcast ads. Advertisers upload 30-second
    scripts with target criteria and fund escrow; creators browse, claim, deliver,
    and get paid on verification.
  contact:
    url: https://poddrop.arflow.io
servers:
  - url: https://poddrop.arflow.io
    description: Production
paths:
  /api/poddrop/advertisers/register:
    post:
      summary: Register a new advertiser
      operationId: registerAdvertiser
      tags: [advertisers]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AdvertiserRegistration"
      responses:
        "201":
          description: Advertiser registered
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Advertiser"
  /api/poddrop/scripts:
    post:
      summary: Upload a host-read ad script and fund escrow
      operationId: createScript
      tags: [scripts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScriptUpload"
      responses:
        "201":
          description: Script created, escrow funded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Script"
  /api/poddrop/browse:
    get:
      summary: Browse available scripts for creators to claim
      operationId: browseScripts
      tags: [marketplace]
      parameters:
        - in: query
          name: category
          schema: { type: string }
          description: Filter by category (e.g. tech, finance, health)
        - in: query
          name: min_payout
          schema: { type: number }
          description: Minimum per-read payout in USD
      responses:
        "200":
          description: List of claimable scripts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Script"
  /api/poddrop/scripts/{id}/claim:
    post:
      summary: Creator claims a script for delivery
      operationId: claimScript
      tags: [marketplace]
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        "201":
          description: Claim created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Claim"
  /api/poddrop/claims/{id}:
    get:
      summary: Get claim status (delivery, verification, payout)
      operationId: getClaim
      tags: [marketplace]
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Claim detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Claim"
components:
  schemas:
    AdvertiserRegistration:
      type: object
      required: [company_name, contact_email]
      properties:
        company_name: { type: string }
        contact_email: { type: string, format: email }
        website: { type: string, format: uri }
    Advertiser:
      type: object
      properties:
        id: { type: string }
        company_name: { type: string }
        contact_email: { type: string, format: email }
        created_at: { type: string, format: date-time }
    ScriptUpload:
      type: object
      required: [advertiser_id, title, body, payout_per_read, target_category]
      properties:
        advertiser_id: { type: string }
        title: { type: string }
        body: { type: string, description: "30-second host-read script text" }
        payout_per_read: { type: number, description: "USD paid per verified read" }
        target_category: { type: string }
        min_show_downloads: { type: integer }
    Script:
      type: object
      properties:
        id: { type: string }
        advertiser_id: { type: string }
        title: { type: string }
        body: { type: string }
        payout_per_read: { type: number }
        target_category: { type: string }
        status:
          type: string
          enum: [open, claimed, delivered, verified, disputed, paid]
        created_at: { type: string, format: date-time }
    Claim:
      type: object
      properties:
        id: { type: string }
        script_id: { type: string }
        creator_id: { type: string }
        show_name: { type: string }
        status:
          type: string
          enum: [claimed, delivered, verified, disputed, paid, refunded]
        delivery_url: { type: string, format: uri }
        created_at: { type: string, format: date-time }