openapi: 3.1.0
info:
  title: Scenarios
  version: 0.2.0
  description: |
    The campaign scenario asset library: create, browse, edit, and archive
    the campaign scenarios you intend to analyze. Scenarios is Motionworks'
    asset-management surface for scenario-based products — Campaign is the
    first — served by `mw-api-scenarios`. Paid measurement (purchase, poll,
    report) is a separate surface at `/v2/viewcast/*`, served by a new
    `mw-api-viewcast-select` worker (see `viewcast-select.yaml`), kept
    separate from the live `mw-api-viewcast` worker for blast-radius
    isolation.

    A campaign scenario asset moves through five lifecycle states: `draft`
    (only the asset exists, fully editable), `queued` (a measurement has
    been purchased and results are pending — still editable), `in_flight`
    (the campaign's flight is still active and results are re-pulled
    periodically — not final, no longer editable), `completed` (every
    measure is final and the flight has ended — retained permanently and
    cannot be edited or deleted), and `failed` (a problem occurred with the
    measurement — the purchase is refunded in full and the asset stays
    editable, so you can fix the issue and retry in place).

    Authenticate with an org-scoped API key (`X-API-Key: mw_…`). Every call
    on this surface costs 1 credit (`scenario_campaign_crud`).
  contact:
    name: Motionworks AI
    url: https://mworks.com
    email: api@mworks.com
servers:
  - url: https://api2.mworks.com/v2
    description: Production (not yet serving this path)
