openapi: 3.1.0
info:
  title: Motionworks API - Popcast Attention
  version: 0.1.0
  description: |
    Popcast Attention will show what is about to draw people to a US Census block group: the upcoming schedule of concerts, sports, conferences, festivals, community events, school sessions and civic or holiday dates, with expected attendance. Look ahead with `horizon`; look back with `window` on the history endpoint.

    **Coming soon.** This capability is on the Motionworks roadmap and is not yet available to call. The request and response shapes are published so you can plan an integration; they may change before launch.
  x-internal-notes: |
    Attention layer of The Conscience Stack (TF-101). Planned sources: Ticketmaster Discovery API (free tier), Eventbrite (stub), US federal holidays (static 2026–2030), school calendars (static, top-25 DMAs).
  contact: { name: Motionworks AI, url: https://mworks.com, email: api@mworks.com }

servers:
  - url: https://api2.mworks.com

tags:
  - name: attention
    description: "Upcoming events and calendar dates for a block group, with expected attendance. Coming soon."
    x-displayName: Attention

paths:
  /v2/popcast/attention/{fips}:
    get:
      operationId: getAttentionSignal
      summary: Read upcoming events
      description: |
        Will return the events scheduled in and around one block group over the next `horizon` days, with total expected attendance, a count by category and the peak day. Planned cost: 1 credit per call. Coming soon — not yet available to call.
      tags: [attention]
      x-motionworks-status: roadmap
      x-motionworks-roadmap-issue: "TF-101"
      x-motionworks-data-maturity: synthetic-only
      x-credit-cost: 1
      parameters:
        - $ref: '#/components/parameters/FipsParam'
        - name: horizon
          in: query
          schema: { type: integer, enum: [7, 14, 30], default: 14 }
          description: "Days ahead to include (7, 14 or 30)."
      responses:
        '200':
          description: Attention signal
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AttentionSignalResponse' }
        '404': { $ref: '#/components/responses/NotFound' }
        '400': { $ref: '#/components/responses/ValidationError' }

  /v2/popcast/attention/{fips}/history:
    get:
      operationId: getAttentionHistory
      summary: Read past event activity
      description: |
        Will return rolled-up past event activity for one block group — event counts, attendance and categories — over a 30- or 90-day window, with cursor pagination. Planned cost: 3 credits per call. Coming soon — not yet available to call.
      tags: [attention]
      x-motionworks-status: roadmap
      x-motionworks-roadmap-issue: "TF-101"
      x-motionworks-data-maturity: synthetic-only
      x-credit-cost: 3
      parameters:
        - $ref: '#/components/parameters/FipsParam'
        - name: window
          in: query
          schema: { type: integer, enum: [30, 90], default: 30 }
          description: Lookback window in days (30 or 90).
        - { name: cursor, in: query, schema: { type: string }, description: "Opaque cursor from the previous page." }
        - { name: limit, in: query, schema: { type: integer, maximum: 24 }, description: "Results per page." }
      responses:
        '200':
          description: Attention history
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AttentionHistoryResponse' }
  /v2/popcast/attention/batch:
    post:
      operationId: batchAttentionSignals
      summary: Read upcoming events for many block groups
      description: |
        Will return upcoming events for up to 100 block groups in one call. Planned cost: 100 credits per call. Coming soon — not yet available to call.
      tags: [attention]
      x-motionworks-status: roadmap
      x-motionworks-roadmap-issue: "TF-101"
      x-motionworks-data-maturity: synthetic-only
      x-credit-cost: 100
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AttentionBatchRequest' }
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AttentionBatchResponse' }
components:
  parameters:
    FipsParam:
      name: fips
      in: path
      required: true
      schema: { type: string, pattern: '^\d{12}$' }
      description: 12-digit US Census block group FIPS code.

  schemas:
    EventItem:
      type: object
      required: [id, name, category, start_time, source]
      properties:
        id: { type: string, description: "Unique id of the record." }
        name: { type: string, description: "Event name." }
        category: { type: string, enum: [concert, sports, conference, festival, community, school, civic, holiday], description: "Kind of event." }
        start_time: { type: string, format: date-time, description: "When the event starts (ISO 8601)." }
        end_time: { type: string, format: date-time, description: "When the event ends (ISO 8601), when known." }
        venue_name: { type: string, description: "Venue name." }
        venue_address: { type: string, description: "Venue street address." }
        latitude: { type: number, description: "Latitude (WGS84)." }
        longitude: { type: number, description: "Longitude (WGS84)." }
        expected_attendance: { type: integer, description: "Expected attendance, when known." }
        url: { type: string, format: uri, description: "Link to the event listing." }
        source: { type: string, description: "Which source supplied this record." }
      description: One scheduled event.
    AttentionPayload:
      type: object
      properties:
        events:
          type: array
          items: { $ref: '#/components/schemas/EventItem' }
          description: "The scheduled events, soonest first."
        total_expected_attendance: { type: integer, description: "Sum of expected attendance across the events." }
        categories: { type: object, additionalProperties: { type: integer }, description: "Count of items in each category, keyed by category." }
        peak_day: { type: string, nullable: true, description: "The day with the most expected attendance (`YYYY-MM-DD`), or `null`." }
      description: The events ahead and their summary.
    AttentionSignal:
      type: object
      required: [fips, signal_layer, horizon_days, period_end, refreshed_at, payload]
      properties:
        fips: { type: string, description: "12-digit US Census block group FIPS code." }
        signal_layer: { type: string, enum: [attention], description: "Which signal layer this record belongs to." }
        period_end: { type: string, description: "Last day of the period this record covers (`YYYY-MM-DD`)." }
        horizon_days: { type: integer, enum: [7, 14, 30], description: "How many days ahead the signal looks." }
        refreshed_at: { type: string, format: date-time, description: "When the signal was last refreshed (ISO 8601)." }
        data_quality: { type: string, enum: [high, medium, low], description: "Confidence in the signal: `high`, `medium` or `low`." }
        source_breakdown: { type: object, additionalProperties: { type: integer }, description: "How many records each contributing source supplied, keyed by source." }
        payload: { $ref: '#/components/schemas/AttentionPayload' }
      description: The forward-looking event signal for one block group.
    Meta:
      type: object
      properties:
        request_id: { type: string, description: "Unique id for this request. Quote it when contacting support." }
        credits_used: { type: integer, description: "Credits charged for this call." }
        product: { type: string, description: "The Motionworks product that served the call." }
        version: { type: string, description: "API version that served the call." }
        provenance: { type: object, additionalProperties: true, description: "Where the data came from and how mature it is." }
      description: Request metadata.
    AttentionSignalResponse:
      type: object
      properties:
        data: { $ref: '#/components/schemas/AttentionSignal' }
        meta: { $ref: '#/components/schemas/Meta' }
      description: One attention signal with request metadata.
    AttentionHistorySnapshot:
      type: object
      properties:
        fips: { type: string, description: "12-digit US Census block group FIPS code." }
        period_start: { type: string, description: "First day of the period this record covers (`YYYY-MM-DD`)." }
        period_end: { type: string, description: "Last day of the period this record covers (`YYYY-MM-DD`)." }
        window_days: { type: integer, description: "Length of the rolling window, in days." }
        event_count: { type: integer, description: "Events that took place in the window." }
        total_attendance: { type: integer, description: "Total attendance across those events." }
        categories: { type: object, additionalProperties: { type: integer }, description: "Count of items in each category, keyed by category." }
        data_quality: { type: string, description: "Confidence in the signal: `high`, `medium` or `low`." }
      description: Past event activity rolled up over one window.
    AttentionHistoryResponse:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/AttentionHistorySnapshot' }
          description: The list of results.
        pagination:
          type: object
          properties:
            cursor: { type: string, nullable: true, description: "Opaque cursor for the next page. Pass it back as `cursor` to continue; absent on the last page." }
            has_more: { type: boolean, description: "Whether another page follows." }
            total: { type: integer, description: "Total number of items in the window." }
          description: Paging information for the list.
        meta: { $ref: '#/components/schemas/Meta' }
      description: A page of history rollups with request metadata.
    AttentionBatchRequest:
      type: object
      required: [fips_codes]
      properties:
        fips_codes:
          type: array
          maxItems: 100
          items: { type: string, pattern: '^\d{12}$' }
          description: Block group FIPS codes to look up (12 digits each).
        horizon: { type: integer, enum: [7, 14, 30], description: "Days ahead to include (7, 14 or 30)." }
      description: Block groups to look up and how far ahead to look.
    AttentionBatchResponse:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/AttentionSignal' }
          description: The list of results.
        meta: { $ref: '#/components/schemas/Meta' }
      description: "One attention signal per requested block group, with request metadata."
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code: { type: string, description: "Stable machine-readable error code." }
            message: { type: string, description: "Human-readable explanation of the error." }
            status: { type: integer, description: "HTTP status code, repeated in the body." }
            request_id: { type: string, description: "Unique id for this request. Quote it when contacting support." }
          description: "The error: a stable `code`, a human-readable `message`, and the HTTP `status`."
      description: The standard error envelope.
  responses:
    NotFound:
      description: Not found
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ApiError' }
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ApiError' }
x-tagGroups:
  - name: Popcast Attention
    tags:
      - attention
x-customer-voice: true