# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Audience Segments Permission Taxonomies API
  version: 1.0.0
extends: openapi/mediamath-permission-taxonomies-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/audience_segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List my permission taxonomies
      effect: read
      questions:
      - Which permission taxonomies have I published as a data provider?
      - Can I search my taxonomies for segments with a name like a keyword?
      instructions:
      - text: List all my permission taxonomies.
      - text: Find audience segments in my taxonomies matching {q}.
        slots:
          q: query.q
      method: generated
      generated: '2026-10-01'
- target: $.paths['/audience_segments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a permission taxonomy
      effect: write
      questions:
      - How do I publish a new audience segment taxonomy with permissions as a data vendor?
      - Can I control which organizations or advertisers can use my segments?
      instructions:
      - text: Create a permission taxonomy {taxonomy} for vendor {vendor_id} with permissions {permissions}.
        slots:
          taxonomy: requestBody.taxonomy
          vendor_id: requestBody.vendor_id
          permissions: requestBody.permissions
      - text: Publish a new segment taxonomy for vendor {vendor_id} granting {permissions}, defined as {taxonomy}.
        slots:
          vendor_id: requestBody.vendor_id
          permissions: requestBody.permissions
          taxonomy: requestBody.taxonomy
      method: generated
      generated: '2026-10-01'
- target: $.paths['/audience_segments/grants/{vendor_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: List entities granted to my data vendor
      effect: read
      questions:
      - Which organizations, agencies or advertisers can I grant my data to?
      - How do I find the entity IDs my vendor account has access to?
      instructions:
      - text: List the entity grants for vendor {vendor_id}.
        slots:
          vendor_id: path.vendor_id
      - text: Show which organizations and advertisers vendor {vendor_id} can permission.
        slots:
          vendor_id: path.vendor_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/audience_segments/{taxonomy_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a permission taxonomy
      effect: read
      questions:
      - How do I review the permissions and segments in one of my taxonomies?
      - Can I fetch a taxonomy by the ID I got when creating it?
      instructions:
      - text: Get permission taxonomy {taxonomy_id}.
        slots:
          taxonomy_id: path.taxonomy_id
      - text: Show the segments and permissions in taxonomy {taxonomy_id}.
        slots:
          taxonomy_id: path.taxonomy_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/audience_segments/{taxonomy_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a permission taxonomy
      effect: write
      questions:
      - How do I add or remove segments in an existing taxonomy?
      - Do I have to resend the whole taxonomy when I change permissions?
      instructions:
      - text: Update taxonomy {taxonomy_id} for audience vendor {audience_vendor_id} with tree {taxonomy}.
        slots:
          taxonomy_id: path.taxonomy_id
          audience_vendor_id: requestBody.audience_vendor_id
          taxonomy: requestBody.taxonomy
      - text: Change the permissions on taxonomy {taxonomy_id} to {permissions}, resending tree {taxonomy} for vendor {audience_vendor_id}.
        slots:
          taxonomy_id: path.taxonomy_id
          permissions: requestBody.permissions
          taxonomy: requestBody.taxonomy
          audience_vendor_id: requestBody.audience_vendor_id
      method: generated
      generated: '2026-10-01'