openapi: 3.1.0
info:
  title: Popcast Attention API
  version: 0.1.0
  description: |
    Attention layer of The Conscience Stack. Forward-looking per-FIPS
    event schedule (concerts, sports, conferences, festivals, community
    events, school sessions, civic/holiday). Uses `horizon_days` for the
    single-FIPS endpoint and `window_days` (lookback) for history.

    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://docs.mworks.com
servers:
  - url: https://api.mworks.com
tags:
  - name: attention
    description: Block group attention signal endpoints
paths: {}
components:
  parameters:
    FipsParam:
      name: fips
      in: path
      required: true
      schema:
        type: string
        pattern: ^\d{12}$
  schemas:
    EventItem:
      type: object
      required:
        - id
        - name
        - category
        - start_time
        - source
      properties:
        id:
          type: string
        name:
          type: string
        category:
          type: string
          enum:
            - concert
            - sports
            - conference
            - festival
            - community
            - school
            - civic
            - holiday
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
        venue_name:
          type: string
        venue_address:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        expected_attendance:
          type: integer
        url:
          type: string
          format: uri
        source:
          type: string
    AttentionPayload:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventItem'
        total_expected_attendance:
          type: integer
        categories:
          type: object
          additionalProperties:
            type: integer
        peak_day:
          type: string
          nullable: true
    AttentionSignal:
      type: object
      required:
        - fips
        - signal_layer
        - horizon_days
        - period_end
        - refreshed_at
        - payload
      properties:
        fips:
          type: string
        signal_layer:
          type: string
          enum:
            - attention
        period_end:
          type: string
        horizon_days:
          type: integer
          enum:
            - 7
            - 14
            - 30
        refreshed_at:
          type: string
          format: date-time
        data_quality:
          type: string
          enum:
            - high
            - medium
            - low
        source_breakdown:
          type: object
          additionalProperties:
            type: integer
        payload:
          $ref: '#/components/schemas/AttentionPayload'
    Meta:
      type: object
      properties:
        request_id:
          type: string
        credits_used:
          type: integer
        product:
          type: string
        version:
          type: string
        provenance:
          type: object
          additionalProperties: true
    AttentionSignalResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AttentionSignal'
        meta:
          $ref: '#/components/schemas/Meta'
    AttentionHistorySnapshot:
      type: object
      properties:
        fips:
          type: string
        period_start:
          type: string
        period_end:
          type: string
        window_days:
          type: integer
        event_count:
          type: integer
        total_attendance:
          type: integer
        categories:
          type: object
          additionalProperties:
            type: integer
        data_quality:
          type: string
    AttentionHistoryResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AttentionHistorySnapshot'
        pagination:
          type: object
          properties:
            cursor:
              type: string
              nullable: true
            has_more:
              type: boolean
            total:
              type: integer
        meta:
          $ref: '#/components/schemas/Meta'
    AttentionBatchRequest:
      type: object
      required:
        - fips_codes
      properties:
        fips_codes:
          type: array
          maxItems: 100
          items:
            type: string
            pattern: ^\d{12}$
        horizon:
          type: integer
          enum:
            - 7
            - 14
            - 30
    AttentionBatchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AttentionSignal'
        meta:
          $ref: '#/components/schemas/Meta'
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            status:
              type: integer
            request_id:
              type: string
  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'