security:
  - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header
  schemas:
    CampaignAssetState:
      type: string
      enum:
        - draft
        - queued
        - in_flight
        - completed
        - failed
      description: |
        `draft` — only the asset exists, fully editable.
        `queued` — a measurement has been purchased, results pending; still editable.
        `in_flight` — the campaign's flight is still active; results are re-pulled
        periodically and are not yet final. No longer editable.
        `completed` — every measure is final and the flight has ended; the asset
        and its report are retained permanently and cannot be edited or deleted.
        `failed` — a problem occurred with the measurement; the purchase is
        refunded in full and the asset stays editable and deletable, so you can
        fix the issue and retry in place.
    CampaignRef:
      type: object
      properties:
        name:
          type: string
        reference:
          type: string
      description: Your own name/reference for the campaign, echoed back unchanged.
    CampaignFlight:
      type: object
      required:
        - start_date
        - end_date
      properties:
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
      description: |
        The campaign's overall active period. A spot with no `windows`
        inherits this envelope in full.
    CampaignSpotWindow:
      type: object
      required:
        - start_date
        - end_date
      properties:
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
      description: One contiguous active period for one spot.
    CampaignSpot:
      type: object
      required:
        - display_id
      properties:
        display_id:
          type: string
          description: |
            The Motionworks-issued identifier for the physical display this
            spot runs on.
        customer_spot_id:
          type: string
          description: Your own reference for this spot, echoed back unchanged.
        windows:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CampaignSpotWindow'
          description: |
            This spot's own active windows. Omit to inherit the campaign's
            `flight` envelope. Several entries model a rotating flight.
      description: One spot in the campaign — one advertisement on one display.
    CampaignCohort:
      type: object
      required:
        - geography_ids
        - customer_segment_ids
        - customer_base_segment_id
      properties:
        geography_ids:
          type: array
          minItems: 1
          items:
            type: string
          description: |
            Geography ids for the requested market geography. More than one
            element defines a market group.
        customer_segment_ids:
          type: array
          minItems: 1
          items:
            type: integer
          description: One or more target audience segment ids (multi-audience).
        customer_base_segment_id:
          type: integer
          description: Id of the base segment every target segment is measured against.
        measures_release:
          type: integer
          description: Version pin for reproducible results across runs.
      description: The market geography and audience to measure.
    CampaignCustomer:
      type: object
      required:
        - customer_id
        - customer_name
        - customer_scenario_id
        - customer_scenario_name
      properties:
        customer_id:
          type: integer
        customer_name:
          type: string
        customer_scenario_id:
          type: string
        customer_scenario_name:
          type: string
        customer_scenario_info:
          type: string
      description: Your own scenario identifiers, echoed back unchanged.
    CampaignAsset:
      type: object
      required:
        - asset_id
        - org_id
        - state
        - flight
        - spots
        - cohort
        - customer
        - created_at
        - updated_at
      properties:
        asset_id:
          type: string
          description: The one identifier you need for this campaign, minted at creation.
        org_id:
          type: string
        state:
          $ref: '#/components/schemas/CampaignAssetState'
        campaign:
          $ref: '#/components/schemas/CampaignRef'
        flight:
          $ref: '#/components/schemas/CampaignFlight'
        spots:
          type: array
          minItems: 1
          maxItems: 2000
          items:
            $ref: '#/components/schemas/CampaignSpot'
        cohort:
          $ref: '#/components/schemas/CampaignCohort'
        customer:
          $ref: '#/components/schemas/CampaignCustomer'
        last_measured_at:
          type: string
          format: date-time
          nullable: true
          description: Date of the last measurement pull. Populated only while/after `in_flight`.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      description: A campaign asset in your organization's library.
    CampaignAssetCreateRequest:
      type: object
      required:
        - flight
        - spots
        - cohort
        - customer
      properties:
        campaign:
          $ref: '#/components/schemas/CampaignRef'
        flight:
          $ref: '#/components/schemas/CampaignFlight'
        spots:
          type: array
          minItems: 1
          maxItems: 2000
          items:
            $ref: '#/components/schemas/CampaignSpot'
        cohort:
          $ref: '#/components/schemas/CampaignCohort'
        customer:
          $ref: '#/components/schemas/CampaignCustomer'
    CampaignAssetPatchRequest:
      type: object
      properties:
        campaign:
          $ref: '#/components/schemas/CampaignRef'
        flight:
          $ref: '#/components/schemas/CampaignFlight'
        spots:
          type: array
          minItems: 1
          maxItems: 2000
          items:
            $ref: '#/components/schemas/CampaignSpot'
        cohort:
          $ref: '#/components/schemas/CampaignCohort'
        customer:
          $ref: '#/components/schemas/CampaignCustomer'
      description: |
        Any field may change while the asset is `draft`, `queued`, or
        `failed` — no field-level restriction. Rejected (400) once the
        asset is `in_flight` or `completed`.
    CampaignAssetSummary:
      type: object
      required:
        - by_state
        - total
      properties:
        by_state:
          type: object
          required:
            - draft
            - queued
            - in_flight
            - completed
            - failed
          properties:
            draft:
              type: integer
            queued:
              type: integer
            in_flight:
              type: integer
            completed:
              type: integer
            failed:
              type: integer
        total:
          type: integer
    Pagination:
      type: object
      properties:
        cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
        total:
          type: integer
    Provenance:
      type: object
      properties:
        source:
          type: string
        source_doc:
          type: string
          format: uri
        methodology_version:
          type: string
        data_vintage:
          type: string
          format: date
        data_freshness:
          type: string
          enum:
            - hourly
            - daily
            - weekly
            - monthly
            - annually
            - on-demand
            - static
        data_latency_days:
          type: integer
        data_maturity:
          type: string
          enum:
            - production
            - research-preview
            - synthetic-only
            - roadmap
    Meta:
      type: object
      properties:
        request_id:
          type: string
        credits_used:
          type: integer
        credits_remaining:
          type: integer
        product:
          type: string
        version:
          type: string
        provenance:
          $ref: '#/components/schemas/Provenance'
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            status:
              type: integer
            request_id:
              type: string
            product:
              type: string
            docs_url:
              type: string
paths: {}
x-tagGroups:
  - name: Campaigns
    tags:
      - Assets
tags:
  - name: Assets
    description: |
      Create, browse, edit, and archive campaign assets. PROPOSAL STAGE —
      not live, no worker exists.