vocabulary: "1.0.0"

info:
  provider: "Albertsons"
  description: "Unified vocabulary for Albertsons Media Collective API covering retail media campaign management, audience targeting, performance analytics, and reporting."
  created: "2026-04-19"
  modified: "2026-04-19"

operational:
  apis:
    - name: Albertsons Media Collective API
      namespace: retail-media-api
      version: "1.0"
      baseUrl: https://api.albertsons.com
      status: active

  resources:
    - name: campaigns
      description: Advertising campaigns on the Albertsons Media Collective platform.
      api: retail-media-api
      actions:
        - list
        - create
        - get
    - name: performance
      description: Near-real-time campaign performance metrics including impressions, clicks, conversions, and ROAS.
      api: retail-media-api
      actions:
        - list
    - name: audiences
      description: Audience targeting segments derived from Albertsons shopper purchase behavior.
      api: retail-media-api
      actions:
        - list
    - name: reports
      description: Custom performance reports for advertising campaigns.
      api: retail-media-api
      actions:
        - generate

  actions:
    - name: list
      description: Retrieve a collection of resources with optional filtering and pagination.
      httpMethod: GET
      pattern: read
    - name: create
      description: Create a new resource with specified parameters.
      httpMethod: POST
      pattern: write
    - name: get
      description: Retrieve a single resource by unique identifier.
      httpMethod: GET
      pattern: read
    - name: generate
      description: Trigger generation of a custom artifact such as a report.
      httpMethod: POST
      pattern: query

  schemas:
    core:
      - name: Campaign
        description: An advertising campaign with status, budget, and targeting configuration.
        keyProperties:
          - campaignId
          - name
          - status
          - budget
          - startDate
          - endDate
      - name: PerformanceMetric
        description: Performance data point for a campaign over a time period.
        keyProperties:
          - date
          - campaignId
          - impressions
          - clicks
          - conversions
          - spend
          - roas
          - clickThroughRate
      - name: Audience
        description: Audience targeting segment based on shopper behavior.
        keyProperties:
          - audienceId
          - name
          - description
          - size
          - category
      - name: ReportRequest
        description: Parameters for generating a custom performance report.
        keyProperties:
          - campaignIds
          - startDate
          - endDate
          - dimensions
          - metrics
          - format
      - name: ReportResponse
        description: Result of a report generation request.
        keyProperties:
          - reportId
          - status
          - createdAt
          - downloadUrl

  parameters:
    pagination:
      - name: limit
        description: Maximum number of results to return.
      - name: offset
        description: Number of results to skip for pagination.
    identifiers:
      - name: campaignId
        description: Unique identifier for an advertising campaign.
    filters:
      - name: status
        description: Filter by campaign status.
      - name: startDate
        description: Start date for date-range filtering.
      - name: endDate
        description: End date for date-range filtering.
      - name: granularity
        description: Time granularity for metrics aggregation.
      - name: category
        description: Product category for audience filtering.

  enums:
    campaignStatus:
      - active
      - paused
      - completed
      - draft
    reportStatus:
      - pending
      - processing
      - completed
      - failed
    reportFormat:
      - json
      - csv
    metricsGranularity:
      - daily
      - weekly
      - monthly

  authentication:
    schemes:
      - type: bearer
        description: Bearer token authentication via Azure AD OAuth2.
        apis:
          - retail-media-api

capability:
  workflows:
    - name: Retail Media Advertising
      file: capabilities/retail-media-advertising.yaml
      description: Unified retail media advertising workflow for campaign management, audience targeting, performance analytics, and reporting.
      apisCombined:
        - retail-media-api
      toolCount: 6
      personas:
        - Brand Manager
        - Media Planner
      domains:
        - Retail Media
        - Advertising

  personas:
    - id: brand-manager
      name: Brand Manager
      description: Manages advertising campaigns and budgets on behalf of consumer brands advertising in the Albertsons network.
      workflows:
        - Retail Media Advertising
    - id: media-planner
      name: Media Planner
      description: Plans and optimizes retail media campaigns, analyzes performance metrics, and generates reports for advertising clients.
      workflows:
        - Retail Media Advertising

  domains:
    - name: Retail Media
      description: Digital advertising within retail environments, leveraging shopper purchase data for targeting.
      resources:
        - campaigns
        - audiences
        - performance
        - reports
    - name: Advertising
      description: Campaign creation, management, and performance optimization for brands.
      resources:
        - campaigns
        - reports

  namespaces:
    - name: retail-media-api
      type: consumed
      baseUri: https://api.albertsons.com
    - name: albertsons-advertising-api
      type: rest-exposed
      port: 8080
    - name: albertsons-advertising-mcp
      type: mcp-exposed
      port: 9090

  binds:
    - name: ALBERTSONS_API_TOKEN
      description: Bearer token for Albertsons Media Collective API authentication.
      workflows:
        - Retail Media Advertising

crossReference:
  - resource: campaigns
    operations:
      - listCampaigns
      - createCampaign
      - getCampaign
    workflows:
      - Retail Media Advertising
    personas:
      - Brand Manager
      - Media Planner
  - resource: performance
    operations:
      - listPerformanceMetrics
    workflows:
      - Retail Media Advertising
    personas:
      - Brand Manager
      - Media Planner
  - resource: audiences
    operations:
      - listAudiences
    workflows:
      - Retail Media Advertising
    personas:
      - Media Planner
  - resource: reports
    operations:
      - generateReport
    workflows:
      - Retail Media Advertising
    personas:
      - Brand Manager
      - Media Planner