openapi: 3.1.0
info:
  title: Albertsons Media Collective Audiences API
  description: The Albertsons Media Collective API enables advertisers to integrate with Albertsons retail media network for campaign management and performance analytics. The API provides near-real-time access to campaign performance data, allowing advertisers to bring data into their own measurement models for analysis. Supported via the Albertsons developer portal built on Microsoft Azure API Management.
  version: '1.0'
  contact:
    name: Albertsons Media Collective
    url: https://portal-prod.apim.azwestus.stratus.albertsons.com/
  x-generated-from: documentation
servers:
- url: https://api.albertsons.com
  description: Production API server
tags:
- name: Audiences
  description: Manage audience targeting segments for retail media campaigns.
paths:
  /audiences:
    get:
      operationId: listAudiences
      summary: Albertsons Media Collective List Audiences
      description: Retrieves a list of audience segments available for campaign targeting on the Albertsons Media Collective, based on shopper purchase behavior and demographic data.
      tags:
      - Audiences
      parameters:
      - name: category
        in: query
        description: Filter audiences by product category.
        schema:
          type: string
        example: grocery
      - name: limit
        in: query
        description: Maximum number of audience segments to return.
        schema:
          type: integer
          default: 20
          maximum: 100
        example: 20
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Audience segments retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudienceListResponse'
              examples:
                ListAudiences200Example:
                  summary: Default listAudiences 200 response
                  x-microcks-default: true
                  value:
                    audiences:
                    - audienceId: aud-001
                      name: Organic Food Buyers
                      description: Shoppers with high organic product purchase frequency
                      size: 2500000
                      category: grocery
                    total: 1
                    limit: 20
                    offset: 0
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ErrorResponse:
      type: object
      title: Error Response
      description: Standard error response object.
      properties:
        error:
          type: string
          description: Error code identifier.
          example: UNAUTHORIZED
        message:
          type: string
          description: Human-readable error message.
          example: Invalid or missing bearer token.
        statusCode:
          type: integer
          description: HTTP status code.
          example: 401
    AudienceListResponse:
      type: object
      title: Audience List Response
      description: Paginated list of audience segments.
      properties:
        audiences:
          type: array
          items:
            $ref: '#/components/schemas/Audience'
          description: Array of audience segment objects.
        total:
          type: integer
          description: Total number of audience segments available.
          example: 150
        limit:
          type: integer
          description: Maximum number of results returned.
          example: 20
        offset:
          type: integer
          description: Number of results skipped.
          example: 0
    Audience:
      type: object
      title: Audience
      description: An audience targeting segment based on shopper behavior.
      properties:
        audienceId:
          type: string
          description: Unique identifier of the audience segment.
          example: aud-001
        name:
          type: string
          description: Display name of the audience segment.
          example: Organic Food Buyers
        description:
          type: string
          description: Description of the audience segment criteria.
          example: Shoppers with high organic product purchase frequency
        size:
          type: integer
          description: Approximate number of shoppers in the audience segment.
          example: 2500000
        category:
          type: string
          description: Product category associated with the audience.
          example: grocery
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication via Azure AD OAuth2.